Add support for custom callouts

MeanderingProgrammer · MeanderingProgrammer · commit 8f5bbbd9e295 · 2024-07-06T06:27:34.000-07:00
# Details

After adding custom checkboxes, given how similar the implementations
are decided to add custom callouts as well.

Uses the same setup / interfaces as checkboxes.

Configuration parameter callout -&gt; custom.
diff --git a/README.md b/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)
+    - Base set as well as custom ones
   - 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
@@ -186,6 +187,9 @@ require('render-markdown').setup({
         important = '󰅾 Important',
         warning = '󰀪 Warning',
         caution = '󰳦 Caution',
+        custom = {
+            bug = { raw = '[!BUG]', rendered = '󰨰 Bug', highlight = 'DiagnosticError' },
+        },
     },
     -- Window options to use that change between rendered and raw view
     win_options = {
@@ -310,8 +314,8 @@ 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 = { raw = '[-]', rendered = '󰥔 ', highlight = '@markup.raw' }`.
+Additionally `custom` states can be specified, an example of this is provided with:
+`todo = { raw = '[-]', rendered = '󰥔 ', highlight = '@markup.raw' }`.
 
 This requires neovim >= `0.10.0` since it relies on `inline` extmarks.
 
@@ -332,6 +336,15 @@ This is a special instance of a `block_quote`.
 When the `callout` syntax is used the start, i.e. `[!NOTE]`, is replaced
 with this text.
 
+Additionally `custom` callouts can be specified, an example of this is provided with:
+`bug = { raw = '[!BUG]', rendered = '󰨰 Bug', highlight = 'DiagnosticError' }`.
+
+The key in the `custom` table is unused. The parts of the value are:
+
+- `raw`: matched against the raw text of a `shortcut_link`
+- `rendered`: replaces the `raw` value when rendering
+- `highlight`: color used for `rendered` text
+
 ## Highlight
 
 Options are all contained in the `highlights` table.
diff --git a/demo/callout.gif b/demo/callout.gif
diff --git a/demo/callout.md b/demo/callout.md
@@ -28,3 +28,8 @@
 
 > [!CAUTION]
 > Cautionary tale
+
+# Bug
+
+> [!BUG]
+> Custom bug
diff --git a/doc/render-markdown.txt b/doc/render-markdown.txt
@@ -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>
+        - Base set as well as custom ones
     - 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
@@ -218,6 +219,9 @@ Full Default Configuration ~
             important = '󰅾 Important',
             warning = '󰀪 Warning',
             caution = '󰳦 Caution',
+            custom = {
+                bug = { raw = '[!BUG]', rendered = '󰨰 Bug', highlight = 'DiagnosticError' },
+            },
         },
         -- Window options to use that change between rendered and raw view
         win_options = {
@@ -371,6 +375,16 @@ This is a special instance of a `block_quote`.
 When the `callout` syntax is used the start, i.e.� `[!NOTE]`, is replaced with
 this text.
 
+Additionally `custom` callouts can be specified, an example of this is provided
+with: `bug = { raw = '[!BUG]', rendered = '󰨰 Bug', highlight =
+'DiagnosticError' }`.
+
+The key in the `custom` table is unused. The parts of the value are:
+
+- `raw`: matched against the raw text of a `shortcut_link`
+- `rendered`: replaces the `raw` value when rendering
+- `highlight`: color used for `rendered` text
+
 
 HIGHLIGHT                                    *render-markdown-setup-highlight*
 
diff --git a/justfile b/justfile
@@ -22,7 +22,7 @@ demo-latex:
   just demo "latex" "15" ""
 
 demo-callout:
-  just demo "callout" "35" ""
+  just demo "callout" "40" ""
 
 demo file rows content:
   rm -f demo/{{file}}.gif
diff --git a/lua/render-markdown/callout.lua b/lua/render-markdown/callout.lua
diff --git a/lua/render-markdown/component.lua b/lua/render-markdown/component.lua
@@ -0,0 +1,76 @@
+local state = require('render-markdown.state')
+
+---@class render.md.Component
+---@field text string
+---@field highlight string
+
+---@class render.md.CalloutInfo
+---@field text string
+---@field key string
+
+---@type render.md.CalloutInfo[]
+local callouts = {
+    { text = '[!NOTE]', key = 'note' },
+    { text = '[!TIP]', key = 'tip' },
+    { text = '[!IMPORTANT]', key = 'important' },
+    { text = '[!WARNING]', key = 'warning' },
+    { text = '[!CAUTION]', key = 'caution' },
+}
+
+local M = {}
+
+---@param value string
+---@param comparison 'exact'|'contains'
+---@return render.md.Component?
+M.callout = function(value, comparison)
+    ---@param text string
+    ---@return boolean
+    local function matches(text)
+        if comparison == 'exact' then
+            return value == text
+        elseif comparison == 'contains' then
+            return value:find(text, 1, true) ~= nil
+        else
+            error(string.format('Unhandled comparison: %s', comparison))
+        end
+    end
+    for _, callout in ipairs(callouts) do
+        if matches(callout.text) then
+            return {
+                text = state.config.callout[callout.key],
+                highlight = state.config.highlights.callout[callout.key],
+            }
+        end
+    end
+    for _, callout in pairs(state.config.callout.custom) do
+        if matches(callout.raw) then
+            return { text = callout.rendered, highlight = callout.highlight }
+        end
+    end
+    return nil
+end
+
+---@param value string
+---@param comparison 'exact'|'starts'
+---@return render.md.Component?
+M.checkbox = function(value, comparison)
+    ---@param text string
+    ---@return boolean
+    local function matches(text)
+        if comparison == 'exact' then
+            return value == text
+        elseif comparison == 'starts' then
+            return vim.startswith(value, text)
+        else
+            error(string.format('Unhandled comparison: %s', comparison))
+        end
+    end
+    for _, checkbox in pairs(state.config.checkbox.custom) do
+        if matches(checkbox.raw) then
+            return { text = checkbox.rendered, highlight = checkbox.highlight }
+        end
+    end
+    return nil
+end
+
+return M
diff --git a/lua/render-markdown/custom_checkbox.lua b/lua/render-markdown/custom_checkbox.lua
diff --git a/lua/render-markdown/handler/markdown.lua b/lua/render-markdown/handler/markdown.lua
@@ -1,5 +1,4 @@
-local callout = require('render-markdown.callout')
-local custom_checkbox = require('render-markdown.custom_checkbox')
+local component = require('render-markdown.component')
 local icons = require('render-markdown.icons')
 local list = require('render-markdown.list')
 local logger = require('render-markdown.logger')
@@ -120,9 +119,9 @@ 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 key = callout.get_key_contains(vim.treesitter.get_node_text(quote, buf))
-            if key ~= nil then
-                highlight = highlights.callout[key]
+            local callout = component.callout(vim.treesitter.get_node_text(quote, buf), 'contains')
+            if callout ~= nil then
+                highlight = callout.highlight
             end
         end
 
@@ -260,7 +259,7 @@ M.sibling_checkbox = function(buf, node)
     if paragraph == nil then
         return false
     end
-    if custom_checkbox.get_starts(vim.treesitter.get_node_text(paragraph, buf)) ~= nil then
+    if component.checkbox(vim.treesitter.get_node_text(paragraph, buf), 'starts') ~= nil then
         return true
     end
     return false
diff --git a/lua/render-markdown/handler/markdown_inline.lua b/lua/render-markdown/handler/markdown_inline.lua
@@ -1,5 +1,4 @@
-local callout = require('render-markdown.callout')
-local custom_checkbox = require('render-markdown.custom_checkbox')
+local component = require('render-markdown.component')
 local logger = require('render-markdown.logger')
 local state = require('render-markdown.state')
 local str = require('render-markdown.str')
@@ -34,9 +33,9 @@ M.render_node = function(namespace, buf, capture, node)
             hl_group = highlights.code,
         })
     elseif capture == 'callout' then
-        local key = callout.get_key_exact(value)
-        if key ~= nil then
-            local callout_text = { state.config.callout[key], highlights.callout[key] }
+        local callout = component.callout(value, 'exact')
+        if callout ~= nil then
+            local callout_text = { callout.text, callout.highlight }
             vim.api.nvim_buf_set_extmark(buf, namespace, start_row, start_col, {
                 end_row = end_row,
                 end_col = end_col,
@@ -49,12 +48,12 @@ M.render_node = function(namespace, buf, capture, node)
                 return
             end
 
-            local checkbox = custom_checkbox.get_exact(value)
+            local checkbox = component.checkbox(value, 'exact')
             if checkbox == nil then
                 return
             end
 
-            local checkbox_text = { str.pad_to(value, checkbox.rendered), checkbox.highlight }
+            local checkbox_text = { str.pad_to(value, checkbox.text), checkbox.highlight }
             vim.api.nvim_buf_set_extmark(buf, namespace, start_row, start_col, {
                 end_row = end_row,
                 end_col = end_col,
diff --git a/lua/render-markdown/init.lua b/lua/render-markdown/init.lua
@@ -3,7 +3,7 @@ local state = require('render-markdown.state')
 
 local M = {}
 
----@class render.md.UserCallout
+---@class render.md.UserCalloutHighlights
 ---@field public note? string
 ---@field public tip? string
 ---@field public important? string
@@ -31,7 +31,7 @@ local M = {}
 ---@field public table? render.md.UserTableHighlights
 ---@field public latex? string
 ---@field public quote? string
----@field public callout? render.md.UserCallout
+---@field public callout? render.md.UserCalloutHighlights
 
 ---@class render.md.Handler
 ---@field public render fun(namespace: integer, root: TSNode, buf: integer)
@@ -41,15 +41,23 @@ local M = {}
 ---@field public default any
 ---@field public rendered any
 
----@class render.md.CustomCheckbox
+---@class render.md.CustomComponent
 ---@field public raw string
 ---@field public rendered string
 ---@field public highlight string
 
+---@class render.md.UserCallout
+---@field public note? string
+---@field public tip? string
+---@field public important? string
+---@field public warning? string
+---@field public caution? string
+---@field public custom? table<string, render.md.CustomComponent>
+
 ---@class render.md.UserCheckbox
 ---@field public unchecked? string
 ---@field public checked? string
----@field public custom? table<string, render.md.CustomCheckbox>
+---@field public custom? table<string, render.md.CustomComponent>
 
 ---@class render.md.UserConfig
 ---@field public start_enabled? boolean
@@ -164,6 +172,9 @@ M.default_config = {
         important = '󰅾 Important',
         warning = '󰀪 Warning',
         caution = '󰳦 Caution',
+        custom = {
+            bug = { raw = '[!BUG]', rendered = '󰨰 Bug', highlight = 'DiagnosticError' },
+        },
     },
     -- Window options to use that change between rendered and raw view
     win_options = {
diff --git a/lua/render-markdown/types.lua b/lua/render-markdown/types.lua
@@ -1,4 +1,4 @@
----@class render.md.Callout
+---@class render.md.CalloutHighlights
 ---@field public note string
 ---@field public tip string
 ---@field public important string
@@ -26,12 +26,20 @@
 ---@field public table render.md.TableHighlights
 ---@field public latex string
 ---@field public quote string
----@field public callout render.md.Callout
+---@field public callout render.md.CalloutHighlights
+
+---@class render.md.Callout
+---@field public note string
+---@field public tip string
+---@field public important string
+---@field public warning string
+---@field public caution string
+---@field public custom table<string, render.md.CustomComponent>
 
 ---@class render.md.Checkbox
 ---@field public unchecked string
 ---@field public checked string
----@field public custom table<string, render.md.CustomCheckbox>
+---@field public custom table<string, render.md.CustomComponent>
 
 ---@class render.md.Config
 ---@field public start_enabled boolean
diff --git a/tests/callout_spec.lua b/tests/callout_spec.lua
