feat: support wiki style media links, improve custom links

## Details

Request: #410

Avoids rendering links if they contain a nested `shortcut_link`. This
avoid the double placement of icons and instead only uses the
`shortcut_link` based rendering. A link in a link will have the same
structure as a `wikilink` so really that is the rendering logic that
will ultimately get used.

To then allow a larger variety of icons to be configured have also
expanded custom link functionality. They now have 2 additional optional
properties, `kind` & `priority`.

- kind: changes how the pattern is matched against link destinations
  - pattern: uses the existing lua pattern mechanism, is also the
    default behavior if no value is set to avoid any breaking changes
  - suffix: when set does a simple `vim.endswith` check, can be used to
    easier support file extension matching
  - because of how this is setup adding more kinds should be trivial
- priority: used when multiple patterns match a destination to decide
  which to use, highest value wins, allows users more control rather
  than being stuck with current behavior, uses the length of the pattern
  if no value is set to avoid any changes to behavior out of the box

Author: MeanderingProgrammer

README.md

@@ -721,8 +721,12 @@ require('render-markdown').setup({
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern   | matched against the destination text, @see :h lua-patterns      |
+        -- | pattern   | matched against the destination text                            |
         -- | icon      | gets inlined before the link text                               |
+        -- | kind      | optional determines how pattern is checked                      |
+        -- |           | pattern | @see :h lua-patterns, is the default if not set       |
+        -- |           | suffix  | @see :h vim.endswith()                                |
+        -- | priority  | optional used when multiple match, uses pattern length if empty |
         -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
         custom = {
             web = { pattern = '^http', icon = '󰖟 ' },
@@ -1394,8 +1398,12 @@ require('render-markdown').setup({
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern   | matched against the destination text, @see :h lua-patterns      |
+        -- | pattern   | matched against the destination text                            |
         -- | icon      | gets inlined before the link text                               |
+        -- | kind      | optional determines how pattern is checked                      |
+        -- |           | pattern | @see :h lua-patterns, is the default if not set       |
+        -- |           | suffix  | @see :h vim.endswith()                                |
+        -- | priority  | optional used when multiple match, uses pattern length if empty |
         -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
         custom = {
             web = { pattern = '^http', icon = '󰖟 ' },

doc/render-markdown.txt

@@ -786,8 +786,12 @@ Default Configuration ~
             -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
             -- patterns match a link the one with the longer pattern is used.
             -- The key is for healthcheck and to allow users to change its values, value type below.
-            -- | pattern   | matched against the destination text, @see :h lua-patterns      |
+            -- | pattern   | matched against the destination text                            |
             -- | icon      | gets inlined before the link text                               |
+            -- | kind      | optional determines how pattern is checked                      |
+            -- |           | pattern | @see :h lua-patterns, is the default if not set       |
+            -- |           | suffix  | @see :h vim.endswith()                                |
+            -- | priority  | optional used when multiple match, uses pattern length if empty |
             -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
             custom = {
                 web = { pattern = '^http', icon = '󰖟 ' },
@@ -1439,8 +1443,12 @@ Link Configuration ~
             -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
             -- patterns match a link the one with the longer pattern is used.
             -- The key is for healthcheck and to allow users to change its values, value type below.
-            -- | pattern   | matched against the destination text, @see :h lua-patterns      |
+            -- | pattern   | matched against the destination text                            |
             -- | icon      | gets inlined before the link text                               |
+            -- | kind      | optional determines how pattern is checked                      |
+            -- |           | pattern | @see :h lua-patterns, is the default if not set       |
+            -- |           | suffix  | @see :h vim.endswith()                                |
+            -- | priority  | optional used when multiple match, uses pattern length if empty |
             -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
             custom = {
                 web = { pattern = '^http', icon = '󰖟 ' },

lua/render-markdown/config/link.lua

@@ -29,8 +29,16 @@
 ---@class (exact) render.md.link.custom.Config
 ---@field pattern string
 ---@field icon string
+---@field kind? render.md.link.custom.Kind
+---@field priority? integer
 ---@field highlight? string
 
+---@enum (key) render.md.link.custom.Kind
+local Kind = {
+    pattern = 'pattern',
+    suffix = 'suffix',
+}
+
 local M = {}
 
 ---@param spec render.md.debug.ValidatorSpec
@@ -57,6 +65,8 @@ function M.validate(spec)
         patterns:each(function(pattern)
             pattern:type('pattern', 'string')
             pattern:type('icon', 'string')
+            pattern:one_of('kind', vim.tbl_keys(Kind), 'nil')
+            pattern:type('priority', { 'number', 'nil' })
             pattern:type('highlight', { 'string', 'nil' })
             pattern:check()
         end, false)

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -587,8 +587,12 @@ M.default = {
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern   | matched against the destination text, @see :h lua-patterns      |
+        -- | pattern   | matched against the destination text                            |
         -- | icon      | gets inlined before the link text                               |
+        -- | kind      | optional determines how pattern is checked                      |
+        -- |           | pattern | @see :h lua-patterns, is the default if not set       |
+        -- |           | suffix  | @see :h vim.endswith()                                |
+        -- | priority  | optional used when multiple match, uses pattern length if empty |
         -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
         custom = {
             web = { pattern = '^http', icon = '󰖟 ' },

lua/render-markdown/lib/iter.lua

@@ -16,13 +16,22 @@ function M.list.map(values, f)
     return result
 end
 
+---@generic T
+---@param values T[]
+---@param f fun(value: T): integer
+function M.list.sort(values, f)
+    table.sort(values, function(a, b)
+        return f(a) < f(b)
+    end)
+end
+
 ---@class render.md.iter.Table
 M.table = {}
 
----@generic V
----@param values table<any, V>
----@param f fun(value: V): boolean
----@return V[]
+---@generic T
+---@param values { [any]: T }
+---@param f fun(value: T): boolean
+---@return T[]
 function M.table.filter(values, f)
     local result = {}
     for _, value in pairs(values) do

lua/render-markdown/lib/node.lua

@@ -78,14 +78,13 @@ function Node:level(parent)
     if section == nil then
         return 0
     end
-    assert(section.type == 'section', 'Node must be a section')
+    assert(section.type == 'section', 'must be a section')
     local heading = section:child('atx_heading')
     local node = heading ~= nil and heading.node:child(0) or nil
-    -- Counts the number of hashtags in the heading marker
+    -- counts the number of hashtags in the heading marker
     return node ~= nil and #vim.treesitter.get_node_text(node, self.buf) or 0
 end
 
----Walk through parent nodes, count the number of target nodes
 ---@param target string
 ---@return integer, render.md.Node?
 function Node:level_in_section(target)
@@ -105,12 +104,12 @@ end
 ---@param target string
 ---@return render.md.Node?
 function Node:parent(target)
-    local parent = self.node:parent()
-    while parent ~= nil do
-        if parent:type() == target then
-            return self:create(parent)
+    local node = self.node:parent()
+    while node ~= nil do
+        if node:type() == target then
+            return self:create(node)
         end
-        parent = parent:parent()
+        node = node:parent()
     end
     return nil
 end
@@ -152,13 +151,13 @@ function Node:child_at(index)
     return node ~= nil and self:create(node) or nil
 end
 
----@param target_type string
----@param target_row? integer
+---@param target string
+---@param row? integer
 ---@return render.md.Node?
-function Node:child(target_type, target_row)
+function Node:child(target, row)
     for node in self.node:iter_children() do
-        if node:type() == target_type then
-            if target_row == nil or node:range() == target_row then
+        if node:type() == target then
+            if row == nil or node:range() == row then
                 return self:create(node)
             end
         end
@@ -168,9 +167,25 @@ end
 
 ---@param callback fun(node: render.md.Node)
 function Node:for_each_child(callback)
-    for child in self.node:iter_children() do
-        callback(self:create(child))
+    for node in self.node:iter_children() do
+        callback(self:create(node))
+    end
+end
+
+---@param target string
+---@return render.md.Node?
+function Node:descendant(target)
+    for node in self.node:iter_children() do
+        local child = self:create(node)
+        if child.type == target then
+            return child
+        end
+        local nested = child:descendant(target)
+        if nested ~= nil then
+            return nested
+        end
     end
+    return nil
 end
 
 ---@return string?
@@ -183,15 +198,16 @@ end
 ---@param by integer
 ---@return string?
 function Node:line(position, by)
-    local one_line, row = self.start_row == self.end_row, nil
+    local row = nil
+    local single = self.start_row == self.end_row
     if position == 'above' then
         row = self.start_row - by
     elseif position == 'first' then
         row = self.start_row + by
     elseif position == 'below' then
-        row = self.end_row - (one_line and 0 or 1) + by
+        row = self.end_row - (single and 0 or 1) + by
     elseif position == 'last' then
-        row = self.end_row - (one_line and 0 or 1) - by
+        row = self.end_row - (single and 0 or 1) - by
     end
     if row == nil then
         return nil

lua/render-markdown/render/base.lua

@@ -53,7 +53,7 @@ function Base:check_icon(icon, highlight)
     local space = self.context:width(self.node) + 1 - Str.width(icon)
     local right_pad = self.config.checkbox.right_pad
     if space < 0 then
-        -- Not enough space to fit the icon in-place
+        -- not enough space to fit the icon in-place
         return self.marks:over('check_icon', self.node, {
             virt_text = self:append(line, right_pad),
             virt_text_pos = 'inline',
@@ -62,23 +62,25 @@ function Base:check_icon(icon, highlight)
     else
         local fits = math.min(space, right_pad)
         self:append(line, fits)
-        space, right_pad = space - fits, right_pad - fits
+        space = space - fits
+        right_pad = right_pad - fits
         local row = self.node.start_row
-        local start_col, end_col = self.node.start_col, self.node.end_col + 1
+        local start_col = self.node.start_col
+        local end_col = self.node.end_col + 1
         self.marks:add('check_icon', row, start_col, {
             end_col = end_col - space,
             virt_text = line,
             virt_text_pos = 'overlay',
         })
         if space > 0 then
-            -- Hide extra space after the icon
+            -- hide extra space after the icon
             self.marks:add('check_icon', row, end_col - space, {
                 end_col = end_col,
                 conceal = '',
             })
         end
         if right_pad > 0 then
-            -- Add padding
+            -- add padding
             self.marks:add('check_icon', row, end_col, {
                 virt_text = self:append({}, right_pad),
                 virt_text_pos = 'inline',
@@ -106,10 +108,14 @@ end
 ---@return string, string
 function Base:dest(icon, highlight, destination)
     local options = Iter.table.filter(self.config.link.custom, function(custom)
-        return destination:find(custom.pattern) ~= nil
+        if custom.kind == 'suffix' then
+            return vim.endswith(destination, custom.pattern)
+        else
+            return destination:find(custom.pattern) ~= nil
+        end
     end)
-    table.sort(options, function(a, b)
-        return Str.width(a.pattern) < Str.width(b.pattern)
+    Iter.list.sort(options, function(custom)
+        return custom.priority or Str.width(custom.pattern)
     end)
     local result = options[#options] or {}
     return result.icon or icon, result.highlight or highlight

lua/render-markdown/render/link.lua

@@ -16,7 +16,9 @@ function Render:setup()
     if self.context:skip(link) then
         return false
     end
-
+    if self.node:descendant('shortcut_link') ~= nil then
+        return false
+    end
     local icon, highlight, autolink = link.hyperlink, link.highlight, false
     if self.node.type == 'email_autolink' then
         icon = link.email
@@ -34,7 +36,6 @@ function Render:setup()
         autolink = true
     end
     self.data = { icon = icon, highlight = highlight, autolink = autolink }
-
     return true
 end
 

lua/render-markdown/render/shortcut.lua

@@ -25,10 +25,8 @@ function Render:render()
     end
 
     local line = self.node:line('first', 0)
-    if
-        line ~= nil
-        and line:find('[' .. self.node.text .. ']', 1, true) ~= nil
-    then
+    local wiki_pattern = '[' .. self.node.text .. ']'
+    if line ~= nil and line:find(wiki_pattern, 1, true) ~= nil then
         self:wiki_link()
         return
     end