feat: add text option to html comment concealing

## Details

Request: #244

Previously support was added for html comment concealing gated by the
`html.conceal_comments` option. A request to add some kind of icon next
to the now concealed text was made so I'm breaking this configuration,
should be very minimal impact and having an older version won't fail.

Now we have an `html.comment` configuration which stores a `conceal`
boolean and functions like the previous option. Additionally an optional
`text` field is added along with a `highlight` to use for this text.

By default the `text` field is made nil, so we don't do anything more
by default than before. If a user specifies some string we inline this
at the start of the now concealed comment with the `highlight` specified
or the default which naturally links to `@comment`. Since this is inline
text and not a conceal character users are free to make it arbitrarily
long or use a single icon, all should work without a problem.

Refactored HTML handler to match markdown & markdown_inline approach.

Author: MeanderingProgrammer

README.md

@@ -204,12 +204,6 @@ require('render-markdown').setup({
         -- Amount of empty lines below LaTeX blocks
         bottom_pad = 0,
     },
-    html = {
-        -- Turn on / off all HTML rendering
-        enabled = true,
-        -- Whether HTML comments should be concealed or not
-        conceal_comments = true,
-    },
     on = {
         -- Called when plugin initially attaches to a buffer
         attach = function() end,
@@ -580,6 +574,18 @@ require('render-markdown').setup({
         -- Do not indent heading titles, only the body
         skip_heading = false,
     },
+    html = {
+        -- Turn on / off all HTML rendering
+        enabled = true,
+        comment = {
+            -- Turn on / off HTML comment concealing
+            conceal = true,
+            -- Optional text to inline before the concealed comment
+            text = nil,
+            -- Highlight for the inlined text
+            highlight = 'RenderMarkdownHtmlComment',
+        },
+    },
     -- Window options to use that change between rendered and raw view
     win_options = {
         -- See :h 'conceallevel'
@@ -602,7 +608,7 @@ require('render-markdown').setup({
     -- if no override is provided. Supports the following fields:
     --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding,
     --   heading, paragraph, code, dash, bullet, checkbox, quote, pipe_table,
-    --   callout, link, sign, indent, win_options
+    --   callout, link, sign, indent, html, win_options
     overrides = {
         -- Overrides for different buftypes, see :h 'buftype'
         buftype = {
@@ -1193,6 +1199,7 @@ The table below shows all the highlight groups with their default link
 | RenderMarkdownDash            | LineNr                             | Thematic break line        |
 | RenderMarkdownSign            | SignColumn                         | Sign column background     |
 | RenderMarkdownMath            | @markup.math                       | LaTeX lines                |
+| RenderMarkdownHtmlComment     | @comment                           | HTML comment inline text   |
 | RenderMarkdownLink            | @markup.link.label.markdown_inline | Image & hyperlink icons    |
 | RenderMarkdownWikiLink        | RenderMarkdownLink                 | WikiLink icon & text       |
 | RenderMarkdownUnchecked       | @markup.list.unchecked             | Unchecked checkbox         |

doc/render-markdown.txt

@@ -251,12 +251,6 @@ Default Configuration ~
             -- Amount of empty lines below LaTeX blocks
             bottom_pad = 0,
         },
-        html = {
-            -- Turn on / off all HTML rendering
-            enabled = true,
-            -- Whether HTML comments should be concealed or not
-            conceal_comments = true,
-        },
         on = {
             -- Called when plugin initially attaches to a buffer
             attach = function() end,
@@ -627,6 +621,18 @@ Default Configuration ~
             -- Do not indent heading titles, only the body
             skip_heading = false,
         },
+        html = {
+            -- Turn on / off all HTML rendering
+            enabled = true,
+            comment = {
+                -- Turn on / off HTML comment concealing
+                conceal = true,
+                -- Optional text to inline before the concealed comment
+                text = nil,
+                -- Highlight for the inlined text
+                highlight = 'RenderMarkdownHtmlComment',
+            },
+        },
         -- Window options to use that change between rendered and raw view
         win_options = {
             -- See :h 'conceallevel'
@@ -649,7 +655,7 @@ Default Configuration ~
         -- if no override is provided. Supports the following fields:
         --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding,
         --   heading, paragraph, code, dash, bullet, checkbox, quote, pipe_table,
-        --   callout, link, sign, indent, win_options
+        --   callout, link, sign, indent, html, win_options
         overrides = {
             -- Overrides for different buftypes, see :h 'buftype'
             buftype = {
@@ -1242,6 +1248,9 @@ The table below shows all the highlight groups with their default link
 
   RenderMarkdownMath              @markup.math                         LaTeX lines
 
+  RenderMarkdownHtmlComment       @comment                             HTML comment inline
+                                                                       text
+
   RenderMarkdownLink              @markup.link.label.markdown_inline   Image & hyperlink
                                                                        icons
 

lua/render-markdown/colors.lua

@@ -38,6 +38,7 @@ M.colors = {
     Dash            = 'LineNr',
     Sign            = 'SignColumn',
     Math            = '@markup.math',
+    HtmlComment     = '@comment',
     -- Links
     Link            = '@markup.link.label.markdown_inline',
     WikiLink        = 'RenderMarkdownLink',

lua/render-markdown/handler/html.lua

@@ -4,35 +4,42 @@ local state = require('render-markdown.state')
 local treesitter = require('render-markdown.core.treesitter')
 
 ---@class render.md.handler.buf.Html
----@field private config render.md.Html
+---@field private config render.md.buffer.Config
 ---@field private context render.md.Context
 ---@field private marks render.md.Marks
 ---@field private query vim.treesitter.Query
+---@field private renderers table<string, render.md.Renderer>
 local Handler = {}
 Handler.__index = Handler
 
 ---@param buf integer
 ---@return render.md.handler.buf.Html
 function Handler.new(buf)
     local self = setmetatable({}, Handler)
-    self.config = state.html
+    self.config = state.get(buf)
     self.context = Context.get(buf)
     self.marks = List.new_marks(buf, true)
     self.query = treesitter.parse('html', '(comment) @comment')
+    self.renderers = {
+        comment = require('render-markdown.render.html_comment'),
+    }
     return self
 end
 
 ---@param root TSNode
 ---@return render.md.Mark[]
 function Handler:parse(root)
-    if self.config.enabled and self.config.conceal_comments then
-        self.context:query(root, self.query, function(capture, node)
-            assert(capture == 'comment', 'Unhandled html capture: ' .. capture)
-            self.marks:add_over(true, node, {
-                conceal = '',
-            })
-        end)
+    if not self.config.html.enabled then
+        return {}
     end
+    self.context:query(root, self.query, function(capture, node)
+        local renderer = self.renderers[capture]
+        assert(renderer ~= nil, 'Unhandled html capture: ' .. capture)
+        local render = renderer:new(self.marks, self.config, self.context, node)
+        if render:setup() then
+            render:render()
+        end
+    end)
     return self.marks:get()
 end
 

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -14,10 +14,6 @@ local M = {}
 ---@class (exact) render.md.UserCallback
 ---@field public attach? fun(buf: integer)
 
----@class (exact) render.md.UserHtml
----@field public enabled? boolean
----@field public conceal_comments? boolean
-
 ---@class (exact) render.md.UserLatex
 ---@field public enabled? boolean
 ---@field public converter? string
@@ -35,6 +31,15 @@ local M = {}
 ---@field public default? render.md.option.Value
 ---@field public rendered? render.md.option.Value
 
+---@class (exact) render.md.UserHtmlComment
+---@field public conceal? boolean
+---@field public text? string
+---@field public highlight? string
+
+---@class (exact) render.md.UserHtml
+---@field public enabled? boolean
+---@field public comment? render.md.UserHtmlComment
+
 ---@class (exact) render.md.UserIndent
 ---@field public enabled? boolean
 ---@field public per_level? integer
@@ -240,6 +245,7 @@ local M = {}
 ---@field public sign? render.md.UserSign
 ---@field public inline_highlight? render.md.UserInlineHighlight
 ---@field public indent? render.md.UserIndent
+---@field public html? render.md.UserHtml
 ---@field public win_options? table<string, render.md.UserWindowOption>
 
 ---@alias render.md.config.Preset 'none'|'lazy'|'obsidian'
@@ -252,7 +258,6 @@ local M = {}
 ---@field public file_types? string[]
 ---@field public injections? table<string, render.md.UserInjection>
 ---@field public latex? render.md.UserLatex
----@field public html? render.md.UserHtml
 ---@field public on? render.md.UserCallback
 ---@field public overrides? render.md.UserConfigOverrides
 ---@field public custom_handlers? table<string, render.md.Handler>
@@ -331,12 +336,6 @@ M.default_config = {
         -- Amount of empty lines below LaTeX blocks
         bottom_pad = 0,
     },
-    html = {
-        -- Turn on / off all HTML rendering
-        enabled = true,
-        -- Whether HTML comments should be concealed or not
-        conceal_comments = true,
-    },
     on = {
         -- Called when plugin initially attaches to a buffer
         attach = function() end,
@@ -707,6 +706,18 @@ M.default_config = {
         -- Do not indent heading titles, only the body
         skip_heading = false,
     },
+    html = {
+        -- Turn on / off all HTML rendering
+        enabled = true,
+        comment = {
+            -- Turn on / off HTML comment concealing
+            conceal = true,
+            -- Optional text to inline before the concealed comment
+            text = nil,
+            -- Highlight for the inlined text
+            highlight = 'RenderMarkdownHtmlComment',
+        },
+    },
     -- Window options to use that change between rendered and raw view
     win_options = {
         -- See :h 'conceallevel'
@@ -729,7 +740,7 @@ M.default_config = {
     -- if no override is provided. Supports the following fields:
     --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding,
     --   heading, paragraph, code, dash, bullet, checkbox, quote, pipe_table,
-    --   callout, link, sign, indent, win_options
+    --   callout, link, sign, indent, html, win_options
     overrides = {
         -- Overrides for different buftypes, see :h 'buftype'
         buftype = {

lua/render-markdown/render/html_comment.lua

@@ -0,0 +1,29 @@
+local Base = require('render-markdown.render.base')
+
+---@class render.md.render.HtmlComment: render.md.Renderer
+---@field private comment render.md.HtmlComment
+local Render = setmetatable({}, Base)
+Render.__index = Render
+
+---@return boolean
+function Render:setup()
+    self.comment = self.config.html.comment
+    if not self.comment.conceal then
+        return false
+    end
+    return true
+end
+
+function Render:render()
+    self.marks:add_over(true, self.node, {
+        conceal = '',
+    })
+    if self.comment.text ~= nil then
+        self.marks:add_over(true, self.node, {
+            virt_text = { { self.comment.text, self.comment.highlight } },
+            virt_text_pos = 'inline',
+        })
+    end
+end
+
+return Render

lua/render-markdown/state.lua

@@ -13,7 +13,6 @@ local configs = {}
 ---@field log_runtime boolean
 ---@field file_types string[]
 ---@field latex render.md.Latex
----@field html render.md.Html
 ---@field on render.md.Callback
 ---@field custom_handlers table<string, render.md.Handler>
 local M = {}
@@ -46,7 +45,6 @@ function M.setup(default_config, user_config)
     M.log_runtime = config.log_runtime
     M.file_types = config.file_types
     M.latex = config.latex
-    M.html = config.html
     M.on = config.on
     M.custom_handlers = config.custom_handlers
     log.setup(config.log_level)
@@ -121,6 +119,7 @@ function M.default_buffer_config()
         sign = config.sign,
         inline_highlight = config.inline_highlight,
         indent = config.indent,
+        html = config.html,
         win_options = config.win_options,
     }
     return vim.deepcopy(buffer_config)
@@ -266,6 +265,17 @@ function M.validate()
                     :type({ 'per_level', 'skip_level' }, 'number')
                     :check()
             end)
+            :nested('html', function(html)
+                html:type('enabled', 'boolean')
+                    :nested('comment', function(comment)
+                        comment
+                            :type('conceal', 'boolean')
+                            :type('highlight', 'string')
+                            :type('text', { 'string', 'nil' })
+                            :check()
+                    end)
+                    :check()
+            end)
             :nested('win_options', function(win_options)
                 win_options
                     :nested('ALL', function(win_option)
@@ -296,9 +306,6 @@ function M.validate()
                 :type({ 'converter', 'highlight' }, 'string')
                 :check()
         end)
-        :nested('html', function(html)
-            html:type({ 'enabled', 'conceal_comments' }, 'boolean'):check()
-        end)
         :nested('on', function(on)
             on:type('attach', 'function'):check()
         end)

lua/render-markdown/types.lua

@@ -3,10 +3,6 @@
 ---@class (exact) render.md.Callback
 ---@field public attach fun(buf: integer)
 
----@class (exact) render.md.Html
----@field public enabled boolean
----@field public conceal_comments boolean
-
 ---@class (exact) render.md.Latex
 ---@field public enabled boolean
 ---@field public converter string
@@ -22,6 +18,15 @@
 ---@field public default render.md.option.Value
 ---@field public rendered render.md.option.Value
 
+---@class (exact) render.md.HtmlComment
+---@field public conceal boolean
+---@field public text? string
+---@field public highlight string
+
+---@class (exact) render.md.Html
+---@field public enabled boolean
+---@field public comment render.md.HtmlComment
+
 ---@class (exact) render.md.Indent
 ---@field public enabled boolean
 ---@field public per_level integer
@@ -194,6 +199,7 @@
 ---@field public sign render.md.Sign
 ---@field public inline_highlight render.md.InlineHighlight
 ---@field public indent render.md.Indent
+---@field public html render.md.Html
 ---@field public win_options table<string, render.md.WindowOption>
 
 ---@class (exact) render.md.Config: render.md.BufferConfig
@@ -203,7 +209,6 @@
 ---@field public file_types string[]
 ---@field public injections table<string, render.md.Injection>
 ---@field public latex render.md.Latex
----@field public html render.md.Html
 ---@field public on render.md.Callback
 ---@field public overrides render.md.ConfigOverrides
 ---@field public custom_handlers table<string, render.md.Handler>

scripts/update.py

@@ -31,6 +31,7 @@ def is_optional(self, field: str) -> bool:
             "UserCheckboxComponent": ["scope_highlight"],
             "UserCustomCallout": ["quote_icon"],
             "UserLinkComponent": ["highlight"],
+            "UserHtmlComment": ["text"],
         }
 
         # ---@field public extends? boolean             -> extends