feat: use changed tick to determine whether we should parse instead of event

## Details

For the main event based update trigger rather than handling some
special events as changes all the builtin events are now handled as
non-changes. Instead in these cases we compare the `changedtick` between
the last time we computed `extmarks` and now and if it is different
(meaning the buffer has been modified) only then do we re-compute `extmarks`.

The `ui.update` method still takes a 4th boolean argument, but it is now
called `force` as the meaning of it is to force an update even if no
change to the buffer has been detected.

The user configured `change_events` will result in `force` being set
since some events that do not produce buffer changes may still require
us to re-compute `extmarks` like an example where `diagnostics` were
used to do some of the rendering.

We also set `force` on `WinResized` events as those do not change the
buffer but may result in a different rendering output since width can
impact some `extmarks`. Also for user commands and initial render.

What this allows us to do is avoid re-computing marks for things like
mode changes that do not modify the buffer. To support this clearing was
modified to delete each `extmark` individually rather than clearing the
entire namespace for the buffer, we can then re-create them later
without doing a whole parse & render cycle which is the most time
consuming task this plugin does. Before we needed to always re-compute
on mode changes since the user can have made text changes in insert
mode, but now this is fully handled by the `changedtick` value.

Other changes:

- do not hide any marks in `command` mode
- add `trace` and `warn` level logs to match neovim levels
- make most logs that were `debug` level now `trace` level and update docs
- unhandled log level from user results in no logs instead of all
- when logging nodes include the length of the text rather than all the
  text in the node (easier to read), also include the TSNode type

Author: MeanderingProgrammer

benches/medium_spec.lua

@@ -11,7 +11,7 @@ describe('medium.md', function()
         util.less_than(util.move_down(3), 0.5)
         util.num_marks(base_marks + 2)
 
-        util.less_than(util.insert_mode(), 5)
+        util.less_than(util.modify(), 2.5)
         util.num_marks(base_marks + 2)
     end)
 end)

benches/medium_table_spec.lua

@@ -11,7 +11,7 @@ describe('medium-table.md', function()
         util.less_than(util.move_down(1), 0.5)
         util.num_marks(base_marks + 1)
 
-        util.less_than(util.insert_mode(), 15)
+        util.less_than(util.modify(), 7.5)
         util.num_marks(base_marks + 1)
     end)
 end)

benches/readme_spec.lua

@@ -11,7 +11,7 @@ describe('README.md', function()
         util.less_than(util.move_down(1), 0.5)
         util.num_marks(base_marks + 2)
 
-        util.less_than(util.insert_mode(), 10)
+        util.less_than(util.modify(), 5)
         util.num_marks(base_marks + 2)
     end)
 end)

benches/util.lua

@@ -7,7 +7,10 @@ local M = {}
 ---@return number
 function M.setup(file)
     return M.time(function()
-        require('render-markdown').setup({ debounce = 0 })
+        require('render-markdown').setup({
+            debounce = 0,
+            change_events = { 'TextChanged' },
+        })
         vim.cmd('e ' .. file)
     end)
 end
@@ -16,16 +19,17 @@ end
 ---@return number
 function M.move_down(n)
     return M.time(function()
-        M.feed(('%dj'):format(n))
-        -- Unsure why, but the CursorMoved event needs to be triggered manually
+        local row, col = unpack(vim.api.nvim_win_get_cursor(0))
+        vim.api.nvim_win_set_cursor(0, { row + n, col })
+        -- CursorMoved event needs to be triggered manually
         vim.api.nvim_exec_autocmds('CursorMoved', {})
     end)
 end
 
 ---@return number
-function M.insert_mode()
+function M.modify()
     return M.time(function()
-        M.feed('i')
+        vim.api.nvim_exec_autocmds('TextChanged', {})
     end)
 end
 
@@ -40,13 +44,6 @@ function M.time(callback)
     return (end_time - start_time) / 1e+6
 end
 
----@private
----@param keys string
-function M.feed(keys)
-    local escape = vim.api.nvim_replace_termcodes(keys, true, false, true)
-    vim.api.nvim_feedkeys(escape, 'nx', false)
-end
-
 ---@param actual number
 ---@param max number
 function M.less_than(actual, max)

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*         For NVIM v0.11.1        Last change: 2025 May 29
+*render-markdown.txt*         For NVIM v0.11.1        Last change: 2025 May 30
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*

doc/troubleshooting.md

@@ -39,7 +39,7 @@ to some default the author prefers. So the settings you think you are using are
 necessarily the only ones be used.
 
 Run `:RenderMarkdown config`, which will output only the non-default values being
-used, you might be surprised what you find.
+used, you might be surprised by what you find.
 
 ## Validate Parse Tree
 
