feat: change_events list & link.wiki.body function

## Details

This change exposes 2 new configuration options to allow users to show
the contents of diagnostics in wiki links as shown in discussion [#228](#228)
without using a separate fork that has accrued merge conflicts.

This is a modified version of PR [#345](#345)
but it offloads the specific details to user configuration. Instead we
expose the information needed through a user configurable function and
the user can use this to change the body of a wiki link as they please.

### Events

The first part is the top level `change_events` configuration which gets
joined to the list of default events that trigger re-rendering due to
content changes. Since diagnostics changing now impacts the rendered
view we need to add the `DiagnosticChanged` event to the list.

```lua
require('render-markdown').setup({
    change_events = { 'DiagnosticChanged' },
})
```

Since it's configurable this is only needed for users that want rendering
that depends on diagnostics, by default no additional events are added.

### Body

Now we use the `link.wiki.body` configuration to dynamically set the
main text of a wiki link based on any overlapping diagnostics. This is
appended to the icon. If a `nil` return value is provided we fallback to
the existing logic with no changes.

Below as an implementation specific to the `zk-nvim` plugin, but it is
easily modified to match any similar use case:

```lua
require('render-markdown').setup({
    link = {
        wiki = {
            body = function(ctx)
                local diagnostics = vim.diagnostic.get(ctx.buf, {
                    lnum = ctx.row,
                    severity = vim.diagnostic.severity.HINT,
                })
                for _, diagnostic in ipairs(diagnostics) do
                    if diagnostic.source == 'zk' then
                        return diagnostic.message
                    end
                end
                return nil
            end,
        },
    },
})
```

Co-authored-by: Michael McDonagh <[email protected]>

Author: MeanderingProgrammer

README.md

@@ -200,6 +200,8 @@ require('render-markdown').setup({
     log_runtime = false,
     -- Filetypes this plugin will run on
     file_types = { 'markdown' },
+    -- Additional events that will trigger this plugin's render loop
+    change_events = {},
     -- Out of the box language injections for known filetypes that allow markdown to be
     -- interpreted in specified locations, see :h treesitter-language-injections
     -- Set enabled to false in order to disable
@@ -616,7 +618,13 @@ require('render-markdown').setup({
         -- Applies to the inlined icon as a fallback
         highlight = 'RenderMarkdownLink',
         -- Applies to UncycloLink elements
-        wiki = { icon = '󱗖 ', highlight = 'RenderMarkdownUncycloLink' },
+        wiki = {
+            icon = '󱗖 ',
+            body = function()
+                return nil
+            end,
+            highlight = 'RenderMarkdownUncycloLink',
+        },
         -- Define custom destination patterns so icons can quickly inform you of what a link
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.
@@ -1246,7 +1254,13 @@ require('render-markdown').setup({
         -- Applies to the inlined icon as a fallback
         highlight = 'RenderMarkdownLink',
         -- Applies to UncycloLink elements
-        wiki = { icon = '󱗖 ', highlight = 'RenderMarkdownUncycloLink' },
+        wiki = {
+            icon = '󱗖 ',
+            body = function()
+                return nil
+            end,
+            highlight = 'RenderMarkdownUncycloLink',
+        },
         -- Define custom destination patterns so icons can quickly inform you of what a link
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*         For 0.10.0         Last change: 2025 February 20
+*render-markdown.txt*         For 0.10.0         Last change: 2025 February 24
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -261,6 +261,8 @@ Default Configuration ~
         log_runtime = false,
         -- Filetypes this plugin will run on
         file_types = { 'markdown' },
+        -- Additional events that will trigger this plugin's render loop
+        change_events = {},
         -- Out of the box language injections for known filetypes that allow markdown to be
         -- interpreted in specified locations, see :h treesitter-language-injections
         -- Set enabled to false in order to disable
@@ -677,7 +679,13 @@ Default Configuration ~
             -- Applies to the inlined icon as a fallback
             highlight = 'RenderMarkdownLink',
             -- Applies to UncycloLink elements
-            wiki = { icon = '󱗖 ', highlight = 'RenderMarkdownUncycloLink' },
+            wiki = {
+                icon = '󱗖 ',
+                body = function()
+                    return nil
+                end,
+                highlight = 'RenderMarkdownUncycloLink',
+            },
             -- Define custom destination patterns so icons can quickly inform you of what a link
             -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
             -- patterns match a link the one with the longer pattern is used.
@@ -1287,7 +1295,13 @@ Link Configuration ~
             -- Applies to the inlined icon as a fallback
             highlight = 'RenderMarkdownLink',
             -- Applies to UncycloLink elements
-            wiki = { icon = '󱗖 ', highlight = 'RenderMarkdownUncycloLink' },
+            wiki = {
+                icon = '󱗖 ',
+                body = function()
+                    return nil
+                end,
+                highlight = 'RenderMarkdownUncycloLink',
+            },
             -- Define custom destination patterns so icons can quickly inform you of what a link
             -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
             -- patterns match a link the one with the longer pattern is used.

lua/render-markdown/core/context.lua

@@ -89,6 +89,11 @@ function Context:skip(component)
     return not util.in_modes(component.render_modes, self.mode)
 end
 
+---@return integer
+function Context:get_buf()
+    return self.buf
+end
+
 ---@param row integer
 ---@return render.md.CustomCallout?
 function Context:get_callout(row)

lua/render-markdown/health.lua

@@ -5,7 +5,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '8.0.6'
+M.version = '8.0.7'
 
 function M.check()
     M.start('version')

lua/render-markdown/init.lua

@@ -72,8 +72,16 @@ local M = {}
 ---@field public icon? string
 ---@field public highlight? string
 
+---@class (exact) render.md.LinkContext
+---@field public buf integer
+---@field public row integer
+---@field public start_col integer
+---@field public end_col integer
+---@field public destination string
+
 ---@class (exact) render.md.UserUncycloLink
 ---@field public icon? string
+---@field public body? fun(ctx: render.md.LinkContext): string?
 ---@field public highlight? string
 
 ---@class (exact) render.md.UserFootnote
@@ -289,6 +297,7 @@ local M = {}
 ---@field public log_level? render.md.config.LogLevel
 ---@field public log_runtime? boolean
 ---@field public file_types? string[]
+---@field public change_events? string[]
 ---@field public injections? table<string, render.md.UserInjection>
 ---@field public on? render.md.UserCallback
 ---@field public overrides? render.md.UserConfigOverrides
@@ -322,6 +331,8 @@ M.default_config = {
     log_runtime = false,
     -- Filetypes this plugin will run on
     file_types = { 'markdown' },
+    -- Additional events that will trigger this plugin's render loop
+    change_events = {},
     -- Out of the box language injections for known filetypes that allow markdown to be
     -- interpreted in specified locations, see :h treesitter-language-injections
     -- Set enabled to false in order to disable
@@ -738,7 +749,13 @@ M.default_config = {
         -- Applies to the inlined icon as a fallback
         highlight = 'RenderMarkdownLink',
         -- Applies to UncycloLink elements
-        wiki = { icon = '󱗖 ', highlight = 'RenderMarkdownUncycloLink' },
+        wiki = {
+            icon = '󱗖 ',
+            body = function()
+                return nil
+            end,
+            highlight = 'RenderMarkdownUncycloLink',
+        },
         -- Define custom destination patterns so icons can quickly inform you of what a link
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.

lua/render-markdown/manager.lua

@@ -101,6 +101,7 @@ function M.attach(buf)
 
     local events = { 'BufWinEnter', 'BufLeave', 'CmdlineChanged', 'CursorHold', 'CursorMoved', 'WinScrolled' }
     local change_events = { 'DiffUpdated', 'ModeChanged', 'TextChanged' }
+    vim.list_extend(change_events, state.change_events)
     if config:render('i') then
         vim.list_extend(events, { 'CursorHoldI', 'CursorMovedI' })
         vim.list_extend(change_events, { 'TextChangedI' })

lua/render-markdown/render/shortcut.lua

@@ -98,35 +98,49 @@ function Render:wiki_link()
         return
     end
 
-    local wiki = self.link.wiki
-    local start_col, end_col = self.node.start_col, self.node.end_col
-    local values = Str.split(self.node.text:sub(2, -2), '|')
-
-    -- Hide opening outer bracket
-    self:hide(start_col - 1, start_col)
+    local sections = Str.split(self.node.text:sub(2, -2), '|')
+    ---@type render.md.LinkContext
+    local ctx = {
+        buf = self.context:get_buf(),
+        row = self.node.start_row,
+        start_col = self.node.start_col - 1,
+        end_col = self.node.end_col + 1,
+        destination = sections[1],
+    }
+
+    -- Hide opening & closing outer brackets
+    self:hide(ctx.start_col, 1)
+    self:hide(ctx.end_col - 1, 1)
 
-    -- Add icon
-    local icon, highlight = self:from_destination(wiki.icon, wiki.highlight, values[1])
-    self.marks:add_over('link', self.node, {
-        virt_text = { { icon, highlight } },
-        virt_text_pos = 'inline',
-    })
-
-    -- Hide destination if there is an alias
-    if #values > 1 then
-        self:hide(start_col + 1, start_col + 1 + #values[1] + 1)
+    local wiki = self.link.wiki
+    local icon, highlight = self:from_destination(wiki.icon, wiki.highlight, ctx.destination)
+    local body = wiki.body(ctx)
+    if body == nil then
+        -- Add icon
+        self.marks:add_over('link', self.node, {
+            virt_text = { { icon, highlight } },
+            virt_text_pos = 'inline',
+        })
+        -- Hide destination if there is an alias
+        if #sections > 1 then
+            self:hide(ctx.start_col + 2, #ctx.destination + 1)
+        end
+    else
+        -- Inline icon & body, hide original text
+        self.marks:add_over('link', self.node, {
+            virt_text = { { icon .. body, highlight } },
+            virt_text_pos = 'inline',
+            conceal = '',
+        }, { 0, 1, 0, -1 })
     end
-
-    -- Hide closing outer bracket
-    self:hide(end_col, end_col + 1)
 end
 
 ---@private
----@param start_col integer
----@param end_col integer
-function Render:hide(start_col, end_col)
-    self.marks:add(true, self.node.start_row, start_col, {
-        end_col = end_col,
+---@param col integer
+---@param length integer
+function Render:hide(col, length)
+    self.marks:add(true, self.node.start_row, col, {
+        end_col = col + length,
         conceal = '',
     })
 end

lua/render-markdown/state.lua

@@ -12,6 +12,7 @@ local configs = {}
 ---@field enabled boolean
 ---@field log_runtime boolean
 ---@field file_types string[]
+---@field change_events string[]
 ---@field on render.md.Callback
 ---@field custom_handlers table<string, render.md.Handler>
 local M = {}
@@ -43,6 +44,7 @@ function M.setup(default_config, user_config)
     M.enabled = config.enabled
     M.log_runtime = config.log_runtime
     M.file_types = config.file_types
+    M.change_events = config.change_events
     M.on = config.on
     M.custom_handlers = config.custom_handlers
     log.setup(config.log_level)
@@ -259,7 +261,7 @@ function M.validate()
                         footnote:type('superscript', 'boolean'):type({ 'prefix', 'suffix' }, 'string'):check()
                     end)
                     :nested('wiki', function(wiki)
-                        wiki:type({ 'icon', 'highlight' }, 'string'):check()
+                        wiki:type({ 'icon', 'highlight' }, 'string'):type('body', 'function'):check()
                     end)
                     :nested('custom', function(patterns)
                         patterns
@@ -320,7 +322,7 @@ function M.validate()
 
     buffer_rules(validator:spec(M.config, false))
         :type('log_runtime', 'boolean')
-        :list('file_types', 'string')
+        :list({ 'file_types', 'change_events' }, 'string')
         :one_of('preset', { 'none', 'lazy', 'obsidian' })
         :one_of('log_level', { 'off', 'debug', 'info', 'error' })
         :nested('injections', function(injections)

lua/render-markdown/types.lua

@@ -50,6 +50,7 @@
 
 ---@class (exact) render.md.UncycloLink
 ---@field public icon string
+---@field public body fun(ctx: render.md.LinkContext): string?
 ---@field public highlight string
 
 ---@class (exact) render.md.Footnote
@@ -205,6 +206,7 @@
 ---@field public log_level render.md.config.LogLevel
 ---@field public log_runtime boolean
 ---@field public file_types string[]
+---@field public change_events string[]
 ---@field public injections table<string, render.md.Injection>
 ---@field public on render.md.Callback
 ---@field public overrides render.md.ConfigOverrides

scripts/update.py

@@ -38,7 +38,7 @@ def is_optional(self, field: str) -> bool:
         # ---@field public extends? boolean             -> extends
         # ---@field public start_row integer            -> start_row
         # ---@field public attach? fun(buf: integer)    -> attach
-        field_name = field.split()[2].replace("?", "")
+        field_name = field.split()[2].replace("?", "", 1)
         return field_name in class_to_optional.get(self.class_name, [])
 
     def validate(self) -> None:
@@ -53,11 +53,11 @@ def to_internal(self) -> str:
         lines: list[str] = [self.name.replace("User", "")]
         for field in self.fields:
             if self.class_name == "UserConfigOverrides":
-                lines.append(field.replace("?", ""))
+                lines.append(field.replace("?", "", 1))
             elif self.is_optional(field):
                 lines.append(field)
             else:
-                lines.append(field.replace("User", "").replace("?", ""))
+                lines.append(field.replace("User", "").replace("?", "", 1))
         return "\n".join(lines)
 
     def to_str(self) -> str: