feat: position property for checkboxes

# Details

Submitted as a bug: #140

When checkboxes are rendered they are padded with spaces to fill the
width of the underlying text. This is because most icons have a width of
2, while the text forming the checkbox (like [x]) has a width of 3. If
spaces were not added using overlay virtual text would result in one of
the square brackets poking through depending on the side of the padding.

We can use inline virtual text which was added in neovim 0.10.0 to fully
hide the underlying text and insert the virtual text, shifting text as
needed, however on its own this would remove the feature for users of
older versions of neovim.

To get around this I have added a position property to the checkbox
config which defaults to the new value of 'inline' which results in
nicer alignment of checkboxes. The value 'overlay' is available and will
result in identical behavior to before this change if users prefer it.

Additionally when initializing the config we check the neovim version
and change configuration values that are known to not work with older
versions to availble alternatives. Currently this is done for:

- checkbox position -> 'overlay' so as not to remove the feature and
  require users to manually modify their config if they run neovim <
  0.10.0
- code position -> 'right' since left alignment requires shifting text
  while right does not, adding a feature to users if they did not dive
  too deep into the options available for this plugin

Overall this updates behavior for anyone that can use it and keeps the
old behavior around either out of necessity (version) or personal
preference.

Author: MeanderingProgrammer

CHANGELOG.md