@@ -92,7 +92,7 @@ Run `:InspectTree` which should output the following:
 If this is not what you see you likely need to update `nvim-treesitter` and your
 treesitter parsers.
 
-## Generate Debug Logs
+## Generate Trace Logs
 
 If all else fails hopefully the logs can provide some insight. This plugin
 ships with logging, however it only includes errors by default.
@@ -105,11 +105,11 @@ Use the same file from [Validate Parse Tree](#validate-parse-tree).
 
 ### 2) Update Log Level
 
-Change plugin configuration to output `debug` logs:
+Change plugin configuration to output `trace` logs:
 
 ```lua
 require('render-markdown').setup({
-    log_level = 'debug',
+    log_level = 'trace',
 })
 ```
 

lua/render-markdown/core/handlers.lua

@@ -53,22 +53,22 @@ end
 ---@param language string
 ---@return render.md.Mark[]
 function M.tree(context, ctx, language)
-    log.buf('debug', 'Language', ctx.buf, language)
+    log.buf('trace', 'Language', ctx.buf, language)
     if not context.view:overlaps(ctx.root) then
         return {}
     end
     local marks = {} ---@type render.md.Mark[]
     local custom = M.config.custom[language]
     if custom then
-        log.buf('debug', 'Handler', ctx.buf, 'custom')
+        log.buf('trace', 'Handler', ctx.buf, 'custom')
         vim.list_extend(marks, custom.parse(ctx))
         if not custom.extends then
             return marks
         end
     end
     local builtin = M.builtin[language]
     if builtin then
-        log.buf('debug', 'Handler', ctx.buf, 'builtin')
+        log.buf('trace', 'Handler', ctx.buf, 'builtin')
         vim.list_extend(marks, builtin.parse(ctx))
     end
     return marks

lua/render-markdown/core/log.lua

@@ -10,12 +10,14 @@ local Env = require('render-markdown.lib.env')
 ---@field level render.md.log.Level
 ---@field runtime boolean
 
----@enum render.md.log.Level
+---@enum (key) render.md.log.Level
 local Level = {
-    debug = 'debug',
-    info = 'info',
-    error = 'error',
-    off = 'off',
+    trace = 0,
+    debug = 1,
+    info = 2,
+    warn = 3,
+    error = 4,
+    off = 5,
 }
 
 ---@class render.md.Log
@@ -74,9 +76,10 @@ end
 ---@param capture string
 ---@param node render.md.Node
 function M.node(capture, node)
-    M.add('debug', 'Node', {
+    M.add('trace', 'Node', {
         capture = capture,
-        text = node.text,
+        type = node.type,
+        length = #node.text,
         rows = { node.start_row, node.end_row },
         cols = { node.start_col, node.end_col },
     })
@@ -138,19 +141,9 @@ end
 
 ---@private
 ---@param level render.md.log.Level
----@return integer
+---@return number
 function M.level(level)
-    if level == Level.debug then
-        return 1
-    elseif level == Level.info then
-        return 2
-    elseif level == Level.error then
-        return 3
-    elseif level == Level.off then
-        return 4
-    else
-        return 0
-    end
+    return Level[level] or math.huge
 end
 
 ---@private

lua/render-markdown/core/manager.lua

@@ -119,15 +119,24 @@ function M.attach(buf)
         'CmdlineChanged',
         'CursorHold',
         'CursorMoved',
+        'DiffUpdated',
+        'ModeChanged',
+        'TextChanged',
         'WinScrolled',
     }
-    local change_events = { 'DiffUpdated', 'ModeChanged', 'TextChanged' }
-    vim.list_extend(change_events, M.config.change_events)
     if config.resolved:render('i') then
-        vim.list_extend(events, { 'CursorHoldI', 'CursorMovedI' })
-        vim.list_extend(change_events, { 'TextChangedI' })
+        events[#events + 1] = 'CursorHoldI'
+        events[#events + 1] = 'CursorMovedI'
+        events[#events + 1] = 'TextChangedI'
     end
-    vim.api.nvim_create_autocmd(vim.list_extend(events, change_events), {
+    local force = M.config.change_events
+    for _, event in ipairs(force) do
+        if not vim.tbl_contains(events, event) then
+            events[#events + 1] = event
+        end
+    end
+
+    vim.api.nvim_create_autocmd(events, {
         group = M.group,
         buffer = buf,
         callback = function(args)
@@ -140,7 +149,7 @@ function M.attach(buf)
                 return
             end
             local event = args.event
-            ui.update(buf, win, event, vim.tbl_contains(change_events, event))
+            ui.update(buf, win, event, vim.tbl_contains(force, event))
         end,
     })
 

lua/render-markdown/core/ui.lua

@@ -26,9 +26,9 @@ M.cache = {}
 ---@param config render.md.ui.Config
 function M.setup(config)
     M.config = config
-    -- reset cache
-    for buf, decorator in pairs(M.cache) do
-        M.clear(buf, decorator)
+    -- clear marks and reset cache
+    for buf in pairs(M.cache) do
+        vim.api.nvim_buf_clear_namespace(buf, M.ns, 0, -1)
     end
     M.cache = {}
 end
@@ -38,7 +38,7 @@ end
 function M.get(buf)
     local result = M.cache[buf]
     if not result then
-        result = Decorator.new()
+        result = Decorator.new(buf)
         M.cache[buf] = result
     end
     return result
@@ -48,24 +48,16 @@ end
 ---@param buf integer
 ---@param win integer
 ---@param event string
----@param change boolean
-function M.update(buf, win, event, change)
-    log.buf('info', 'Update', buf, event, ('change %s'):format(change))
-    M.updater.new(buf, win, change):start()
-end
-
----@private
----@param buf integer
----@param decorator render.md.Decorator
-function M.clear(buf, decorator)
-    vim.api.nvim_buf_clear_namespace(buf, M.ns, 0, -1)
-    decorator:clear()
+---@param force boolean
+function M.update(buf, win, event, force)
+    log.buf('info', 'Update', buf, event, ('force %s'):format(force))
+    M.updater.new(buf, win, force):start()
 end
 
 ---@class render.md.ui.Updater
 ---@field private buf integer
 ---@field private win integer
----@field private change boolean
+---@field private force boolean
 ---@field private decorator render.md.Decorator
 ---@field private config render.md.buf.Config
 ---@field private mode string
@@ -74,13 +66,13 @@ Updater.__index = Updater
 
 ---@param buf integer
 ---@param win integer
----@param change boolean
+---@param force boolean
 ---@return render.md.ui.Updater
-function Updater.new(buf, win, change)
+function Updater.new(buf, win, force)
     local self = setmetatable({}, Updater)
     self.buf = buf
     self.win = win
-    self.change = change
+    self.force = force
     self.decorator = M.get(buf)
     self.config = state.get(buf)
     return self
@@ -94,7 +86,7 @@ function Updater:start()
         return
     end
     self.decorator:schedule(
-        self:should_parse(),
+        self:changed(),
         self.config.debounce,
         log.runtime('update', function()
             self:run()
@@ -104,9 +96,11 @@ end
 
 ---@private
 ---@return boolean
-function Updater:should_parse()
-    -- need to parse on changes or when we have not parsed the visible range yet
-    return self.change or not Context.contains(self.buf, self.win)
+function Updater:changed()
+    -- force or buffer has changed or we have not handled the visible range yet
+    return self.force
+        or self.decorator:changed()
+        or not Context.contains(self.buf, self.win)
 end
 
 ---@private
@@ -126,20 +120,28 @@ function Updater:run()
             Env.win.set(window, name, value[next_state])
         end
     end
-    if render then
+    if not render then
+        self:clear()
+        M.config.on.clear({ buf = self.buf, win = self.win })
+    else
         self:render()
         M.config.on.render({ buf = self.buf, win = self.win })
-    else
-        M.clear(self.buf, self.decorator)
-        M.config.on.clear({ buf = self.buf, win = self.win })
+    end
+end
+
+---@private
+function Updater:clear()
+    local extmarks = self.decorator:get()
+    for _, extmark in ipairs(extmarks) do
+        extmark:hide(M.ns, self.buf)
     end
 end
 
 ---@private
 function Updater:render()
-    local initial = self.decorator:initial()
-    if initial or self:should_parse() then
-        M.clear(self.buf, self.decorator)
+    if self:changed() then
+        local initial = self.decorator:initial()
+        self:clear()
         local extmarks = self:get_extmarks()
         self.decorator:set(extmarks)
         if initial then
@@ -161,8 +163,8 @@ end
 ---@private
 ---@return render.md.Extmark[]
 function Updater:get_extmarks()
-    local has_parser, parser = pcall(vim.treesitter.get_parser, self.buf)
-    if not has_parser or not parser then
+    local ok, parser = pcall(vim.treesitter.get_parser, self.buf)
+    if not ok or not parser then
         log.buf('error', 'Fail', self.buf, 'no treesitter parser found')
         return {}
     end
@@ -179,9 +181,10 @@ end
 function Updater:hidden()
     -- anti-conceal is not enabled -> hide nothing
     -- row is not known -> buffer is not active -> hide nothing
+    -- in command mode -> cursor is not in buffer -> hide nothing
     local config = self.config.anti_conceal
     local row = Env.row.get(self.buf, self.win)
-    if not config.enabled or not row then
+    if not config.enabled or not row or Env.mode.is(self.mode, { 'c' }) then
         return nil
     end
     if Env.mode.is(self.mode, { 'v', 'V', '\22' }) then