feat: ability to conceal text based on lua patterns

## Details

Request: #397

Adds new top level `document` configuration. The main part of this new
configuration is a nested `conceal` configuration which contains two
fields, `char_patterns` & `line_patterns`.

These 2 fields will have their values iterated over the top level
`markdown` document node text and any ranges that match the text will be
concealed. The difference in behavior is the kind of mark that gets
added over the range.

- char_patterns: `conceal = ''` characters in the range are hidden but
  lines rest of line if any is still visible.
- line_patterns: `conceal_lines = ''` entire lines are hidden even if
  match is partial, will unfold when user cursor enters the range,
  requires neovim `0.11.0` as that is when horizontal conceal was added.

This plugin does not do anything clever for the ranges and will at no
time support doing anything outside of the bounds of lua patterns. It is
entirely up to the user to make good patterns, i.e. using `-` instead of
`+/*` for non-greedy matches, capturing the start of line or start of
document patterns, and any other specific behavior they want.

Any issues opened about how to make a pattern do something or why does
some pattern match like this will be auto-closed, lua patterns are well
defined and easy to iterate and test with.

Providing some examples below:

- Hiding words surrounded by `:`, i.e. `:conceal-me:`:

```lua
require('render-markdown').setup({
    document = {
        conceal = {
            char_patterns = { ':%S-:%s' },
        },
    },
})
```

- Hiding minus metadata

```lua
require('render-markdown').setup({
    document = {
        conceal = {
            line_patterns = {
                '^%-%-%-\n.-\n%-%-%-\n', -- start
                '\n%-%-%-\n.-\n%-%-%-\n', -- middle
            },
        },
    },
})
```

- Hiding plus metadata

```lua
require('render-markdown').setup({
    document = {
        conceal = {
            line_patterns = {
                '^%+%+%+\n.-\n%+%+%+\n', -- start
                '\n%+%+%+\n.-\n%+%+%+\n', -- middle
            },
        },
    },
})
```

Author: MeanderingProgrammer

README.md