@@ -14,6 +14,7 @@
 - wiki links nested in tables [72688ba](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/72688baea4ef0ed605033bf654b54d801b6a5f01)
 - code block background when indented in lists [#133](https://github.com/MeanderingProgrammer/render-markdown.nvim/issues/133)
   [4c823b1](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/4c823b1df151dbf1ed3ddaacac517be606b1e145)
+  [d1cec33](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/d1cec33f0d59bac5c2854312d2ea0483b44dfd11)
 - do not set noref in vim.deepcopy [#139](https://github.com/MeanderingProgrammer/render-markdown.nvim/pull/139)
 - gate virt_text_repeat_linebreak to neovim >= 0.10.0 [98f9965](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/98f996563591b753470942165d2d5134df868529)
 - account for folds when computing visible range [#138](https://github.com/MeanderingProgrammer/render-markdown.nvim/issues/138)

README.md

@@ -18,20 +18,13 @@ Plugin to improve viewing Markdown files in Neovim
 >     plugins = { markdown = true },
 > })
 > ```
->
-> For `rocks.nvim` users migrate to the new [LuaRock](https://luarocks.org/modules/MeanderingProgrammer/render-markdown.nvim).
->
-> ```vim
-> :Rocks prune markdown.nvim
-> :Rocks install render-markdown.nvim
-> ```
 
 <!-- panvimdoc-ignore-start -->
 
 |           |         |
 | --------- | ------- |
 | ![Heading](https://github.com/user-attachments/assets/663a34c5-0438-4688-8204-332065f65835) | ![Table](https://github.com/user-attachments/assets/162986e1-91f0-4e13-a83f-6183d58b0fcb) |
-| ![Quote](https://github.com/user-attachments/assets/3f76e73e-b3a0-4cd8-90c1-208c5070659c)   | ![LaTeX](https://github.com/user-attachments/assets/9e8909e4-7256-45fc-b481-4aba8850ebc3) |
+| ![Quote](https://github.com/user-attachments/assets/5343ca45-d5e1-4de0-9065-46499e1ed919)   | ![LaTeX](https://github.com/user-attachments/assets/9e8909e4-7256-45fc-b481-4aba8850ebc3) |
 | ![Callout](https://github.com/user-attachments/assets/4324ea72-a017-4175-9f9d-363da5e5f6ba) | |
 
 <!-- panvimdoc-ignore-end -->
@@ -41,10 +34,10 @@ Plugin to improve viewing Markdown files in Neovim
 - Functions entirely inside of Neovim with no external windows
 - Changes between `rendered` view in normal mode and `raw` view in all other modes
 - Supports anti-conceal behavior, removing any virtual text added by this plugin
-  on the line the cursor is on, this does have a performance penalty and can be disabled
+  on the line the cursor is on, this can be disabled
 - Changes window options between `rendered` and `raw` view based on configuration
   - Effects `conceallevel` & `concealcursor` by default
-- Supports rendering `markdown` injected into other file types
+- Supports rendering `markdown` injected into any file type
 - Renders the following `markdown` components:
   - Headings: highlight depending on level and replaces `#` with icon
   - Horizontal breaks: replace with full-width lines
@@ -57,8 +50,8 @@ Plugin to improve viewing Markdown files in Neovim
   - Block quotes: replace leading `>` with provided icon
   - Tables: replace border characters, handles misaligned tables but does NOT align
     according to delimiter indicator
-  - [Callouts](https://github.com/orgs/community/discussions/16925)
-    - Github & Obsidian out of the box, supports user defined as well
+  - [Callouts](https://github.com/orgs/community/discussions/16925): Github & Obsidian
+    out of the box, supports user defined as well
   - Custom checkbox states [^1], function similar to `callouts`
   - Adds icon before images / links [^1]
   - `LaTeX` blocks: renders formulas if `latex` parser and `pylatexenc` are installed
@@ -241,7 +234,7 @@ require('render-markdown').setup({
         enabled = true,
         -- Turn on / off any sign column related rendering
         sign = true,
-        -- Determines how the icon fills the available space:
+        -- Determines how icons fill the available space:
         --  inline:  underlying '#'s are concealed resulting in a left aligned icon
         --  overlay: result is left padded with spaces to hide any additional '#'
         position = 'overlay',
@@ -367,6 +360,10 @@ require('render-markdown').setup({
     checkbox = {
         -- Turn on / off checkbox state rendering
         enabled = true,
+        -- Determines how icons fill the available space:
+        --  inline:  underlying text is concealed resulting in a left aligned icon
+        --  overlay: result is left padded with spaces to hide any additional text
+        position = 'inline',
         unchecked = {
             -- Replaces '[ ]' of 'task_list_marker_unchecked'
             icon = '󰄱 ',
@@ -546,7 +543,7 @@ require('render-markdown').setup({
         enabled = true,
         -- Turn on / off any sign column related rendering
         sign = true,
-        -- Determines how the icon fills the available space:
+        -- Determines how icons fill the available space:
         --  inline:  underlying '#'s are concealed resulting in a left aligned icon
         --  overlay: result is left padded with spaces to hide any additional '#'
         position = 'overlay',
@@ -708,6 +705,10 @@ require('render-markdown').setup({
     checkbox = {
         -- Turn on / off checkbox state rendering
         enabled = true,
+        -- Determines how icons fill the available space:
+        --  inline:  underlying text is concealed resulting in a left aligned icon
+        --  overlay: result is left padded with spaces to hide any additional text
+        position = 'inline',
         unchecked = {
             -- Replaces '[ ]' of 'task_list_marker_unchecked'
             icon = '󰄱 ',

benches/readme_spec.lua

@@ -4,7 +4,7 @@ local util = require('benches.util')
 
 describe('README.md', function()
     it('default', function()
-        local base_marks = 50
+        local base_marks = 53
         util.less_than(util.setup('README.md'), 50)
         util.num_marks(base_marks)
 

demo/box_dash_quote.md

@@ -3,6 +3,7 @@
 - [ ] Unchecked Checkbox
 - [x] Checked Checkbox
 - [-] Todo Checkbox
+- Regular List Item
 
 ---
 

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*          For 0.10.0          Last change: 2024 August 19
+*render-markdown.txt*          For 0.10.0          Last change: 2024 August 20
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -47,23 +47,17 @@ Plugin to improve viewing Markdown files in Neovim
           plugins = { markdown = true },
       })
   <
-  For `rocks.nvim` users migrate to the new LuaRock
-  <https://luarocks.org/modules/MeanderingProgrammer/render-markdown.nvim>.
-  >vim
-      :Rocks prune markdown.nvim
-      :Rocks install render-markdown.nvim
-  <
 
 ==============================================================================
 2. Features                                         *render-markdown-features*
 
 - Functions entirely inside of Neovim with no external windows
 - Changes between `rendered` view in normal mode and `raw` view in all other modes
 - Supports anti-conceal behavior, removing any virtual text added by this plugin
-    on the line the cursor is on, this does have a performance penalty and can be disabled
+    on the line the cursor is on, this can be disabled
 - Changes window options between `rendered` and `raw` view based on configuration
     - Effects `conceallevel` & `concealcursor` by default
-- Supports rendering `markdown` injected into other file types
+- Supports rendering `markdown` injected into any file type
 - Renders the following `markdown` components:
     - Headings: highlight depending on level and replaces `#` with icon
     - Horizontal breaks: replace with full-width lines
@@ -76,8 +70,8 @@ Plugin to improve viewing Markdown files in Neovim
     - Block quotes: replace leading `>` with provided icon
     - Tables: replace border characters, handles misaligned tables but does NOT align
         according to delimiter indicator
-    - Callouts <https://github.com/orgs/community/discussions/16925>
-        - Github & Obsidian out of the box, supports user defined as well
+    - Callouts <https://github.com/orgs/community/discussions/16925>: Github & Obsidian
+        out of the box, supports user defined as well
     - Custom checkbox states , function similar to `callouts`
     - Adds icon before images / links 
     - `LaTeX` blocks: renders formulas if `latex` parser and `pylatexenc` are installed
@@ -270,7 +264,7 @@ Full Default Configuration ~
             enabled = true,
             -- Turn on / off any sign column related rendering
             sign = true,
-            -- Determines how the icon fills the available space:
+            -- Determines how icons fill the available space:
             --  inline:  underlying '#'s are concealed resulting in a left aligned icon
             --  overlay: result is left padded with spaces to hide any additional '#'
             position = 'overlay',
@@ -396,6 +390,10 @@ Full Default Configuration ~
         checkbox = {
             -- Turn on / off checkbox state rendering
             enabled = true,
+            -- Determines how icons fill the available space:
+            --  inline:  underlying text is concealed resulting in a left aligned icon
+            --  overlay: result is left padded with spaces to hide any additional text
+            position = 'inline',
             unchecked = {
                 -- Replaces '[ ]' of 'task_list_marker_unchecked'
                 icon = '󰄱 ',
@@ -575,7 +573,7 @@ Wiki Page
             enabled = true,
             -- Turn on / off any sign column related rendering
             sign = true,
-            -- Determines how the icon fills the available space:
+            -- Determines how icons fill the available space:
             --  inline:  underlying '#'s are concealed resulting in a left aligned icon
             --  overlay: result is left padded with spaces to hide any additional '#'
             position = 'overlay',
@@ -745,6 +743,10 @@ Wiki Page
         checkbox = {
             -- Turn on / off checkbox state rendering
             enabled = true,
+            -- Determines how icons fill the available space:
+            --  inline:  underlying text is concealed resulting in a left aligned icon
+            --  overlay: result is left padded with spaces to hide any additional text
+            position = 'inline',
             unchecked = {
                 -- Replaces '[ ]' of 'task_list_marker_unchecked'
                 icon = '󰄱 ',

lua/render-markdown/handler/markdown.lua

@@ -111,7 +111,7 @@ function Handler:heading(info)
         -- Overwrite anything beyond width with Normal
         self:add(true, info.start_row, 0, {
             priority = 0,
-            virt_text = { { str.pad(vim.o.columns * 2), 'Normal' } },
+            virt_text = { { str.spaces(vim.o.columns * 2), 'Normal' } },
             virt_text_win_col = width,
         })
     end
@@ -123,7 +123,7 @@ function Handler:heading(info)
     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 = { { str.spaces(heading.left_pad), background } },
             virt_text_pos = 'inline',
         })
     end
@@ -346,7 +346,7 @@ function Handler:code_background(code_block, icon_added)
         end
     end
 
-    local padding = str.pad(vim.o.columns * 2)
+    local padding = str.spaces(vim.o.columns * 2)
     for row = code_block.start_row, code_block.end_row - 1 do
         self:add(false, row, code_block.col, {
             end_row = row + 1,
@@ -375,8 +375,8 @@ function Handler:code_left_pad(code_block, add_background)
 
     -- Use low priority to include other marks in padding when code block is at edge
     local priority = code_block.col == 0 and 0 or nil
-    local outer_text = { str.pad(code_block.col), 'Normal' }
-    local left_text = { str.pad(code.left_pad), add_background and code.highlight or 'Normal' }
+    local outer_text = { str.spaces(code_block.col), 'Normal' }
+    local left_text = { str.spaces(code.left_pad), add_background and code.highlight or 'Normal' }
 
     for row = code_block.start_row, code_block.end_row - 1 do
         local virt_text = {}
@@ -446,13 +446,13 @@ function Handler:list_marker(info)
         if bullet.left_pad > 0 then
             self:add(false, info.start_row, 0, {
                 priority = 0,
-                virt_text = { { str.pad(bullet.left_pad), 'Normal' } },
+                virt_text = { { str.spaces(bullet.left_pad), 'Normal' } },
                 virt_text_pos = 'inline',
             })
         end
         if bullet.right_pad > 0 then
             self:add(true, info.start_row, info.end_col - 1, {
-                virt_text = { { str.pad(bullet.right_pad), 'Normal' } },
+                virt_text = { { str.spaces(bullet.right_pad), 'Normal' } },
                 virt_text_pos = 'inline',
             })
         end
@@ -461,16 +461,19 @@ end
 
 ---@private
 ---@param info render.md.NodeInfo
----@param checkbox_state render.md.CheckboxComponent
-function Handler:checkbox(info, checkbox_state)
+---@param checkbox render.md.CheckboxComponent
+function Handler:checkbox(info, checkbox)
     if not self.config.checkbox.enabled then
         return
     end
+    local inline = self.config.checkbox.position == 'inline'
+    local icon, highlight = checkbox.icon, checkbox.highlight
     self:add(true, info.start_row, info.start_col, {
         end_row = info.end_row,
         end_col = info.end_col,
-        virt_text = { { str.pad_to(info.text, checkbox_state.icon), checkbox_state.highlight } },
-        virt_text_pos = 'overlay',
+        virt_text = { { inline and icon or str.pad_to(info.text, icon), highlight } },
+        virt_text_pos = inline and 'inline' or 'overlay',
+        conceal = inline and '' or nil,
     })
 end
 
@@ -583,7 +586,7 @@ function Handler:table_row(delim, row)
             local offset = delim.columns[i].width - column.width
             if offset > 0 then
                 self:add(true, column.info.start_row, column.info.end_col - 1, {
-                    virt_text = { { str.pad(offset), pipe_table.filler } },
+                    virt_text = { { str.spaces(offset), pipe_table.filler } },
                     virt_text_pos = 'inline',
                 })
             end

lua/render-markdown/handler/markdown_inline.lua

@@ -128,10 +128,12 @@ function Handler:checkbox(info, checkbox)
     if not self.config.checkbox.enabled then
         return
     end
+    local inline = self.config.checkbox.position == 'inline'
+    local icon, highlight = checkbox.rendered, checkbox.highlight
     self:add(info.start_row, info.start_col, {
         end_row = info.end_row,
         end_col = info.end_col,
-        virt_text = { { str.pad_to(info.text, checkbox.rendered), checkbox.highlight } },
+        virt_text = { { inline and icon or str.pad_to(info.text, icon), highlight } },
         virt_text_pos = 'inline',
         conceal = '',
     })

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -68,8 +68,11 @@ local M = {}
 ---@field public icon? string
 ---@field public highlight? string
 
+---@alias render.md.checkbox.Position 'overlay'|'inline'
+
 ---@class (exact) render.md.UserCheckbox
 ---@field public enabled? boolean
+---@field public position? render.md.checkbox.Position
 ---@field public unchecked? render.md.UserCheckboxComponent
 ---@field public checked? render.md.UserCheckboxComponent
 ---@field public custom? table<string, render.md.CustomComponent>
@@ -264,7 +267,7 @@ M.default_config = {
         enabled = true,
         -- Turn on / off any sign column related rendering
         sign = true,
-        -- Determines how the icon fills the available space:
+        -- Determines how icons fill the available space:
         --  inline:  underlying '#'s are concealed resulting in a left aligned icon
         --  overlay: result is left padded with spaces to hide any additional '#'
         position = 'overlay',
@@ -390,6 +393,10 @@ M.default_config = {
     checkbox = {
         -- Turn on / off checkbox state rendering
         enabled = true,
+        -- Determines how icons fill the available space:
+        --  inline:  underlying text is concealed resulting in a left aligned icon
+        --  overlay: result is left padded with spaces to hide any additional text
+        position = 'inline',
         unchecked = {
             -- Replaces '[ ]' of 'task_list_marker_unchecked'
             icon = '󰄱 ',

lua/render-markdown/state.lua

@@ -26,6 +26,12 @@ end
 ---@param user_config render.md.UserConfig
 function M.setup(default_config, user_config)
     local config = vim.tbl_deep_extend('force', default_config, presets.get(user_config), user_config)
+    -- Override settings that require neovim >= 0.10.0 and have compatible alternatives
+    if not util.has_10 then
+        config.code.position = 'right'
+        config.checkbox.position = 'overlay'
+    end
+
     M.config = config
     M.enabled = config.enabled
     M.log_level = config.log_level
@@ -272,6 +278,7 @@ function M.validate()
         if checkbox ~= nil then
             append_errors(path .. '.checkbox', checkbox, {
                 enabled = { checkbox.enabled, 'boolean', nilable },
+                position = one_of(checkbox.position, { 'overlay', 'inline' }, {}, nilable),
                 unchecked = { checkbox.unchecked, 'table', nilable },
                 checked = { checkbox.checked, 'table', nilable },
                 custom = { checkbox.custom, 'table', nilable },

lua/render-markdown/str.lua

@@ -24,23 +24,25 @@ function M.leading_spaces(s)
     return leading_spaces or 0
 end
 
----@param value string
+---@param n integer
+---@return string
+function M.spaces(n)
+    return string.rep(' ', n)
+end
+
+---@param target string
 ---@param s string
 ---@return string
-function M.pad_to(value, s)
-    local padding = M.width(value) - M.width(s)
-    return M.pad(padding, s)
+function M.pad_to(target, s)
+    local n = M.width(target) - M.width(s)
+    return M.pad(n, s)
 end
 
----@param padding integer
----@param s? string
+---@param n integer
+---@param s string
 ---@return string
-function M.pad(padding, s)
-    local result = string.rep(' ', padding)
-    if s ~= nil then
-        result = result .. s
-    end
-    return result
+function M.pad(n, s)
+    return M.spaces(n) .. s
 end
 
 return M