feat: add left_pad, right_pad, & min_width for headings

# Details

Request: #121

This adds 3 additional heading parameters, left_pad, right_pad, and
min_width.

This works in an identical way to the same parameters in code blocks.

left_pad can be used with any width attribute, whereas right_pad and
min_width are only used for 'block' width.

We do need to take additional care of various concealing behaviors
which adds a bit of complexity.

left_pad: moves the heading line to the left
right_pad: adds a margin of background to the end of block width headings
min_width: ensures that the same padding extends at least to the
specified value making a uniform look easier

Author: MeanderingProgrammer

Diff for: README.md

@@ -245,6 +245,12 @@ require('render-markdown').setup({
         --  block: width of the heading text
         --  full: full width of the window
         width = 'full',
+        -- Amount of padding to add to the left of headings
+        left_pad = 0,
+        -- Amount of padding to add to the right of headings when width is 'block'
+        right_pad = 0,
+        -- Minimum width to use for headings when width is 'block'
+        min_width = 0,
         -- The 'level' is used to index into the array using a clamp
         -- Highlight for the heading icon and extends through the entire line
         backgrounds = {
@@ -284,16 +290,16 @@ require('render-markdown').setup({
         -- An array of language names for which background highlighting will be disabled
         -- Likely because that language has background highlights itself
         disable_background = { 'diff' },
+        -- Width of the code block background:
+        --  block: width of the code block
+        --  full: full width of the window
+        width = 'full',
         -- Amount of padding to add to the left of code blocks
         left_pad = 0,
         -- Amount of padding to add to the right of code blocks when width is 'block'
         right_pad = 0,
         -- Minimum width to use for code blocks when width is 'block'
         min_width = 0,
-        -- Width of the code block background:
-        --  block: width of the code block
-        --  full: full width of the window
-        width = 'full',
         -- Determins how the top / bottom of code block are rendered:
         --  thick: use the same highlight as the code body
         --  thin: when lines are empty overlay the above & below icons
@@ -526,6 +532,12 @@ require('render-markdown').setup({
         --  block: width of the heading text
         --  full: full width of the window
         width = 'full',
+        -- Amount of padding to add to the left of headings
+        left_pad = 0,
+        -- Amount of padding to add to the right of headings when width is 'block'
+        right_pad = 0,
+        -- Minimum width to use for headings when width is 'block'
+        min_width = 0,
         -- The 'level' is used to index into the array using a clamp
         -- Highlight for the heading icon and extends through the entire line
         backgrounds = {
@@ -572,16 +584,16 @@ require('render-markdown').setup({
         -- An array of language names for which background highlighting will be disabled
         -- Likely because that language has background highlights itself
         disable_background = { 'diff' },
+        -- Width of the code block background:
+        --  block: width of the code block
+        --  full: full width of the window
+        width = 'full',
         -- Amount of padding to add to the left of code blocks
         left_pad = 0,
         -- Amount of padding to add to the right of code blocks when width is 'block'
         right_pad = 0,
         -- Minimum width to use for code blocks when width is 'block'
         min_width = 0,
-        -- Width of the code block background:
-        --  block: width of the code block
-        --  full: full width of the window
-        width = 'full',
         -- Determins how the top / bottom of code block are rendered:
         --  thick: use the same highlight as the code body
         --  thin: when lines are empty overlay the above & below icons

Diff for: doc/render-markdown.txt

@@ -273,6 +273,12 @@ Full Default Configuration ~
             --  block: width of the heading text
             --  full: full width of the window
             width = 'full',
+            -- Amount of padding to add to the left of headings
+            left_pad = 0,
+            -- Amount of padding to add to the right of headings when width is 'block'
+            right_pad = 0,
+            -- Minimum width to use for headings when width is 'block'
+            min_width = 0,
             -- The 'level' is used to index into the array using a clamp
             -- Highlight for the heading icon and extends through the entire line
             backgrounds = {
@@ -312,16 +318,16 @@ Full Default Configuration ~
             -- An array of language names for which background highlighting will be disabled
             -- Likely because that language has background highlights itself
             disable_background = { 'diff' },
+            -- Width of the code block background:
+            --  block: width of the code block
+            --  full: full width of the window
+            width = 'full',
             -- Amount of padding to add to the left of code blocks
             left_pad = 0,
             -- Amount of padding to add to the right of code blocks when width is 'block'
             right_pad = 0,
             -- Minimum width to use for code blocks when width is 'block'
             min_width = 0,
-            -- Width of the code block background:
-            --  block: width of the code block
-            --  full: full width of the window
-            width = 'full',
             -- Determins how the top / bottom of code block are rendered:
             --  thick: use the same highlight as the code body
             --  thin: when lines are empty overlay the above & below icons
@@ -553,6 +559,12 @@ HEADINGS                                      *render-markdown-setup-headings*
             --  block: width of the heading text
             --  full: full width of the window
             width = 'full',
+            -- Amount of padding to add to the left of headings
+            left_pad = 0,
+            -- Amount of padding to add to the right of headings when width is 'block'
+            right_pad = 0,
+            -- Minimum width to use for headings when width is 'block'
+            min_width = 0,
             -- The 'level' is used to index into the array using a clamp
             -- Highlight for the heading icon and extends through the entire line
             backgrounds = {
@@ -600,16 +612,16 @@ CODE BLOCKS                                *render-markdown-setup-code-blocks*
             -- An array of language names for which background highlighting will be disabled
             -- Likely because that language has background highlights itself
             disable_background = { 'diff' },
+            -- Width of the code block background:
+            --  block: width of the code block
+            --  full: full width of the window
+            width = 'full',
             -- Amount of padding to add to the left of code blocks
             left_pad = 0,
             -- Amount of padding to add to the right of code blocks when width is 'block'
             right_pad = 0,
             -- Minimum width to use for code blocks when width is 'block'
             min_width = 0,
-            -- Width of the code block background:
-            --  block: width of the code block
-            --  full: full width of the window
-            width = 'full',
             -- Determins how the top / bottom of code block are rendered:
             --  thick: use the same highlight as the code body
             --  thin: when lines are empty overlay the above & below icons

Diff for: lua/render-markdown/handler/markdown.lua

@@ -83,28 +83,63 @@ function Handler:heading(info)
     end
 
     local level = str.width(info.text)
-    local icon = list.cycle(heading.icons, level)
     local foreground = list.clamp(heading.foregrounds, level)
     local background = list.clamp(heading.backgrounds, level)
 
+    local icon_width = self:heading_icon(info, level, foreground, background)
+    if heading.sign then
+        self:sign(info, list.cycle(heading.signs, level), foreground)
+    end
+
     self:add(true, info.start_row, 0, {
         end_row = info.end_row + 1,
         end_col = 0,
         hl_group = background,
-        hl_eol = heading.width == 'full',
+        hl_eol = true,
     })
 
-    if heading.sign then
-        self:sign(info, list.cycle(heading.signs, level), foreground)
+    if heading.width == 'block' then
+        -- Overwrite anything beyond left_pad + heading width + right_pad with Normal
+        local width = heading.left_pad + icon_width + heading.right_pad
+        local content = ts.sibling(self.buf, info, 'inline')
+        if content ~= nil then
+            width = width + str.width(content.text) - ts.concealed(self.buf, content)
+        end
+        self:add(true, info.start_row, 0, {
+            priority = 0,
+            virt_text = { { str.pad(vim.o.columns * 2), 'Normal' } },
+            virt_text_win_col = math.max(width, heading.min_width),
+        })
     end
 
-    if icon == nil then
-        return
+    if heading.left_pad > 0 then
+        self:add(false, info.start_row, 0, {
+            priority = 0,
+            virt_text = { { str.pad(heading.left_pad), background } },
+            virt_text_pos = 'inline',
+        })
     end
+end
+
+---@private
+---@param info render.md.NodeInfo
+---@param level integer
+---@param foreground string
+---@param background string
+---@return integer
+function Handler:heading_icon(info, level, foreground, background)
+    local heading = self.config.heading
+    local icon = list.cycle(heading.icons, level)
+
     -- Available width is level + 1 - concealed, where level = number of `#` characters, one
     -- is added to account for the space after the last `#` but before the heading title,
     -- and concealed text is subtracted since that space is not usable
-    local padding = level + 1 - ts.concealed(self.buf, info) - str.width(icon)
+    local width = level + 1 - ts.concealed(self.buf, info)
+    if icon == nil then
+        return width
+    end
+
+    local padding = width - str.width(icon)
     if heading.position == 'inline' or padding < 0 then
         self:add(true, info.start_row, info.start_col, {
             end_row = info.end_row,
@@ -113,13 +148,15 @@ function Handler:heading(info)
             virt_text_pos = 'inline',
             conceal = '',
         })
+        return str.width(icon)
     else
         self:add(true, info.start_row, info.start_col, {
             end_row = info.end_row,
             end_col = info.end_col,
             virt_text = { { str.pad(padding, icon), { foreground, background } } },
             virt_text_pos = 'overlay',
         })
+        return width
     end
 end
 
@@ -284,7 +321,6 @@ function Handler:code_left_pad(code_block, add_background)
     for row = code_block.start_row, code_block.end_row - 1 do
         -- Uses a low priority so other marks are loaded first and included in padding
         self:add(false, row, code_block.col, {
-            end_row = row + 1,
             priority = 0,
             virt_text = { { padding, highlight } },
             virt_text_pos = 'inline',

Diff for: lua/render-markdown/handler/markdown_inline.lua

@@ -73,21 +73,28 @@ function Handler:shortcut(info)
         self:callout(info, callout)
         return
     end
+
     local checkbox = component.checkbox(self.config, info.text, 'exact')
     if checkbox ~= nil then
         self:checkbox(info, checkbox)
         return
     end
+
     local line = vim.api.nvim_buf_get_lines(self.buf, info.start_row, info.start_row + 1, false)[1]
     if line:find('[' .. info.text .. ']', 1, true) ~= nil then
         self:wiki_link(info)
+        return
     end
 end
 
 ---@private
 ---@param info render.md.NodeInfo
 ---@param callout render.md.CustomComponent
 function Handler:callout(info, callout)
+    if not self.config.quote.enabled then
+        return
+    end
+
     ---Support for overriding title: https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title
     ---@return string, string?
     local function custom_title()
@@ -103,9 +110,6 @@ function Handler:callout(info, callout)
         return callout.rendered, nil
     end
 
-    if not self.config.quote.enabled then
-        return
-    end
     local text, conceal = custom_title()
     self:add(info.start_row, info.start_col, {
         end_row = info.end_row,

Diff for: lua/render-markdown/health.lua

@@ -5,7 +5,7 @@ local M = {}
 
 ---@private
 ---@type string
-M.version = '6.0.3'
+M.version = '6.0.4'
 
 function M.check()
     vim.health.start('render-markdown.nvim [version]')

Diff for: lua/render-markdown/init.lua

@@ -88,10 +88,10 @@ local M = {}
 ---@field public style? 'full'|'normal'|'language'|'none'
 ---@field public position? 'left'|'right'
 ---@field public disable_background? string[]
+---@field public width? 'full'|'block'
 ---@field public left_pad? integer
 ---@field public right_pad? integer
 ---@field public min_width? integer
----@field public width? 'full'|'block'
 ---@field public border? 'thin'|'thick'
 ---@field public above? string
 ---@field public below? string
@@ -105,6 +105,9 @@ local M = {}
 ---@field public icons? string[]
 ---@field public signs? string[]
 ---@field public width? 'full'|'block'
+---@field public left_pad? integer
+---@field public right_pad? integer
+---@field public min_width? integer
 ---@field public backgrounds? string[]
 ---@field public foregrounds? string[]
 
@@ -251,6 +254,12 @@ M.default_config = {
         --  block: width of the heading text
         --  full: full width of the window
         width = 'full',
+        -- Amount of padding to add to the left of headings
+        left_pad = 0,
+        -- Amount of padding to add to the right of headings when width is 'block'
+        right_pad = 0,
+        -- Minimum width to use for headings when width is 'block'
+        min_width = 0,
         -- The 'level' is used to index into the array using a clamp
         -- Highlight for the heading icon and extends through the entire line
         backgrounds = {
@@ -290,16 +299,16 @@ M.default_config = {
         -- An array of language names for which background highlighting will be disabled
         -- Likely because that language has background highlights itself
         disable_background = { 'diff' },
+        -- Width of the code block background:
+        --  block: width of the code block
+        --  full: full width of the window
+        width = 'full',
         -- Amount of padding to add to the left of code blocks
         left_pad = 0,
         -- Amount of padding to add to the right of code blocks when width is 'block'
         right_pad = 0,
         -- Minimum width to use for code blocks when width is 'block'
         min_width = 0,
-        -- Width of the code block background:
-        --  block: width of the code block
-        --  full: full width of the window
-        width = 'full',
         -- Determins how the top / bottom of code block are rendered:
         --  thick: use the same highlight as the code body
         --  thin: when lines are empty overlay the above & below icons

Diff for: lua/render-markdown/state.lua

@@ -169,6 +169,9 @@ function M.validate()
                 icons = string_array(heading.icons, nilable),
                 signs = string_array(heading.signs, nilable),
                 width = one_of(heading.width, { 'full', 'block' }, {}, nilable),
+                left_pad = { heading.left_pad, 'number', nilable },
+                right_pad = { heading.right_pad, 'number', nilable },
+                min_width = { heading.min_width, 'number', nilable },
                 backgrounds = string_array(heading.backgrounds, nilable),
                 foregrounds = string_array(heading.foregrounds, nilable),
             })
@@ -182,10 +185,10 @@ function M.validate()
                 style = one_of(code.style, { 'full', 'normal', 'language', 'none' }, {}, nilable),
                 position = one_of(code.position, { 'left', 'right' }, {}, nilable),
                 disable_background = string_array(code.disable_background, nilable),
+                width = one_of(code.width, { 'full', 'block' }, {}, nilable),
                 left_pad = { code.left_pad, 'number', nilable },
                 right_pad = { code.right_pad, 'number', nilable },
                 min_width = { code.min_width, 'number', nilable },
-                width = one_of(code.width, { 'full', 'block' }, {}, nilable),
                 border = one_of(code.border, { 'thin', 'thick' }, {}, nilable),
                 above = { code.above, 'string', nilable },
                 below = { code.below, 'string', nilable },

Diff for: lua/render-markdown/types.lua

@@ -77,10 +77,10 @@
 ---@field public style 'full'|'normal'|'language'|'none'
 ---@field public position 'left'|'right'
 ---@field public disable_background string[]
+---@field public width 'full'|'block'
 ---@field public left_pad integer
 ---@field public right_pad integer
 ---@field public min_width integer
----@field public width 'full'|'block'
 ---@field public border 'thin'|'thick'
 ---@field public above string
 ---@field public below string
@@ -94,6 +94,9 @@
 ---@field public icons string[]
 ---@field public signs string[]
 ---@field public width 'full'|'block'
+---@field public left_pad integer
+---@field public right_pad integer
+---@field public min_width integer
 ---@field public backgrounds string[]
 ---@field public foregrounds string[]