feat: combine highlights for links

## Details

Request: #413

Link icons are added using inline virtual text. Since we do not set an
`hl_mode` property the default value of `replace` is used. This is fine
in most context but in headings for instance, where we highlight the
background of the line the icons will continue to have their own default
background so will stick out.

The fix for this is to specify `hl_mode = combine` when we add link
icons, which results in the background getting picked up from the
background mark.

Minor other changes:

- Use method name `padding` consistently in renderers rather than
  different ones like `side_padding`, `left_pad`, etc.
- Add an enum for positions in node
- Raise an error when an invalid position is provided to `Node:line`,
  since this is only used internally it would mean there's definitely a
  bug somewhere that we'd otherwise swallow, include the row number in
  the output

Author: MeanderingProgrammer

doc/custom-handlers.md

@@ -27,6 +27,7 @@ Each handler must conform to the following interface:
 ---@field opts render.md.mark.Opts
 
 ---@class render.md.mark.Opts: vim.api.keyset.set_extmark
+---@field hl_mode? 'replace'|'combine'|'blend'
 ---@field virt_text? render.md.mark.Line
 ---@field virt_text_pos? 'eol'|'inline'|'overlay'
 ---@field virt_lines? render.md.mark.Line[]

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*           For 0.11.0          Last change: 2025 April 24
+*render-markdown.txt*           For 0.11.0          Last change: 2025 April 25
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*

lua/render-markdown/health.lua

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

lua/render-markdown/lib/marks.lua

@@ -10,6 +10,7 @@ local log = require('render-markdown.core.log')
 ---@field opts render.md.mark.Opts
 
 ---@class render.md.mark.Opts: vim.api.keyset.set_extmark
+---@field hl_mode? 'replace'|'combine'|'blend'
 ---@field virt_text? render.md.mark.Line
 ---@field virt_text_pos? 'eol'|'inline'|'overlay'
 ---@field virt_lines? render.md.mark.Line[]

lua/render-markdown/lib/node.lua

@@ -1,6 +1,14 @@
 local Iter = require('render-markdown.lib.iter')
 local Str = require('render-markdown.lib.str')
 
+---@enum (key) render.md.node.Position
+local Position = {
+    above = 'above',
+    first = 'first',
+    below = 'below',
+    last = 'last',
+}
+
 ---@class render.md.Node
 ---@field private buf integer
 ---@field private node TSNode
@@ -194,25 +202,24 @@ function Node:after()
     return vim.api.nvim_buf_get_text(self.buf, row, col, row, col + 1, {})[1]
 end
 
----@param position 'above'|'first'|'below'|'last'
+---@param position render.md.node.Position
 ---@param by integer
----@return string?
+---@return integer, string?
 function Node:line(position, by)
     local row = nil
     local single = self.start_row == self.end_row
-    if position == 'above' then
+    if position == Position.above then
         row = self.start_row - by
-    elseif position == 'first' then
+    elseif position == Position.first then
         row = self.start_row + by
-    elseif position == 'below' then
+    elseif position == Position.below then
         row = self.end_row - (single and 0 or 1) + by
-    elseif position == 'last' then
+    elseif position == Position.last then
         row = self.end_row - (single and 0 or 1) - by
+    else
+        error('invalid position: ' .. position)
     end
-    if row == nil then
-        return nil
-    end
-    return vim.api.nvim_buf_get_lines(self.buf, row, row + 1, false)[1]
+    return row, vim.api.nvim_buf_get_lines(self.buf, row, row + 1, false)[1]
 end
 
 ---@return integer[]

lua/render-markdown/render/base.lua

@@ -102,11 +102,9 @@ function Base:scope(element, node, highlight)
 end
 
 ---@protected
----@param icon string
----@param highlight string
 ---@param destination string
