feat: heading padding options allow arrays, opt in always virtual border

## Details

Request 1: #182

This change adds support for 2 features.

The first is around the padding options for headings. For each of:

- `left_margin`
- `left_pad`
- `right_pad`
- `min_width`

We now accept an array of numbers in addition to a single number. When
the value is an array we index it using the level and we clamp the last
value. This is the same behavior we support for `width`.

Request 2: #183

This request is simply to allow using virtual lines for heading borders
all the time rather than trying to overlay borders on empty lines.

This can now be opted in to by setting `border_virtual` to `true`.

Author: MeanderingProgrammer

CHANGELOG.md

@@ -13,6 +13,9 @@
   [0986638](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/0986638b381a4b01eb108bb946f3a67a9eb3d0ec)
   [67288fe](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/67288febca78b7aac8fae9543ef8980237e27d2a)
 - integrate with lazy.nvim filetypes [cb9a5e2](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/cb9a5e2412d21c7a89627e0d6da5459acbc0eb9c)
+- bullet left & right padding on all lines of items [#181](https://github.com/MeanderingProgrammer/render-markdown.nvim/issues/181)
+  [3adb9d5](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/3adb9d539a016bc63fee83aa740e38fa4eeab094)
+
 
 ### Bug Fixes
 

README.md

@@ -260,17 +260,23 @@ require('render-markdown').setup({
         -- Amount of margin to add to the left of headings
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         -- Margin available space is computed after accounting for padding
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         left_margin = 0,
         -- Amount of padding to add to the left of headings
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         left_pad = 0,
         -- Amount of padding to add to the right of headings when width is 'block'
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
+        -- Can also be an array of integers in which case the 'level' is used to index into the array using a clamp
         min_width = 0,
         -- Determins if a border is added above and below headings
         border = false,
+        -- Alway use virtual lines for heading borders instead of attempting to use empty lines
+        border_virtual = false,
         -- Highlight the start of the border using the foreground highlight
         border_prefix = false,
         -- Used above heading for border
@@ -622,17 +628,23 @@ require('render-markdown').setup({
         -- Amount of margin to add to the left of headings
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         -- Margin available space is computed after accounting for padding
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         left_margin = 0,
         -- Amount of padding to add to the left of headings
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         left_pad = 0,
         -- Amount of padding to add to the right of headings when width is 'block'
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
+        -- Can also be an array of integers in which case the 'level' is used to index into the array using a clamp
         min_width = 0,
         -- Determins if a border is added above and below headings
         border = false,
+        -- Alway use virtual lines for heading borders instead of attempting to use empty lines
+        border_virtual = false,
         -- Highlight the start of the border using the foreground highlight
         border_prefix = false,
         -- Used above heading for border

doc/render-markdown.txt

@@ -306,17 +306,23 @@ Default Configuration ~
             -- Amount of margin to add to the left of headings
             -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             -- Margin available space is computed after accounting for padding
+            -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
             left_margin = 0,
             -- Amount of padding to add to the left of headings
             -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
             left_pad = 0,
             -- Amount of padding to add to the right of headings when width is 'block'
             -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
             right_pad = 0,
             -- Minimum width to use for headings when width is 'block'
+            -- Can also be an array of integers in which case the 'level' is used to index into the array using a clamp
             min_width = 0,
             -- Determins if a border is added above and below headings
             border = false,
+            -- Alway use virtual lines for heading borders instead of attempting to use empty lines
+            border_virtual = false,
             -- Highlight the start of the border using the foreground highlight
             border_prefix = false,
             -- Used above heading for border
@@ -666,17 +672,23 @@ Heading Configuration ~
             -- Amount of margin to add to the left of headings
             -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             -- Margin available space is computed after accounting for padding
+            -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
             left_margin = 0,
             -- Amount of padding to add to the left of headings
             -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
             left_pad = 0,
             -- Amount of padding to add to the right of headings when width is 'block'
             -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
             right_pad = 0,
             -- Minimum width to use for headings when width is 'block'
+            -- Can also be an array of integers in which case the 'level' is used to index into the array using a clamp
             min_width = 0,
             -- Determins if a border is added above and below headings
             border = false,
+            -- Alway use virtual lines for heading borders instead of attempting to use empty lines
+            border_virtual = false,
             -- Highlight the start of the border using the foreground highlight
             border_prefix = false,
             -- Used above heading for border

lua/render-markdown/debug/validator.lua

@@ -66,24 +66,25 @@ function Spec:one_of(keys, values, input_types)
 end
 
 ---@param keys string|string[]
+---@param array_type type
 ---@param input_types? type|type[]
 ---@return render.md.debug.ValidatorSpec
-function Spec:string_array(keys, input_types)
+function Spec:array(keys, array_type, input_types)
     local types, suffix = self:handle_types(input_types)
     return self:add(keys, function(v)
         if vim.tbl_contains(types, type(v)) then
             return true
         elseif type(v) == 'table' then
             for i, item in ipairs(v) do
-                if type(item) ~= 'string' then
+                if type(item) ~= array_type then
                     return false, string.format('Index %d is %s', i, type(item))
                 end
             end
             return true
         else
             return false
         end
-    end, 'string array' .. suffix)
+    end, array_type .. ' array' .. suffix)
 end
 
 ---@param keys string|string[]

lua/render-markdown/health.lua

@@ -4,7 +4,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '7.1.10'
+M.version = '7.1.11'
 
 function M.check()
     M.start('version')

lua/render-markdown/init.lua

@@ -135,11 +135,12 @@ local M = {}
 ---@field public icons? string[]
 ---@field public signs? string[]
 ---@field public width? render.md.heading.Width|(render.md.heading.Width)[]
----@field public left_margin? number
----@field public left_pad? number
----@field public right_pad? number
----@field public min_width? integer
+---@field public left_margin? number|number[]
+---@field public left_pad? number|number[]
+---@field public right_pad? number|number[]
+---@field public min_width? integer|integer[]
 ---@field public border? boolean
+---@field public border_virtual? boolean
 ---@field public border_prefix? boolean
 ---@field public above? string
 ---@field public below? string
@@ -332,17 +333,23 @@ M.default_config = {
         -- Amount of margin to add to the left of headings
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         -- Margin available space is computed after accounting for padding
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         left_margin = 0,
         -- Amount of padding to add to the left of headings
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         left_pad = 0,
         -- Amount of padding to add to the right of headings when width is 'block'
         -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Can also be an array of numbers in which case the 'level' is used to index into the array using a clamp
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
+        -- Can also be an array of integers in which case the 'level' is used to index into the array using a clamp
         min_width = 0,
         -- Determins if a border is added above and below headings
         border = false,
+        -- Alway use virtual lines for heading borders instead of attempting to use empty lines
+        border_virtual = false,
         -- Highlight the start of the border using the foreground highlight
         border_prefix = false,
         -- Used above heading for border

lua/render-markdown/render/heading.lua

@@ -10,7 +10,11 @@ local str = require('render-markdown.core.str')
 ---@field sign? string
 ---@field foreground string
 ---@field background string
----@field heading_width render.md.heading.Width
+---@field width render.md.heading.Width
+---@field left_margin number
+---@field left_pad number
+---@field right_pad number
+---@field min_width integer
 ---@field end_row integer
 
 ---@class render.md.width.Heading
@@ -47,25 +51,37 @@ function Render:setup()
         atx, level = true, str.width(self.info.text)
     end
 
-    local heading_width = self.heading.width
-    if type(heading_width) == 'table' then
-        heading_width = list.clamp(heading_width, level)
-    end
-
     self.data = {
         atx = atx,
         level = level,
         icon = list.cycle(self.heading.icons, level),
         sign = list.cycle(self.heading.signs, level),
         foreground = list.clamp(self.heading.foregrounds, level),
         background = list.clamp(self.heading.backgrounds, level),
-        heading_width = heading_width,
+        width = Render.resolve(self.heading.width, level),
+        left_margin = Render.resolve(self.heading.left_margin, level),
+        left_pad = Render.resolve(self.heading.left_pad, level),
+        right_pad = Render.resolve(self.heading.right_pad, level),
+        min_width = Render.resolve(self.heading.min_width, level),
         end_row = self.info.end_row + (atx and 1 or 0),
     }
 
     return true
 end
 
+---@private
+---@generic T
+---@param values `T`|T[]
+---@param level integer
+---@return T
+function Render.resolve(values, level)
+    if type(values) == 'table' then
+        return list.clamp(values, level)
+    else
+        return values
+    end
+end
+
 function Render:render()
     local width = self:width(self:icon())
     if self.heading.sign then
@@ -139,22 +155,22 @@ function Render:width(icon_width)
         text_width = vim.fn.max(vim.tbl_map(str.width, self.info:lines()))
     end
     local width = icon_width + text_width
-    local left_padding = self.context:resolve_offset(self.heading.left_pad, width)
-    local right_padding = self.context:resolve_offset(self.heading.right_pad, width)
-    width = math.max(left_padding + width + right_padding, self.heading.min_width)
+    local left_padding = self.context:resolve_offset(self.data.left_pad, width)
+    local right_padding = self.context:resolve_offset(self.data.right_pad, width)
+    width = math.max(left_padding + width + right_padding, self.data.min_width)
     ---@type render.md.width.Heading
     return {
-        margin = self.context:resolve_offset(self.heading.left_margin, width),
+        margin = self.context:resolve_offset(self.data.left_margin, width),
         padding = left_padding,
-        content = self.data.heading_width == 'block' and width or self.context:get_width(),
+        content = self.data.width == 'block' and width or self.context:get_width(),
     }
 end
 
 ---@private
 ---@param width render.md.width.Heading
 function Render:background(width)
     local win_col, padding = 0, {}
-    if self.data.heading_width == 'block' then
+    if self.data.width == 'block' then
         win_col = width.margin + width.content + self:indent(self.data.level)
         table.insert(padding, { str.pad(vim.o.columns * 2), self.config.padding.highlight })
     end
@@ -185,6 +201,7 @@ function Render:border(width)
 
     local foreground, background = self.data.foreground, colors.inverse_bg(self.data.background)
     local prefix = self.heading.border_prefix and self.data.level or 0
+    local virtual = self.heading.border_virtual
 
     ---@param icon string
     ---@return { [1]: string, [2]: string }[]
@@ -198,7 +215,7 @@ function Render:border(width)
     end
 
     local line_above = line(self.heading.above)
-    if str.width(self.info:line('above', 1)) == 0 and self.info.start_row - 1 ~= self.context.last_heading then
+    if not virtual and self:empty_line('above') and self.info.start_row - 1 ~= self.context.last_heading then
         self.marks:add(true, self.info.start_row - 1, 0, {
             virt_text = line_above,
             virt_text_pos = 'overlay',
@@ -211,7 +228,7 @@ function Render:border(width)
     end
 
     local line_below = line(self.heading.below)
-    if str.width(self.info:line('below', 1)) == 0 then
+    if not virtual and self:empty_line('below') then
         self.marks:add(true, self.info.end_row + 1, 0, {
             virt_text = line_below,
             virt_text_pos = 'overlay',
@@ -224,6 +241,13 @@ function Render:border(width)
     end
 end
 
+---@private
+---@param position 'above'|'below'
+---@return boolean
+function Render:empty_line(position)
+    return str.width(self.info:line(position, 1)) == 0
+end
+
 ---@private
 ---@param width render.md.width.Heading
 function Render:left_pad(width)

lua/render-markdown/state.lua

@@ -137,10 +137,10 @@ function M.validate()
 
         validator
             :spec(path, config, 'heading', nilable)
-            :type({ 'enabled', 'sign', 'border', 'border_prefix' }, 'boolean')
-            :type({ 'left_margin', 'left_pad', 'right_pad', 'min_width' }, 'number')
+            :type({ 'enabled', 'sign', 'border', 'border_virtual', 'border_prefix' }, 'boolean')
             :type({ 'above', 'below' }, 'string')
-            :string_array({ 'icons', 'signs', 'backgrounds', 'foregrounds' })
+            :array({ 'left_margin', 'left_pad', 'right_pad', 'min_width' }, 'number', 'number')
+            :array({ 'icons', 'signs', 'backgrounds', 'foregrounds' }, 'string')
             :one_of('position', { 'overlay', 'inline' })
             :one_or_array_of('width', { 'full', 'block' })
             :check()
@@ -150,7 +150,7 @@ function M.validate()
             :type({ 'enabled', 'sign' }, 'boolean')
             :type({ 'language_pad', 'left_margin', 'left_pad', 'right_pad', 'min_width' }, 'number')
             :type({ 'above', 'below', 'highlight', 'highlight_inline' }, 'string')
-            :string_array('disable_background')
+            :array('disable_background', 'string')
             :one_of('style', { 'full', 'normal', 'language', 'none' })
             :one_of('position', { 'left', 'right' })
             :one_of('width', { 'full', 'block' })
@@ -169,7 +169,7 @@ function M.validate()
             :type('enabled', 'boolean')
             :type({ 'left_pad', 'right_pad' }, 'number')
             :type('highlight', 'string')
-            :string_array('icons')
+            :array('icons', 'string')
             :check()
 
         validator
@@ -198,7 +198,7 @@ function M.validate()
             :type('enabled', 'boolean')
             :type('min_width', 'number')
             :type({ 'alignment_indicator', 'head', 'row', 'filler' }, 'string')
-            :string_array('border')
+            :array('border', 'string')
             :one_of('preset', { 'none', 'round', 'double', 'heavy' })
             :one_of('style', { 'full', 'normal', 'none' })
             :one_of('cell', { 'trimmed', 'padded', 'raw', 'overlay' })
@@ -238,10 +238,10 @@ function M.validate()
         :type({ 'max_file_size', 'debounce' }, 'number')
         :type({ 'anti_conceal', 'padding', 'heading', 'code', 'dash', 'bullet', 'checkbox' }, 'table')
         :type({ 'quote', 'pipe_table', 'callout', 'link', 'sign', 'indent', 'win_options' }, 'table')
-        :string_array('render_modes', 'boolean')
+        :array('render_modes', 'string', 'boolean')
         :type({ 'markdown_query', 'markdown_quote_query', 'inline_query' }, 'string')
         :type({ 'injections', 'latex', 'overrides', 'custom_handlers' }, 'table')
-        :string_array('file_types')
+        :array('file_types', 'string')
         :one_of('preset', { 'none', 'lazy', 'obsidian' })
         :one_of('log_level', { 'debug', 'info', 'error' })
         :check()
@@ -267,7 +267,7 @@ function M.validate()
                 :type({ 'max_file_size', 'debounce' }, 'number')
                 :type({ 'anti_conceal', 'padding', 'heading', 'code', 'dash', 'bullet', 'checkbox' }, 'table')
                 :type({ 'quote', 'pipe_table', 'callout', 'link', 'sign', 'indent', 'win_options' }, 'table')
-                :string_array('render_modes', 'boolean')
+                :array('render_modes', 'string', 'boolean')
                 :check()
             validate_buffer_config(spec:get_suffix(), spec:get_input(), true)
         end, true)

lua/render-markdown/types.lua

@@ -110,11 +110,12 @@
 ---@field public icons string[]
 ---@field public signs string[]
 ---@field public width render.md.heading.Width|(render.md.heading.Width)[]
----@field public left_margin number
----@field public left_pad number
----@field public right_pad number
----@field public min_width integer
+---@field public left_margin number|number[]
+---@field public left_pad number|number[]
+---@field public right_pad number|number[]
+---@field public min_width integer|integer[]
 ---@field public border boolean
+---@field public border_virtual boolean
 ---@field public border_prefix boolean
 ---@field public above string
 ---@field public below string