@@ -381,10 +381,10 @@ require('render-markdown').setup({
         -- Define custom heading patterns which allow you to override various properties based on
         -- the contents of a heading.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern    | matched against the heading text @see :h lua-pattern |
-        -- | icon       | optional override for the icon                       |
-        -- | background | optional override for the background                 |
-        -- | foreground | optional override for the foreground                 |
+        -- | pattern    | matched against the heading text @see :h lua-patterns |
+        -- | icon       | optional override for the icon                        |
+        -- | background | optional override for the background                  |
+        -- | foreground | optional override for the foreground                  |
         custom = {},
     },
     paragraph = {
@@ -489,6 +489,20 @@ require('render-markdown').setup({
         -- Highlight for the whole line generated from the icon.
         highlight = 'RenderMarkdownDash',
     },
+    document = {
+        -- Turn on / off document rendering.
+        enabled = true,
+        -- Additional modes to render document.
+        render_modes = false,
+        -- Ability to conceal arbitrary ranges of text based on lua patterns, @see :h lua-patterns.
+        -- Relies entirely on user to set patterns that handle their edge cases.
+        conceal = {
+            -- Matched ranges will be concealed using character level conceal.
+            char_patterns = {},
+            -- Matched ranges will be concealed using line level conceal.
+            line_patterns = {},
+        },
+    },
     -- Useful context to have when evaluating values.
     -- | level | how deeply nested the list is, 1-indexed          |
     -- | index | how far down the item is at that level, 1-indexed |
@@ -702,7 +716,7 @@ require('render-markdown').setup({
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern   | matched against the destination text, @see :h lua-pattern       |
+        -- | pattern   | matched against the destination text, @see :h lua-patterns      |
         -- | icon      | gets inlined before the link text                               |
         -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
         custom = {
@@ -914,10 +928,10 @@ require('render-markdown').setup({
         -- Define custom heading patterns which allow you to override various properties based on
         -- the contents of a heading.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern    | matched against the heading text @see :h lua-pattern |
-        -- | icon       | optional override for the icon                       |
-        -- | background | optional override for the background                 |
-        -- | foreground | optional override for the foreground                 |
+        -- | pattern    | matched against the heading text @see :h lua-patterns |
+        -- | icon       | optional override for the icon                        |
+        -- | background | optional override for the background                  |
+        -- | foreground | optional override for the foreground                  |
         custom = {},
     },
 })
@@ -1370,7 +1384,7 @@ require('render-markdown').setup({
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern   | matched against the destination text, @see :h lua-pattern       |
+        -- | pattern   | matched against the destination text, @see :h lua-patterns      |
         -- | icon      | gets inlined before the link text                               |
         -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
         custom = {

doc/render-markdown.txt

@@ -446,10 +446,10 @@ Default Configuration ~
             -- Define custom heading patterns which allow you to override various properties based on
             -- the contents of a heading.
             -- The key is for healthcheck and to allow users to change its values, value type below.
-            -- | pattern    | matched against the heading text @see :h lua-pattern |
-            -- | icon       | optional override for the icon                       |
-            -- | background | optional override for the background                 |
-            -- | foreground | optional override for the foreground                 |
+            -- | pattern    | matched against the heading text @see :h lua-patterns |
+            -- | icon       | optional override for the icon                        |
+            -- | background | optional override for the background                  |
+            -- | foreground | optional override for the foreground                  |
             custom = {},
         },
         paragraph = {
@@ -554,6 +554,20 @@ Default Configuration ~
             -- Highlight for the whole line generated from the icon.
             highlight = 'RenderMarkdownDash',
         },
+        document = {
+            -- Turn on / off document rendering.
+            enabled = true,
+            -- Additional modes to render document.
+            render_modes = false,
+            -- Ability to conceal arbitrary ranges of text based on lua patterns, @see :h lua-patterns.
+            -- Relies entirely on user to set patterns that handle their edge cases.
+            conceal = {
+                -- Matched ranges will be concealed using character level conceal.
+                char_patterns = {},
+                -- Matched ranges will be concealed using line level conceal.
+                line_patterns = {},
+            },
+        },
         -- Useful context to have when evaluating values.
         -- | level | how deeply nested the list is, 1-indexed          |
         -- | index | how far down the item is at that level, 1-indexed |
@@ -767,7 +781,7 @@ Default Configuration ~
             -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
             -- patterns match a link the one with the longer pattern is used.
             -- The key is for healthcheck and to allow users to change its values, value type below.
-            -- | pattern   | matched against the destination text, @see :h lua-pattern       |
+            -- | pattern   | matched against the destination text, @see :h lua-patterns      |
             -- | icon      | gets inlined before the link text                               |
             -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
             custom = {
@@ -977,10 +991,10 @@ Heading Configuration ~
             -- Define custom heading patterns which allow you to override various properties based on
             -- the contents of a heading.
             -- The key is for healthcheck and to allow users to change its values, value type below.
-            -- | pattern    | matched against the heading text @see :h lua-pattern |
-            -- | icon       | optional override for the icon                       |
-            -- | background | optional override for the background                 |
-            -- | foreground | optional override for the foreground                 |
+            -- | pattern    | matched against the heading text @see :h lua-patterns |
+            -- | icon       | optional override for the icon                        |
+            -- | background | optional override for the background                  |
+            -- | foreground | optional override for the foreground                  |
             custom = {},
         },
     })
@@ -1415,7 +1429,7 @@ Link Configuration ~
             -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
             -- patterns match a link the one with the longer pattern is used.
             -- The key is for healthcheck and to allow users to change its values, value type below.
-            -- | pattern   | matched against the destination text, @see :h lua-pattern       |
+            -- | pattern   | matched against the destination text, @see :h lua-patterns      |
             -- | icon      | gets inlined before the link text                               |
             -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
             custom = {

lua/render-markdown/config.lua

@@ -47,6 +47,7 @@ function Config.validate(spec)
     spec:config('checkbox')
     spec:config('code')
     spec:config('dash')
+    spec:config('document')
     spec:config('heading')
     spec:config('html')
     spec:config('indent')

lua/render-markdown/config/document.lua

@@ -0,0 +1,21 @@
+---@class (exact) render.md.document.Config: render.md.base.Config
+---@field conceal render.md.document.conceal.Config
+
+---@class (exact) render.md.document.conceal.Config
+---@field char_patterns string[]
+---@field line_patterns string[]
+
+local M = {}
+
+---@param spec render.md.debug.ValidatorSpec
+function M.validate(spec)
+    require('render-markdown.config.base').validate(spec)
+    spec:nested('conceal', function(conceal)
+        conceal:list('char_patterns', 'string')
+        conceal:list('line_patterns', 'string')
+        conceal:check()
+    end)
+    spec:check()
+end
+
+return M

lua/render-markdown/handler/latex.lua

@@ -41,7 +41,7 @@ function M.parse(ctx)
     for _ = 1, latex.top_pad do
         expressions[#expressions + 1] = ''
     end
-    for _, expression in ipairs(Str.split(raw_expression, '\n')) do
+    for _, expression in ipairs(Str.split(raw_expression, '\n', true)) do
         expressions[#expressions + 1] = Str.pad(node.start_col) .. expression
     end
     for _ = 1, latex.bottom_pad do

lua/render-markdown/handler/markdown.lua

@@ -22,6 +22,8 @@ function Handler.new(buf)
     self.query = ts.parse(
         'markdown',
         [[
+            (document) @document
+
             (section) @section
 
             [
@@ -56,6 +58,7 @@ function Handler.new(buf)
         checkbox = require('render-markdown.render.checkbox'),
         code = require('render-markdown.render.code'),
         dash = require('render-markdown.render.dash'),
+        document = require('render-markdown.render.document'),
         heading = require('render-markdown.render.heading'),
         paragraph = require('render-markdown.render.paragraph'),
         quote = require('render-markdown.render.quote'),

lua/render-markdown/health.lua

@@ -5,7 +5,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '8.2.11'
+M.version = '8.2.12'
 
 function M.check()
     M.start('version')

lua/render-markdown/init.lua

@@ -28,6 +28,7 @@ local M = {}
 ---@field checkbox render.md.checkbox.Config
 ---@field code render.md.code.Config
 ---@field dash render.md.dash.Config
+---@field document render.md.document.Config
 ---@field heading render.md.heading.Config
 ---@field html render.md.html.Config
 ---@field indent render.md.indent.Config
@@ -249,10 +250,10 @@ M.default = {
         -- Define custom heading patterns which allow you to override various properties based on
         -- the contents of a heading.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern    | matched against the heading text @see :h lua-pattern |
-        -- | icon       | optional override for the icon                       |
-        -- | background | optional override for the background                 |
-        -- | foreground | optional override for the foreground                 |
+        -- | pattern    | matched against the heading text @see :h lua-patterns |
+        -- | icon       | optional override for the icon                        |
+        -- | background | optional override for the background                  |
+        -- | foreground | optional override for the foreground                  |
         custom = {},
     },
     paragraph = {
@@ -357,6 +358,20 @@ M.default = {
         -- Highlight for the whole line generated from the icon.
         highlight = 'RenderMarkdownDash',
     },
+    document = {
+        -- Turn on / off document rendering.
+        enabled = true,
+        -- Additional modes to render document.
+        render_modes = false,
+        -- Ability to conceal arbitrary ranges of text based on lua patterns, @see :h lua-patterns.
+        -- Relies entirely on user to set patterns that handle their edge cases.
+        conceal = {
+            -- Matched ranges will be concealed using character level conceal.
+            char_patterns = {},
+            -- Matched ranges will be concealed using line level conceal.
+            line_patterns = {},
+        },
+    },
     -- Useful context to have when evaluating values.
     -- | level | how deeply nested the list is, 1-indexed          |
     -- | index | how far down the item is at that level, 1-indexed |
@@ -570,7 +585,7 @@ M.default = {
         -- contains. Applies to 'inline_link', 'uri_autolink', and wikilink nodes. When multiple
         -- patterns match a link the one with the longer pattern is used.
         -- The key is for healthcheck and to allow users to change its values, value type below.
-        -- | pattern   | matched against the destination text, @see :h lua-pattern       |
+        -- | pattern   | matched against the destination text, @see :h lua-patterns      |
         -- | icon      | gets inlined before the link text                               |
         -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
         custom = {

lua/render-markdown/lib/node.lua

@@ -230,7 +230,7 @@ end
 ---@param offset integer
 ---@return integer, integer
 function Node:position(index, offset)
-    local lines = Str.split(self.text:sub(1, index), '\n')
+    local lines = Str.split(self.text:sub(1, index), '\n', false)
     -- start row includes first line
     local row = self.start_row + #lines - 1
     local col = #lines[#lines] + offset

lua/render-markdown/lib/str.lua

@@ -3,9 +3,10 @@ local M = {}
 
 ---@param s string
 ---@param sep string
+---@param trimempty boolean
 ---@return string[]
-function M.split(s, sep)
-    return vim.split(s, sep, { plain = true, trimempty = true })
+function M.split(s, sep, trimempty)
+    return vim.split(s, sep, { plain = true, trimempty = trimempty })
 end
 
 ---@param s? string

lua/render-markdown/render/document.lua

@@ -0,0 +1,38 @@
+local Base = require('render-markdown.render.base')
+
+---@class render.md.render.Document: render.md.Render
+---@field private info render.md.document.Config
+local Render = setmetatable({}, Base)
+Render.__index = Render
+
+---@return boolean
+function Render:setup()
+    self.info = self.config.document
+    if self.context:skip(self.info) then
+        return false
+    end
+    return true
+end
+
+function Render:render()
+    for _, pattern in ipairs(self.info.conceal.char_patterns) do
+        for _, range in ipairs(self.node:find(pattern)) do
+            self.marks:add(true, range[1], range[2], {
+                end_row = range[3],
+                end_col = range[4],
+                conceal = '',
+            })
+        end
+    end
+    for _, pattern in ipairs(self.info.conceal.line_patterns) do
+        for _, range in ipairs(self.node:find(pattern)) do
+            self.marks:add(true, range[1], 0, {
+                end_row = range[3],
+                end_col = 0,
+                conceal_lines = '',
+            })
+        end
+    end
+end
+
+return Render

lua/render-markdown/render/shortcut.lua

@@ -63,12 +63,12 @@ function Render:callout_title(callout)
     ---Support for overriding title: https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title
     local content = self.node:parent('inline')
     if content ~= nil then
-        local line = Str.split(content.text, '\n')[1]
+        local line = Str.split(content.text, '\n', true)[1]
         if
             #line > #callout.raw
             and vim.startswith(line:lower(), callout.raw:lower())
         then
-            local icon = Str.split(callout.rendered, ' ')[1]
+            local icon = Str.split(callout.rendered, ' ', true)[1]
             local title = vim.trim(line:sub(#callout.raw + 1))
             return icon .. ' ' .. title, true
         end
@@ -96,7 +96,7 @@ function Render:wiki_link()
         return
     end
 
-    local sections = Str.split(self.node.text:sub(2, -2), '|')
+    local sections = Str.split(self.node.text:sub(2, -2), '|', true)
     ---@type render.md.link.Context
     local ctx = {
         buf = self.context.buf,

lua/render-markdown/state.lua

@@ -116,6 +116,7 @@ function M.default_buffer_config()
         checkbox = config.checkbox,
         code = config.code,
         dash = config.dash,
+        document = config.document,
         heading = config.heading,
         html = config.html,
         indent = config.indent,

lua/render-markdown/types.lua

@@ -23,6 +23,7 @@
 ---@field checkbox? render.md.checkbox.UserConfig
 ---@field code? render.md.code.UserConfig
 ---@field dash? render.md.dash.UserConfig
+---@field document? render.md.document.UserConfig
 ---@field heading? render.md.heading.UserConfig
 ---@field html? render.md.html.UserConfig
 ---@field indent? render.md.indent.UserConfig
@@ -122,6 +123,13 @@
 ---@field left_margin? number
 ---@field highlight? string
 
+---@class (exact) render.md.document.UserConfig: render.md.base.UserConfig
+---@field conceal? render.md.document.conceal.UserConfig
+
+---@class (exact) render.md.document.conceal.UserConfig
+---@field char_patterns? string[]
+---@field line_patterns? string[]
+
 ---@class (exact) render.md.heading.UserConfig: render.md.base.UserConfig
 ---@field atx? boolean
 ---@field setext? boolean