----@return string, string
-function Base:dest(icon, highlight, destination)
+---@param icon render.md.mark.Text
+function Base:link_icon(destination, icon)
     local options = Iter.table.filter(self.config.link.custom, function(custom)
         if custom.kind == 'suffix' then
             return vim.endswith(destination, custom.pattern)
@@ -117,8 +115,11 @@ function Base:dest(icon, highlight, destination)
     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
+    local result = options[#options]
+    if result ~= nil then
+        icon[1] = result.icon
+        icon[2] = result.highlight or icon[2]
+    end
 end
 
 ---@protected

lua/render-markdown/render/bullet.lua

@@ -4,37 +4,28 @@ local Str = require('render-markdown.lib.str')
 
 ---@class render.md.bullet.Data
 ---@field marker render.md.Node
----@field icons render.md.bullet.Text
 ---@field spaces integer
 ---@field checkbox? render.md.checkbox.custom.Config
 
 ---@class render.md.render.Bullet: render.md.Render
----@field private info render.md.bullet.Config
 ---@field private data render.md.bullet.Data
 local Render = setmetatable({}, Base)
 Render.__index = Render
 
 ---@return boolean
 function Render:setup()
-    self.info = self.config.bullet
-
     local marker = self.node:child_at(0)
     if marker == nil then
         return false
     end
-
-    local ordered_types = { 'list_marker_dot', 'list_marker_parenthesis' }
-    local ordered = vim.tbl_contains(ordered_types, marker.type)
     self.data = {
         marker = marker,
-        icons = ordered and self.info.ordered_icons or self.info.icons,
         -- List markers from tree-sitter should have leading spaces removed, however there are edge
         -- cases in the parser: https://github.com/tree-sitter-grammars/tree-sitter-markdown/issues/127
         -- As a result we account for leading spaces here, can remove if this gets fixed upstream
         spaces = Str.spaces('start', marker.text),
         checkbox = self.context:get_checkbox(self.node.start_row),
     }
-
     return true
 end
 
@@ -47,23 +38,30 @@ function Render:render()
             self:highlight_scope('check_scope', scope_highlight)
         end
     else
-        if self.context:skip(self.info) then
+        local info = self.config.bullet
+        if self.context:skip(info) then
             return
         end
+
+        local ordered_types = { 'list_marker_dot', 'list_marker_parenthesis' }
+        local ordered = vim.tbl_contains(ordered_types, self.data.marker.type)
+        local icons = ordered and info.ordered_icons or info.icons
+
         local level, root = self.node:level_in_section('list')
         ---@type render.md.bullet.Context
         local ctx = {
             level = level,
             index = self.node:sibling_count('list_item'),
             value = self.data.marker.text,
         }
-        local icon = self:get_text(ctx, self.data.icons)
-        local highlight = self:get_text(ctx, self.info.highlight)
-        local scope_highlight = self:get_text(ctx, self.info.scope_highlight)
-        local left_pad = self:get_int(ctx, self.info.left_pad)
-        local right_pad = self:get_int(ctx, self.info.right_pad)
-        self:add_icon(icon, highlight)
-        self:add_padding(left_pad, right_pad, root)
+
+        local icon = self:get_text(icons, ctx)
+        local highlight = self:get_text(info.highlight, ctx)
+        local scope_highlight = self:get_text(info.scope_highlight, ctx)
+        local left_pad = self:get_int(info.left_pad, ctx)
+        local right_pad = self:get_int(info.right_pad, ctx)
+        self:icon(icon, highlight)
+        self:padding(root, left_pad, right_pad)
         self:highlight_scope(true, scope_highlight)
     end
 end
@@ -74,16 +72,9 @@ function Render:has_checkbox()
     if self.context:skip(self.config.checkbox) then
         return false
     end
-    if self.data.checkbox ~= nil then
-        return true
-    end
-    if self.data.marker:sibling('task_list_marker_unchecked') ~= nil then
-        return true
-    end
-    if self.data.marker:sibling('task_list_marker_checked') ~= nil then
-        return true
-    end
-    return false
+    return self.data.checkbox ~= nil
+        or self.data.marker:sibling('task_list_marker_unchecked') ~= nil
+        or self.data.marker:sibling('task_list_marker_checked') ~= nil
 end
 
 ---@private
@@ -100,10 +91,10 @@ function Render:highlight_scope(element, highlight)
 end
 
 ---@private
----@param ctx render.md.bullet.Context
 ---@param values render.md.bullet.Text
+---@param ctx render.md.bullet.Context
 ---@return string?
-function Render:get_text(ctx, values)
+function Render:get_text(values, ctx)
     if type(values) == 'function' then
         return values(ctx)
     elseif type(values) == 'string' then
@@ -119,10 +110,10 @@ function Render:get_text(ctx, values)
 end
 
 ---@private
----@param ctx render.md.bullet.Context
 ---@param value render.md.bullet.Int
+---@param ctx render.md.bullet.Context
 ---@return integer
-function Render:get_int(ctx, value)
+function Render:get_int(value, ctx)
     if type(value) == 'function' then
         return value(ctx)
     else
@@ -133,7 +124,7 @@ end
 ---@private
 ---@param icon string?
 ---@param highlight string?
-function Render:add_icon(icon, highlight)
+function Render:icon(icon, highlight)
     if icon == nil or highlight == nil then
         return
     end
@@ -147,56 +138,52 @@ function Render:add_icon(icon, highlight)
 end
 
 ---@private
+---@param root? render.md.Node
 ---@param left_pad integer
 ---@param right_pad integer
----@param root? render.md.Node
-function Render:add_padding(left_pad, right_pad, root)
+function Render:padding(root, left_pad, right_pad)
     if left_pad <= 0 and right_pad <= 0 then
         return
     end
     local start_row, end_row = self.node.start_row, self:end_row(root)
+    local left_line = self:append({}, left_pad)
+    local right_line = self:append({}, right_pad)
     for row = start_row, end_row - 1 do
         local left = root ~= nil and root.start_col or self.node.start_col
         local right = row == start_row and self.data.marker.end_col - 1 or left
-        self:side_padding(row, left, left_pad)
-        self:side_padding(row, right, right_pad)
+        if #left_line > 0 then
+            self.marks:add(false, row, left, {
+                priority = 0,
+                virt_text = left_line,
+                virt_text_pos = 'inline',
+            })
+        end
+        if #right_line > 0 then
+            self.marks:add(false, row, right, {
+                priority = 0,
+                virt_text = right_line,
+                virt_text_pos = 'inline',
+            })
+        end
     end
 end
 
 ---@private
 ---@param root? render.md.Node
 ---@return integer
 function Render:end_row(root)
-    local next_list = self.node:child('list')
-    if next_list ~= nil then
-        return next_list.start_row
+    local sub_list = self.node:child('list')
+    if sub_list ~= nil then
+        return sub_list.start_row
+    elseif root == nil then
+        return self.node.end_row
     else
+        -- on the last item of the root list ignore the last line if empty
         local row = self.node.end_row
-        -- On the last item of the root list ignore the last line if it is empty
-        if
-            root ~= nil
-            and root.end_row == row
-            and Str.width(root:line('last', 0)) == 0
-        then
-            return row - 1
-        else
-            return row
-        end
-    end
-end
-
----@private
----@param row integer
----@param col integer
----@param amount integer
-function Render:side_padding(row, col, amount)
-    local line = self:append({}, amount)
-    if #line > 0 then
-        self.marks:add(false, row, col, {
-            priority = 0,
-            virt_text = line,
-            virt_text_pos = 'inline',
-        })
+        local _, line = root:line('last', 0)
+        local ignore_last = root.end_row == row and Str.width(line) == 0
+        local offset = ignore_last and 1 or 0
+        return row - offset
     end
 end
 

lua/render-markdown/render/code.lua

@@ -94,7 +94,7 @@ function Render:render()
     if background then
         self:background(start_row + 1, end_row - 1, self.info.highlight)
     end
-    self:left_pad(background)
+    self:padding(background)
 end
 
 ---@private
@@ -233,7 +233,7 @@ end
 
 ---@private
 ---@param background boolean
-function Render:left_pad(background)
+function Render:padding(background)
     local col = self.node.start_col
     local start_row, end_row = self.node.start_row, self.node.end_row - 1
     local empty, widths = {}, col == 0 and {} or self.node:widths()

lua/render-markdown/render/code_inline.lua

@@ -21,14 +21,14 @@ end
 function Render:render()
     local highlight = self.info.highlight_inline
     self.marks:over('code_background', self.node, { hl_group = highlight })
-    self:side_padding(highlight, true)
-    self:side_padding(highlight, false)
+    self:padding(highlight, true)
+    self:padding(highlight, false)
 end
 
 ---@private
 ---@param highlight string
 ---@param left boolean
-function Render:side_padding(highlight, left)
+function Render:padding(highlight, left)
     local line, icon_highlight = {}, colors.bg_to_fg(highlight)
     if left then
         self:append(line, self.info.inline_left, icon_highlight)