feat: allow heading icons to be a function, provide section nesting as input

## Details

Request: #286

This change allows `heading.icons` to be a function which returns a
`string` that will be used as the icon. The input to the function is an
`integer[]` which describes the nesting level of the current heading at
all parent levels.

An example configuration would look like:

```lua
require('render-markdown').setup({
    heading = {
        icons = function(sections)
            return table.concat(sections, '.') .. '. '
        end,
    },
})
```

Which when rendering:

```
# Foo
# Bar
## Baz
```

Results in:

```
1. Foo
2. Bar
2.1. Baz
```

Author: MeanderingProgrammer

README.md

@@ -259,15 +259,16 @@ require('render-markdown').setup({
         render_modes = false,
         -- Turn on / off any sign column related rendering
         sign = true,
+        -- Replaces '#+' of 'atx_h._marker'
+        -- The number of '#' in the heading determines the 'level'
+        -- The 'level' is used to index into the list using a cycle
+        -- If the value is a function the input is the nesting level of the heading within sections
+        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Determines how icons fill the available space:
         --  right:   '#'s are concealed and icon is appended to right side
         --  inline:  '#'s are concealed and icon is inlined on left side
         --  overlay: icon is left padded with spaces and inserted on left hiding any additional '#'
         position = 'overlay',
-        -- Replaces '#+' of 'atx_h._marker'
-        -- The number of '#' in the heading determines the 'level'
-        -- The 'level' is used to index into the list using a cycle
-        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Added to the sign column if enabled
         -- The 'level' is used to index into the list using a cycle
         signs = { '󰫎 ' },
@@ -734,15 +735,16 @@ require('render-markdown').setup({
         render_modes = false,
         -- Turn on / off any sign column related rendering
         sign = true,
+        -- Replaces '#+' of 'atx_h._marker'
+        -- The number of '#' in the heading determines the 'level'
+        -- The 'level' is used to index into the list using a cycle
+        -- If the value is a function the input is the nesting level of the heading within sections
+        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Determines how icons fill the available space:
         --  right:   '#'s are concealed and icon is appended to right side
         --  inline:  '#'s are concealed and icon is inlined on left side
         --  overlay: icon is left padded with spaces and inserted on left hiding any additional '#'
         position = 'overlay',
-        -- Replaces '#+' of 'atx_h._marker'
-        -- The number of '#' in the heading determines the 'level'
-        -- The 'level' is used to index into the list using a cycle
-        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Added to the sign column if enabled
         -- The 'level' is used to index into the list using a cycle
         signs = { '󰫎 ' },

doc/render-markdown.txt

@@ -315,15 +315,16 @@ Default Configuration ~
             render_modes = false,
             -- Turn on / off any sign column related rendering
             sign = true,
+            -- Replaces '#+' of 'atx_h._marker'
+            -- The number of '#' in the heading determines the 'level'
+            -- The 'level' is used to index into the list using a cycle
+            -- If the value is a function the input is the nesting level of the heading within sections
+            icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
             -- Determines how icons fill the available space:
             --  right:   '#'s are concealed and icon is appended to right side
             --  inline:  '#'s are concealed and icon is inlined on left side
             --  overlay: icon is left padded with spaces and inserted on left hiding any additional '#'
             position = 'overlay',
-            -- Replaces '#+' of 'atx_h._marker'
-            -- The number of '#' in the heading determines the 'level'
-            -- The 'level' is used to index into the list using a cycle
-            icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
             -- Added to the sign column if enabled
             -- The 'level' is used to index into the list using a cycle
             signs = { '󰫎 ' },
@@ -788,15 +789,16 @@ Heading Configuration ~
             render_modes = false,
             -- Turn on / off any sign column related rendering
             sign = true,
+            -- Replaces '#+' of 'atx_h._marker'
+            -- The number of '#' in the heading determines the 'level'
+            -- The 'level' is used to index into the list using a cycle
+            -- If the value is a function the input is the nesting level of the heading within sections
+            icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
             -- Determines how icons fill the available space:
             --  right:   '#'s are concealed and icon is appended to right side
             --  inline:  '#'s are concealed and icon is inlined on left side
             --  overlay: icon is left padded with spaces and inserted on left hiding any additional '#'
             position = 'overlay',
-            -- Replaces '#+' of 'atx_h._marker'
-            -- The number of '#' in the heading determines the 'level'
-            -- The 'level' is used to index into the list using a cycle
-            icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
             -- Added to the sign column if enabled
             -- The 'level' is used to index into the list using a cycle
             signs = { '󰫎 ' },

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -171,13 +171,16 @@ local M = {}
 ---@field public left_margin? number
 ---@field public min_width? integer
 
+---@alias render.md.heading.Icons
+---| string[]
+---| fun(sections: integer[]): string?
 ---@alias render.md.heading.Position 'overlay'|'inline'|'right'
 ---@alias render.md.heading.Width 'full'|'block'
 
 ---@class (exact) render.md.UserHeading: render.md.UserBaseComponent
 ---@field public sign? boolean
+---@field public icons? render.md.heading.Icons
 ---@field public position? render.md.heading.Position
----@field public icons? string[]
 ---@field public signs? string[]
 ---@field public width? render.md.heading.Width|(render.md.heading.Width)[]
 ---@field public left_margin? number|number[]
@@ -353,15 +356,16 @@ M.default_config = {
         render_modes = false,
         -- Turn on / off any sign column related rendering
         sign = true,
+        -- Replaces '#+' of 'atx_h._marker'
+        -- The number of '#' in the heading determines the 'level'
+        -- The 'level' is used to index into the list using a cycle
+        -- If the value is a function the input is the nesting level of the heading within sections
+        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Determines how icons fill the available space:
         --  right:   '#'s are concealed and icon is appended to right side
         --  inline:  '#'s are concealed and icon is inlined on left side
         --  overlay: icon is left padded with spaces and inserted on left hiding any additional '#'
         position = 'overlay',
-        -- Replaces '#+' of 'atx_h._marker'
-        -- The number of '#' in the heading determines the 'level'
-        -- The 'level' is used to index into the list using a cycle
-        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Added to the sign column if enabled
         -- The 'level' is used to index into the list using a cycle
         signs = { '󰫎 ' },

lua/render-markdown/lib/node.lua

@@ -48,6 +48,17 @@ function Node:has_error()
     return self.node:has_error()
 end
 
+---@return integer[]
+function Node:sections()
+    local result, section = {}, self:parent('section')
+    while section ~= nil do
+        local count = section:sibling_count('section')
+        table.insert(result, 1, count)
+        section = section:parent('section')
+    end
+    return result
+end
+
 ---@param parent boolean
 ---@return integer
 function Node:heading_level(parent)

lua/render-markdown/render/heading.lua

@@ -52,11 +52,18 @@ function Render:setup()
         return false
     end
 
+    local icon, icons = nil, self.heading.icons
+    if type(icons) == 'function' then
+        icon = icons(self.node:sections())
+    else
+        icon = List.cycle(icons, level)
+    end
+
     self.data = {
         atx = atx,
         marker = marker,
         level = level,
-        icon = List.cycle(self.heading.icons, level),
+        icon = icon,
         sign = List.cycle(self.heading.signs, level),
         foreground = List.clamp(self.heading.foregrounds, level),
         background = List.clamp(self.heading.backgrounds, level),

lua/render-markdown/state.lua

@@ -163,7 +163,8 @@ function M.validate()
                     :type({ 'above', 'below' }, 'string')
                     :list('border', 'boolean', 'boolean')
                     :list({ 'left_margin', 'left_pad', 'right_pad', 'min_width' }, 'number', 'number')
-                    :list({ 'icons', 'signs', 'backgrounds', 'foregrounds' }, 'string')
+                    :list({ 'signs', 'backgrounds', 'foregrounds' }, 'string')
+                    :list('icons', 'string', 'function')
                     :one_of('position', { 'overlay', 'inline', 'right' })
                     :one_or_list_of('width', { 'full', 'block' })
                     :check()

lua/render-markdown/types.lua

@@ -144,8 +144,8 @@
 
 ---@class (exact) render.md.Heading: render.md.BaseComponent
 ---@field public sign boolean
+---@field public icons render.md.heading.Icons
 ---@field public position render.md.heading.Position
----@field public icons string[]
 ---@field public signs string[]
 ---@field public width render.md.heading.Width|(render.md.heading.Width)[]
 ---@field public left_margin number|number[]