Add support for custom checkbox states

# Details

Proposed in: #42

Take a similar approach as callouts and use shortcut_links in list items
as custom states of a checkbox.

Configurable through checkbox -> custom.

Each value must provide text, icon, and highlight.

Author: MeanderingProgrammer

README.md

@@ -27,6 +27,7 @@ Plugin to improve viewing Markdown files in Neovim
   - Block quotes: replace leading `>` with provided icon
   - Tables: replace border characters, does NOT automatically align
   - [Callouts](https://github.com/orgs/community/discussions/16925)
+  - Custom checkbox states, function similar to `callouts`
   - `LaTeX` blocks: renders formulas if `latex` parser and `pylatexenc` are installed
 - Disable rendering when file is larger than provided value
 - Support custom handlers which are ran identically to builtin handlers
@@ -171,6 +172,10 @@ require('render-markdown').setup({
         unchecked = '󰄱 ',
         -- Character that will replace the [x] in checked checkboxes
         checked = '󰱒 ',
+        -- Specify custom checkboxes, must be surrounded in square brackets
+        custom = {
+            todo = { text = '[-]', icon = '󰥔 ', highlight = '@markup.raw' },
+        },
     },
     -- Character that will replace the > at the start of block quotes
     quote = '▋',
@@ -305,6 +310,17 @@ is used to hide the character.
 
 The checked `[ ]` & unchecked `[x]` are directly replaced with these values.
 
+Additionally `custom` states can be specified, an example of this is provided
+with: `todo = { text = '[-]', icon = '󰥔 ', highlight = '@markup.raw' }`.
+
+This requires neovim >= `0.10.0` since it relies on `inline` extmarks.
+
+The key in the `custom` table is unused. The parts of the value are:
+
+- `text`: matched against the raw text of a `shortcut_link`, in the same way as `callouts`
+- `icon`: replaces the `text` value when rendering
+- `highlight`: color used for `icon`
+
 ### quote
 
 Replaces the `|` character in front of `block_quotes`.

demo/box_dash_quote.gif

@@ -2,6 +2,7 @@
 
 - [ ] Unchecked Checkbox
 - [x] Checked Checkbox
+- [-] Todo Checkbox
 
 ---
 

demo/box_dash_quote.md

@@ -50,6 +50,7 @@ Plugin to improve viewing Markdown files in Neovim
     - Block quotes: replace leading `>` with provided icon
     - Tables: replace border characters, does NOT automatically align
     - Callouts <https://github.com/orgs/community/discussions/16925>
+    - Custom checkbox states, function similar to `callouts`
     - `LaTeX` blocks: renders formulas if `latex` parser and `pylatexenc` are installed
 - Disable rendering when file is larger than provided value
 - Support custom handlers which are ran identically to builtin handlers
@@ -203,6 +204,10 @@ Full Default Configuration ~
             unchecked = '󰄱 ',
             -- Character that will replace the [x] in checked checkboxes
             checked = '󰱒 ',
+            -- Specify custom checkboxes, must be surrounded in square brackets
+            custom = {
+                todo = { text = '[-]', icon = '󰥔 ', highlight = '@markup.raw' },
+            },
         },
         -- Character that will replace the > at the start of block quotes
         quote = '▋',
@@ -342,6 +347,17 @@ CHECKBOX ~
 
 The checked `[ ]` & unchecked `[x]` are directly replaced with these values.
 
+Additionally `custom` states can be specified, an example of this is provided
+with: `todo = { text = '[-]', icon = '󰥔 ', highlight = '@markup.raw' }`.
+
+This requires neovim >= `0.10.0` since it relies on `inline` extmarks.
+
+The key in the `custom` table is unused. The parts of the value are:
+
+- `text`: matched against the raw text of a `shortcut_link`, in the same way as `callouts`
+- `icon`: replaces the `text` value when rendering
+- `highlight`: color used for `icon`
+
 
 QUOTE ~
 

doc/render-markdown.txt

@@ -0,0 +1,29 @@
+local state = require('render-markdown.state')
+
+local M = {}
+
+---@param value string
+---@return render.md.CustomCheckbox?
+M.get_exact = function(value)
+    for _, checkbox in pairs(state.config.checkbox.custom) do
+        ---@diagnostic disable-next-line: undefined-field
+        if checkbox.text == value then
+            return checkbox
+        end
+    end
+    return nil
+end
+
+---@param value string
+---@return render.md.CustomCheckbox?
+M.get_starts = function(value)
+    for _, checkbox in pairs(state.config.checkbox.custom) do
+        ---@diagnostic disable-next-line: undefined-field
+        if vim.startswith(value, checkbox.text) then
+            return checkbox
+        end
+    end
+    return nil
+end
+
+return M

lua/render-markdown/custom_checkbox.lua

@@ -1,8 +1,10 @@
 local callout = require('render-markdown.callout')
+local custom_checkbox = require('render-markdown.custom_checkbox')
 local icons = require('render-markdown.icons')
 local list = require('render-markdown.list')
 local logger = require('render-markdown.logger')
 local state = require('render-markdown.state')
+local str = require('render-markdown.str')
 local ts = require('render-markdown.ts')
 local util = require('render-markdown.util')
 
@@ -39,7 +41,7 @@ M.render_node = function(namespace, buf, capture, node)
         local background = list.clamp_last(highlights.heading.backgrounds, level)
         local foreground = list.clamp_last(highlights.heading.foregrounds, level)
 
-        local heading_text = { string.rep(' ', padding) .. heading, { foreground, background } }
+        local heading_text = { str.pad(heading, padding), { foreground, background } }
         vim.api.nvim_buf_set_extmark(buf, namespace, start_row, 0, {
             end_row = end_row + 1,
             end_col = 0,
@@ -71,7 +73,7 @@ M.render_node = function(namespace, buf, capture, node)
             return
         end
         -- Requires inline extmarks
-        if vim.fn.has('nvim-0.10') == 0 then
+        if not util.has_10 then
             return
         end
 
@@ -86,7 +88,7 @@ M.render_node = function(namespace, buf, capture, node)
             virt_text_pos = 'inline',
         })
     elseif capture == 'list_marker' then
-        if ts.sibling(node, { 'task_list_marker_unchecked', 'task_list_marker_checked' }) ~= nil then
+        if M.sibling_checkbox(buf, node) then
             -- Hide the list marker for checkboxes rather than replacing with a bullet point
             vim.api.nvim_buf_set_extmark(buf, namespace, start_row, start_col, {
                 end_row = end_row,
@@ -101,7 +103,7 @@ M.render_node = function(namespace, buf, capture, node)
             local level = ts.level_in_section(node, 'list')
             local bullet = list.cycle(state.config.bullets, level)
 
-            local list_marker_text = { string.rep(' ', leading_spaces or 0) .. bullet, highlights.bullet }
+            local list_marker_text = { str.pad(bullet, leading_spaces), highlights.bullet }
             vim.api.nvim_buf_set_extmark(buf, namespace, start_row, start_col, {
                 end_row = end_row,
                 end_col = end_col,
@@ -118,8 +120,7 @@ M.render_node = function(namespace, buf, capture, node)
         local highlight = highlights.quote
         local quote = ts.parent_in_section(node, 'block_quote')
         if quote ~= nil then
-            local quote_value = vim.treesitter.get_node_text(quote, buf)
-            local key = callout.get_key_contains(quote_value)
+            local key = callout.get_key_contains(vim.treesitter.get_node_text(quote, buf))
             if key ~= nil then
                 highlight = highlights.callout[key]
             end
@@ -139,17 +140,14 @@ M.render_node = function(namespace, buf, capture, node)
             checkbox = state.config.checkbox.checked
             highlight = highlights.checkbox.checked
         end
-        local padding = vim.fn.strdisplaywidth(value) - vim.fn.strdisplaywidth(checkbox)
 
-        if padding >= 0 then
-            local checkbox_text = { string.rep(' ', padding) .. checkbox, highlight }
-            vim.api.nvim_buf_set_extmark(buf, namespace, start_row, start_col, {
-                end_row = end_row,
-                end_col = end_col,
-                virt_text = { checkbox_text },
-                virt_text_pos = 'overlay',
-            })
-        end
+        local checkbox_text = { str.pad_to(value, checkbox), highlight }
+        vim.api.nvim_buf_set_extmark(buf, namespace, start_row, start_col, {
+            end_row = end_row,
+            end_col = end_col,
+            virt_text = { checkbox_text },
+            virt_text_pos = 'overlay',
+        })
     elseif capture == 'table' then
         if state.config.table_style ~= 'full' then
             return
@@ -251,4 +249,21 @@ M.render_node = function(namespace, buf, capture, node)
     end
 end
 
+---@param buf integer
+---@param node TSNode
+---@return boolean
+M.sibling_checkbox = function(buf, node)
+    if ts.sibling(node, { 'task_list_marker_unchecked', 'task_list_marker_checked' }) ~= nil then
+        return true
+    end
+    local paragraph = ts.sibling(node, { 'paragraph' })
+    if paragraph == nil then
+        return false
+    end
+    if custom_checkbox.get_starts(vim.treesitter.get_node_text(paragraph, buf)) ~= nil then
+        return true
+    end
+    return false
+end
+
 return M

lua/render-markdown/handler/markdown.lua

@@ -1,6 +1,9 @@
 local callout = require('render-markdown.callout')
+local custom_checkbox = require('render-markdown.custom_checkbox')
 local logger = require('render-markdown.logger')
 local state = require('render-markdown.state')
+local str = require('render-markdown.str')
+local util = require('render-markdown.util')
 
 local M = {}
 
@@ -40,6 +43,25 @@ M.render_node = function(namespace, buf, capture, node)
                 virt_text = { callout_text },
                 virt_text_pos = 'overlay',
             })
+        else
+            -- Requires inline extmarks
+            if not util.has_10 then
+                return
+            end
+
+            local checkbox = custom_checkbox.get_exact(value)
+            if checkbox == nil then
+                return
+            end
+
+            local checkbox_text = { str.pad_to(value, checkbox.icon), checkbox.highlight }
+            vim.api.nvim_buf_set_extmark(buf, namespace, start_row, start_col, {
+                end_row = end_row,
+                end_col = end_col,
+                virt_text = { checkbox_text },
+                virt_text_pos = 'inline',
+                conceal = '',
+            })
         end
     else
         -- Should only get here if user provides custom capture, currently unhandled

lua/render-markdown/handler/markdown_inline.lua

@@ -85,7 +85,7 @@ function M.check_keys(t1, t2, path)
             table.insert(errors, string.format('Invalid type: %s, expected %s, found %s', key, type(v1), type(v2)))
         elseif type(v1) == 'table' and type(v2) == 'table' then
             -- Some tables are meant to have unrestricted keys
-            if not vim.tbl_contains({ 'win_options', 'custom_handlers' }, k) then
+            if not vim.tbl_contains({ 'win_options', 'custom', 'custom_handlers' }, k) then
                 vim.list_extend(errors, M.check_keys(v1, v2, key_path))
             end
         end

lua/render-markdown/health.lua

@@ -41,9 +41,15 @@ local M = {}
 ---@field public default any
 ---@field public rendered any
 
+---@class render.md.CustomCheckbox
+---@field public text string
+---@field public icon string
+---@field public highlight string
+
 ---@class render.md.UserCheckbox
 ---@field public unchecked? string
 ---@field public checked? string
+---@field public custom? table<string, render.md.CustomCheckbox[]>
 
 ---@class render.md.UserConfig
 ---@field public start_enabled? boolean
@@ -144,6 +150,10 @@ M.default_config = {
         unchecked = '󰄱 ',
         -- Character that will replace the [x] in checked checkboxes
         checked = '󰱒 ',
+        -- Specify custom checkboxes, must be surrounded in square brackets
+        custom = {
+            todo = { text = '[-]', icon = '󰥔 ', highlight = '@markup.raw' },
+        },
     },
     -- Character that will replace the > at the start of block quotes
     quote = '▋',

lua/render-markdown/init.lua

@@ -0,0 +1,18 @@
+local M = {}
+
+---@param value string
+---@param s string
+---@return string
+M.pad_to = function(value, s)
+    local padding = vim.fn.strdisplaywidth(value) - vim.fn.strdisplaywidth(s)
+    return M.pad(s, padding)
+end
+
+---@param s string
+---@param padding integer?
+---@return string
+M.pad = function(s, padding)
+    return string.rep(' ', padding or 0) .. s
+end
+
+return M