feat: support function for paragraph.left_margin

## Details

Request: #401

Allows `paragraph.left_margin` option to be a function that returns a
number based on the context in addition to a flat number. The context
provided currently is just the text value of the node, but can be
expanded in the future if needed.

This can be used to set a different margin based on the length of the
paragraph. For example use a margin of 4 for paragraphs longer than 80
characters, otherwise use no margin:

```lua
require('render-markdown').setup({
    paragraph = {
        left_margin = function(ctx)
            return #ctx.text > 80 and 4 or 0
        end,
    },
})
```

Author: MeanderingProgrammer

README.md

@@ -387,13 +387,18 @@ require('render-markdown').setup({
         -- | foreground | optional override for the foreground                  |
         custom = {},
     },
+    -- Useful context to have when evaluating values.
+    -- | text | text value of the node |
     paragraph = {
         -- Turn on / off paragraph rendering.
         enabled = true,
         -- Additional modes to render paragraphs.
         render_modes = false,
         -- Amount of margin to add to the left of paragraphs.
         -- If a float < 1 is provided it is treated as a percentage of available window space.
+        -- Output is evaluated depending on the type.
+        -- | function | `value(context)` |
+        -- | number   | `value`          |
         left_margin = 0,
         -- Minimum width to use for paragraphs.
         min_width = 0,
@@ -949,13 +954,18 @@ require('render-markdown').setup({
 
 ```lua
 require('render-markdown').setup({
+    -- Useful context to have when evaluating values.
+    -- | text | text value of the node |
     paragraph = {
         -- Turn on / off paragraph rendering.
         enabled = true,
         -- Additional modes to render paragraphs.
         render_modes = false,
         -- Amount of margin to add to the left of paragraphs.
         -- If a float < 1 is provided it is treated as a percentage of available window space.
+        -- Output is evaluated depending on the type.
+        -- | function | `value(context)` |
+        -- | number   | `value`          |
         left_margin = 0,
         -- Minimum width to use for paragraphs.
         min_width = 0,

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*           For 0.11.0          Last change: 2025 April 15
+*render-markdown.txt*           For 0.11.0          Last change: 2025 April 17
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -452,13 +452,18 @@ Default Configuration ~
             -- | foreground | optional override for the foreground                  |
             custom = {},
         },
+        -- Useful context to have when evaluating values.
+        -- | text | text value of the node |
         paragraph = {
             -- Turn on / off paragraph rendering.
             enabled = true,
             -- Additional modes to render paragraphs.
             render_modes = false,
             -- Amount of margin to add to the left of paragraphs.
             -- If a float < 1 is provided it is treated as a percentage of available window space.
+            -- Output is evaluated depending on the type.
+            -- | function | `value(context)` |
+            -- | number   | `value`          |
             left_margin = 0,
             -- Minimum width to use for paragraphs.
             min_width = 0,
@@ -1010,13 +1015,18 @@ Paragraph Configuration ~
 
 >lua
     require('render-markdown').setup({
+        -- Useful context to have when evaluating values.
+        -- | text | text value of the node |
         paragraph = {
             -- Turn on / off paragraph rendering.
             enabled = true,
             -- Additional modes to render paragraphs.
             render_modes = false,
             -- Amount of margin to add to the left of paragraphs.
             -- If a float < 1 is provided it is treated as a percentage of available window space.
+            -- Output is evaluated depending on the type.
+            -- | function | `value(context)` |
+            -- | number   | `value`          |
             left_margin = 0,
             -- Minimum width to use for paragraphs.
             min_width = 0,

lua/render-markdown/config/paragraph.lua

@@ -1,13 +1,20 @@
 ---@class (exact) render.md.paragraph.Config: render.md.base.Config
----@field left_margin number
+---@field left_margin render.md.paragraph.Margin
 ---@field min_width integer
 
+---@class (exact) render.md.paragraph.Context
+---@field text string
+
+---@alias render.md.paragraph.Margin
+---| number
+---| fun(ctx: render.md.paragraph.Context): number
+
 local M = {}
 
 ---@param spec render.md.debug.ValidatorSpec
 function M.validate(spec)
     require('render-markdown.config.base').validate(spec)
-    spec:type('left_margin', 'number')
+    spec:type('left_margin', { 'number', 'function' })
     spec:type('min_width', 'number')
     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.0'
+M.version = '8.3.1'
 
 function M.check()
     M.start('version')

lua/render-markdown/init.lua

@@ -256,13 +256,18 @@ M.default = {
         -- | foreground | optional override for the foreground                  |
         custom = {},
     },
+    -- Useful context to have when evaluating values.
+    -- | text | text value of the node |
     paragraph = {
         -- Turn on / off paragraph rendering.
         enabled = true,
         -- Additional modes to render paragraphs.
         render_modes = false,
         -- Amount of margin to add to the left of paragraphs.
         -- If a float < 1 is provided it is treated as a percentage of available window space.
+        -- Output is evaluated depending on the type.
+        -- | function | `value(context)` |
+        -- | number   | `value`          |
         left_margin = 0,
         -- Minimum width to use for paragraphs.
         min_width = 0,

lua/render-markdown/render/paragraph.lua

@@ -1,7 +1,11 @@
 local Base = require('render-markdown.render.base')
 
+---@class render.md.paragraph.Data
+---@field margin number
+
 ---@class render.md.render.Paragraph: render.md.Render
 ---@field private info render.md.paragraph.Config
+---@field private data render.md.paragraph.Data
 local Render = setmetatable({}, Base)
 Render.__index = Render
 
@@ -11,16 +15,28 @@ function Render:setup()
     if self.context:skip(self.info) then
         return false
     end
-    if self.info.left_margin <= 0 then
+
+    local margin, left_margin = nil, self.info.left_margin
+    if type(left_margin) == 'function' then
+        margin = left_margin({ text = self.node.text })
+    else
+        margin = left_margin
+    end
+
+    if margin <= 0 then
         return false
     end
+    self.data = {
+        margin = margin,
+    }
+
     return true
 end
 
 function Render:render()
     local width = vim.fn.max(self.node:widths())
     width = math.max(width, self.info.min_width)
-    local margin = self.context:percent(self.info.left_margin, width)
+    local margin = self.context:percent(self.data.margin, width)
     local line = self:append({}, margin)
     if #line == 0 then
         return

lua/render-markdown/render/quote.lua

@@ -14,8 +14,8 @@ Render.__index = Render
 
 ---@return boolean
 function Render:setup()
-    local quote = self.config.quote
-    if self.context:skip(quote) then
+    local config = self.config.quote
+    if self.context:skip(config) then
         return false
     end
 
@@ -31,9 +31,9 @@ function Render:setup()
                 ] @quote_marker
             ]]
         ),
-        icon = callout ~= nil and callout.quote_icon or quote.icon,
-        highlight = callout ~= nil and callout.highlight or quote.highlight,
-        repeat_linebreak = quote.repeat_linebreak or nil,
+        icon = callout ~= nil and callout.quote_icon or config.icon,
+        highlight = callout ~= nil and callout.highlight or config.highlight,
+        repeat_linebreak = config.repeat_linebreak or nil,
     }
 
     return true

lua/render-markdown/render/section.lua

@@ -1,9 +1,12 @@
 local Base = require('render-markdown.render.base')
 local Str = require('render-markdown.lib.str')
 
+---@class render.md.indent.Data
+---@field level_change integer
+
 ---@class render.md.render.Section: render.md.Render
 ---@field private info render.md.indent.Config
----@field private level_change integer
+---@field private data render.md.indent.Data
 local Render = setmetatable({}, Base)
 Render.__index = Render
 
@@ -16,10 +19,12 @@ function Render:setup()
 
     local current_level = self.node:level(false)
     local parent_level = math.max(self.node:level(true), self.info.skip_level)
-    self.level_change = current_level - parent_level
+    self.data = {
+        level_change = current_level - parent_level,
+    }
 
     -- Nothing to do if there is not a change in level
-    if self.level_change <= 0 then
+    if self.data.level_change <= 0 then
         return false
     end
 
@@ -30,7 +35,7 @@ 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 virt_text = self:indent_line(false, self.level_change)
+    local virt_text = self:indent_line(false, self.data.level_change)
     for row = start_row, end_row do
         self.marks:add(false, row, 0, {
             priority = 0,

lua/render-markdown/types.lua

@@ -221,7 +221,7 @@
 ---@field highlight? string
 
 ---@class (exact) render.md.paragraph.UserConfig: render.md.base.UserConfig
----@field left_margin? number
+---@field left_margin? render.md.paragraph.Margin
 ---@field min_width? integer
 
 ---@class (exact) render.md.pattern.UserConfig