feat: handle arbitrary block quote nesting nicely

## Details

Request: #404

While the request seems to be about using the parent color across the
board, I've instead implemented this in a slightly more complex but
hopefully more pretty way.

Rather than highlighting entire sets of `block quote` markers, i.e.
`> > >`, with a single highlight we now associate colors based on the
level of the block quote.

What this means is if we're into a triple nested block quote where:

- Level 1: `[!IMPORTANT]` callout
- Level 2: no callout
- Level 3:  `[!BUG]` callout

We'll use highlight as follows:

- `>` 1: `[!IMPORTANT]` callout highlight
- `>` 2: default `quote` highlight
- `>` 3: `[!BUG]` callout highlight

This applies throughout the `block quote` on all lines. To handle the
`lazy` provision of the `markdown` spec we simply go front to back one
level at a time. So if on some line `> >` is added even though the level
is still technically 3, we only highlight the first 2 according to the
first 2 levels.

So as not to limit the usage to callouts `quote.icon` and `quote.highlight`
now both support taking a list of strings in addition to a single string
value. When a list is provided it is indexed into using a `cycle` access
pattern based on the nesting of the current `block quote`. This allows
users to change both the color and the icon used based on how deeply
nested the block quote is.

Add unit tests for updated quote logic since it's not trivial.

Author: MeanderingProgrammer

doc/render-markdown.txt

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

lua/render-markdown/config/quote.lua

@@ -1,16 +1,16 @@
 ---@class (exact) render.md.quote.Config: render.md.base.Config
----@field icon string
+---@field icon string|string[]
 ---@field repeat_linebreak boolean
----@field highlight string
+---@field highlight string|string[]
 
 local M = {}
 
 ---@param spec render.md.debug.ValidatorSpec
 function M.validate(spec)
     require('render-markdown.config.base').validate(spec)
-    spec:type('icon', 'string')
+    spec:list('icon', 'string', 'string')
     spec:type('repeat_linebreak', 'boolean')
-    spec:type('highlight', 'string')
+    spec:list('highlight', 'string', 'string')
     spec:check()
 end
 

lua/render-markdown/health.lua

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

lua/render-markdown/lib/list.lua

@@ -2,14 +2,18 @@
 local M = {}
 
 ---@generic T
----@param values T[]
+---@param values `T`|T[]
 ---@param index integer
 ---@return T|nil
 function M.cycle(values, index)
-    if #values == 0 then
-        return nil
+    if type(values) == 'table' then
+        if #values == 0 then
+            return nil
+        end
+        return values[((index - 1) % #values) + 1]
+    else
+        return values
     end
-    return values[((index - 1) % #values) + 1]
 end
 
 ---@generic T

lua/render-markdown/lib/node.lua

@@ -55,14 +55,16 @@ end
 
 ---@return integer[]
 function Node:sections()
-    local result, levels, section = {}, 0, self:parent('section')
+    local result = {} ---@type integer[]
+    local levels = 0
+    local section = self:parent('section')
     while section ~= nil do
         local level = section:level(false)
         result[level] = section:sibling_count('section', level)
         levels = math.max(levels, level)
         section = section:parent('section')
     end
-    -- Fill in any heading level gaps with 0
+    -- fill in any heading level gaps with 0
     for i = 1, levels do
         result[i] = result[i] or 0
     end
@@ -87,12 +89,15 @@ end
 ---@param target string
 ---@return integer, render.md.Node?
 function Node:level_in_section(target)
-    local parent, level, root = self.node:parent(), 0, nil
-    while parent ~= nil and parent:type() ~= 'section' do
-        if parent:type() == target then
-            level, root = level + 1, parent
+    local level = 0
+    local root = nil ---@type TSNode?
+    local node = self.node ---@type TSNode?
+    while node ~= nil and node:type() ~= 'section' do
+        if node:type() == target then
+            level = level + 1
+            root = node
         end
-        parent = parent:parent()
+        node = node:parent()
     end
     return level, root ~= nil and self:create(root) or nil
 end
@@ -113,12 +118,12 @@ end
 ---@param target string
 ---@return render.md.Node?
 function Node:sibling(target)
-    local sibling = self.node:next_sibling()
-    while sibling ~= nil do
-        if sibling:type() == target then
-            return self:create(sibling)
+    local node = self.node ---@type TSNode?
+    while node ~= nil do
+        if node:type() == target then
+            return self:create(node)
         end
-        sibling = sibling:next_sibling()
+        node = node:next_sibling()
     end
     return nil
 end
@@ -127,14 +132,15 @@ end
 ---@param level? integer
 ---@return integer
 function Node:sibling_count(target, level)
-    local count, sibling = 1, self.node:prev_sibling()
+    local count = 0
+    local node = self.node ---@type TSNode?
     while
-        sibling ~= nil
-        and sibling:type() == target
-        and (level == nil or self:create(sibling):level(false) == level)
+        node ~= nil
+        and node:type() == target
+        and (level == nil or self:create(node):level(false) == level)
     do
         count = count + 1
-        sibling = sibling:prev_sibling()
+        node = node:prev_sibling()
     end
     return count
 end
@@ -150,10 +156,10 @@ end
 ---@param target_row? integer
 ---@return render.md.Node?
 function Node:child(target_type, target_row)
-    for child in self.node:iter_children() do
-        if child:type() == target_type then
-            if target_row == nil or child:range() == target_row then
-                return self:create(child)
+    for node in self.node:iter_children() do
+        if node:type() == target_type then
+            if target_row == nil or node:range() == target_row then
+                return self:create(node)
             end
         end
     end

lua/render-markdown/render/quote.lua

@@ -1,8 +1,10 @@
 local Base = require('render-markdown.render.base')
+local List = require('render-markdown.lib.list')
 local ts = require('render-markdown.integ.ts')
 
 ---@class render.md.quote.Data
 ---@field query vim.treesitter.Query
+---@field level integer
 ---@field icon string
 ---@field highlight string
 ---@field repeat_linebreak? boolean
@@ -18,44 +20,56 @@ function Render:setup()
     if self.context:skip(config) then
         return false
     end
-
+    local level = self.node:level_in_section('block_quote')
     local callout = self.context:get_callout(self.node.start_row)
-
     self.data = {
         query = ts.parse(
             'markdown',
             [[
-                [
-                    (block_quote_marker)
-                    (block_continuation)
-                ] @quote_marker
+                (block_quote_marker) @marker
+                (block_continuation) @continuation
             ]]
         ),
-        icon = callout ~= nil and callout.quote_icon or config.icon,
-        highlight = callout ~= nil and callout.highlight or config.highlight,
+        level = level,
+        icon = callout ~= nil and callout.quote_icon
+            or assert(List.cycle(config.icon, level)),
+        highlight = callout ~= nil and callout.highlight
+            or assert(List.cycle(config.highlight, level)),
         repeat_linebreak = config.repeat_linebreak or nil,
     }
-
     return true
 end
 
 function Render:render()
     self.context:query(self.node:get(), self.data.query, function(capture, node)
-        assert(
-            capture == 'quote_marker',
-            'Unhandled quote capture: ' .. capture
-        )
-        self:quote_marker(node)
+        if capture == 'marker' then
+            -- marker nodes are a single '>' at the start of a block quote
+            -- overlay the only range if it is at the current level
+            if node:level_in_section('block_quote') == self.data.level then
+                self:quote(node, 1)
+            end
+        elseif capture == 'continuation' then
+            -- continuation nodes are a group of '>'s inside a block quote
+            -- overlay the range of the one at the current level if it exists
+            self:quote(node, self.data.level)
+        else
+            error('Unhandled quote capture: ' .. capture)
+        end
     end)
 end
 
 ---@private
 ---@param node render.md.Node
-function Render:quote_marker(node)
-    self.marks:over('quote', node, {
-        virt_text = {
-            { node.text:gsub('>', self.data.icon), self.data.highlight },
-        },
+---@param index integer
+function Render:quote(node, index)
+    local range = node:find('>')[index]
+    if range == nil then
+        return
+    end
+    self.marks:add('quote', range[1], range[2], {
+        end_row = range[3],
+        end_col = range[4],
+        virt_text = { { self.data.icon, self.data.highlight } },
         virt_text_pos = 'overlay',
         virt_text_repeat_linebreak = self.data.repeat_linebreak,
     })

lua/render-markdown/render/section.lua

@@ -16,25 +16,23 @@ function Render:setup()
     if self.context:skip(self.info) then
         return false
     end
-
     local current_level = self.node:level(false)
     local parent_level = math.max(self.node:level(true), self.info.skip_level)
-    self.data = {
-        level_change = current_level - parent_level,
-    }
-
-    -- Nothing to do if there is not a change in level
-    if self.data.level_change <= 0 then
+    local level_change = current_level - parent_level
+    -- nothing to do if there is not a change in level
+    if level_change <= 0 then
         return false
     end
-
+    self.data = {
+        level_change = level_change,
+    }
     return true
 end
 
 function Render:render()
-    local start_row = self:get_start_row()
-    local end_row = self:get_end_row()
-    -- Each level stacks inline marks so we only need to process change in level
+    local start_row = math.max(self.node.start_row + self:start_below(), 0)
+    local end_row = self.node.end_row - 1 - self:end_above()
+    -- each level stacks inline marks so we only add changes in level
     local virt_text = self:indent_line(false, self.data.level_change)
     for row = start_row, end_row do
         self.marks:add(false, row, 0, {
@@ -47,41 +45,34 @@ end
 
 ---@private
 ---@return integer
-function Render:get_start_row()
+function Render:start_below()
     if self.info.skip_heading then
-        -- Exclude any lines potentially used by section heading
-        local second = self.node:line('first', 1)
-        local offset = Str.width(second) == 0 and 1 or 0
-        return self.node.start_row + 1 + offset
+        -- exclude second line of current section if empty
+        local empty = Str.width(self.node:line('first', 1)) == 0
+        return empty and 2 or 1
     else
-        -- Include last empty line in previous section
-        -- Exclude if it is the only empty line in that section
-        local above = self.node:line('above', 1)
-        local two_above = self.node:line('above', 2)
-        local above_is_empty = Str.width(above) == 0
-        local two_above_is_section = self:is_section(two_above)
-        local offset = (above_is_empty and not two_above_is_section) and 1 or 0
-        return math.max(self.node.start_row - offset, 0)
+        -- include last line of previous section if empty
+        -- skip if it is the only line in the previous section
+        local empty = Str.width(self.node:line('above', 1)) == 0
+        local only = self:section(self.node:line('above', 2))
+        return (empty and not only) and -1 or 0
     end
 end
 
 ---@private
 ---@return integer
-function Render:get_end_row()
-    -- Exclude last empty line in current section
-    -- Include if it is the only empty line of the last subsection
-    local last = self.node:line('last', 0)
-    local second_last = self.node:line('last', 1)
-    local last_is_empty = Str.width(last) == 0
-    local second_last_is_section = self:is_section(second_last)
-    local offset = (last_is_empty and not second_last_is_section) and 1 or 0
-    return self.node.end_row - 1 - offset
+function Render:end_above()
+    -- exclude last line of current section if empty
+    -- skip if it is the only line in the last nested section
+    local empty = Str.width(self.node:line('last', 0)) == 0
+    local only = self:section(self.node:line('last', 1))
+    return (empty and not only) and 1 or 0
 end
 
 ---@private
 ---@param line? string
 ---@return boolean
-function Render:is_section(line)
+function Render:section(line)
     return line ~= nil and vim.startswith(line, '#')
 end
 

lua/render-markdown/types.lua

@@ -245,9 +245,9 @@
 ---@field filler? string
 
 ---@class (exact) render.md.quote.UserConfig: render.md.base.UserConfig
----@field icon? string
+---@field icon? string|string[]
 ---@field repeat_linebreak? boolean
----@field highlight? string
+---@field highlight? string|string[]
 
 ---@class (exact) render.md.sign.UserConfig
 ---@field enabled? boolean

tests/box_dash_quote_spec.lua

@@ -40,8 +40,8 @@ describe('box_dash_quote.md', function()
             virt_text_pos = 'overlay',
         })
 
-        marks:add(row:inc(2), row:get(), 0, 4, util.quote('  %s ', 'RmQuote'))
-        marks:add(row:inc(), row:get(), 0, 4, util.quote('  %s ', 'RmQuote'))
+        marks:add(row:inc(2), row:get(), 2, 3, util.quote('RmQuote'))
+        marks:add(row:inc(), row:get(), 2, 3, util.quote('RmQuote'))
 
         util.assert_view(marks, {
             '󰫎 󰲡 Checkbox / Dash / Quote',