feature: Full anti conceal behavior, wooooo

# Details

This feature allows the plugin to hide any virtual text that
would be displayed on the line the cursor is currently on.

This enables are super fluid editing experience since nothing
is concealed or obstructed by the rendering behavior.

This is similar conceptually to concealing a link, but rather
than hiding information that is already there, we are hiding
information added by this plugin.

Since this is not a native neovim feature, i.e. I cannot set a
nice value in nvim_buf_set_extmark that makes this happen, this
feature relies on listening to the 'CursorMoved' event. This
event gets triggered on, as you would think, every cursor movement,
so this comes at a very real performance penalty.

The logic has been optimized to avoid re-parsing the entire file on
cursor movements, instead using a cached list of marks and adding the
ones outside the current line. This is noticibely faster and I have
yet to see a significant degredation. Even so the option to disable
this feature is added under the new 'anti_conceal.enabled' option.
Other ways to disable this feature (say on large files) can be added,
please submit any feature requests as an issue.

This should resolve: #15

Though it is doing the exact thing I wanted to avoid, it is easy
enough to opt out of and with the caching I have not noticed much
of a performance penalty.

Not all marks are removed, for instance sign column markers are left
as are virtual lines, since they do not interfere with the underlying
buffer text. Similarly padded code blocks (if used) are not unpadded
since that experience was not great.

Since this plugin now effectively controls the life cycle of marks
there is a breaking change for anyone using the 'custom_handlers' hook.
Rather than directly setting extmarks in the hook the information
needs to be passed back to this plugin so it can handle showing the
correct ones based on cursor position. As such the 'render' method
is on deprecation path, to be removed fully August 19th. Instead the
new 'parse' method should be defined which returns effectively the
same information

Author: MeanderingProgrammer

.gitignore

@@ -1,4 +1,5 @@
 *.cast
+medium.md
 large.md
 test.md
 test.log

README.md

@@ -12,6 +12,8 @@ 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
 - Changes window options between `rendered` and `raw` view based on configuration
   - Effects `conceallevel` & `concealcursor` by default
 - Supports rendering `markdown` injected into other file types
@@ -166,6 +168,11 @@ require('render-markdown').setup({
         -- Buftypes ignored by this plugin, see :h 'buftype'
         buftypes = {},
     },
+    anti_conceal = {
+        -- This enables hiding any added text on the line the cursor is on
+        -- This does have a performance penalty as we must listen to the 'CursorMoved' event
+        enabled = true,
+    },
     latex = {
         -- Whether LaTeX should be rendered, mainly used for health check
         enabled = true,
@@ -366,8 +373,8 @@ require('render-markdown').setup({
         concealcursor = {
             -- Used when not being rendered, get user setting
             default = vim.api.nvim_get_option_value('concealcursor', {}),
-            -- Used when being rendered, conceal text in all modes
-            rendered = 'nvic',
+            -- Used when being rendered, disable concealing text in all modes
+            rendered = '',
         },
     },
     -- Mapping from treesitter language to user defined handlers

demo/box_dash_quote.gif

@@ -1,5 +1,6 @@
 import time
 from argparse import ArgumentParser
+from pathlib import Path
 
 import pyautogui
 
@@ -9,6 +10,9 @@ def main(cols: int, rows: int, file: str, cast: str, content: str) -> None:
     pyautogui.hotkey("`", "c")
     time.sleep(1.0)
 
+    # Get length of file so we can scroll down it
+    num_lines = len(Path(file).read_text().splitlines())
+
     # Start recording demo file
     # https://docs.asciinema.org/manual/cli/usage/
     record_command: list[str] = [
@@ -30,12 +34,14 @@ def main(cols: int, rows: int, file: str, cast: str, content: str) -> None:
         pyautogui.press("esc")
         time.sleep(2.0)
 
-    # Swith between insert and normal mode a few times
-    for i in range(2):
-        pyautogui.press("i")
-        time.sleep(i + 1)
-        pyautogui.press("esc")
-        time.sleep((i + 1) * 2)
+    insert_normal(1)
+
+    # Slowly scroll down
+    for _ in range(num_lines):
+        pyautogui.press("j")
+        time.sleep(0.1)
+
+    insert_normal(1)
 
     # Close demo file
     pyautogui.write(":q!")
@@ -47,6 +53,13 @@ def main(cols: int, rows: int, file: str, cast: str, content: str) -> None:
     pyautogui.press("enter")
 
 
+def insert_normal(seconds: float) -> None:
+    pyautogui.press("i")
+    time.sleep(seconds)
+    pyautogui.press("esc")
+    time.sleep(seconds)
+
+
 if __name__ == "__main__":
     parser = ArgumentParser(description="Generate a demo recording using asciinema")
     parser.add_argument("--cols", type=int, required=True)

demo/callout.gif

@@ -3,23 +3,28 @@
 Custom handlers allow users to integrate custom rendering for either unsupported
 languages or to override / extend builtin implementations.
 
-Custom handlers are ran identically to builtin ones, so by writing custom `extmark`s
-(see :h nvim_buf_set_extmark()) to the `namespace` this plugin will handle clearing
-the `extmark`s on mode changes as well as re-rendering when needed.
+Custom handlers are ran identically to builtin ones, so by returning `extmark` data
+this plugin will handle clearing the `extmark`s on mode changes, re-rendering when
+needed, and concealing when the cursor enters.
 
 ## Interface
 
 Each handler must conform to the following interface:
 
 ```lua
+---@class render.md.Mark
+---@field public conceal boolean
+---@field public start_row integer
+---@field public start_col integer
+---@field public opts vim.api.keyset.set_extmark
+
 ---@class render.md.Handler
----@field public render fun(namespace: integer, root: TSNode, buf: integer)
+---@field public parse fun(root: TSNode, buf: integer): render.md.Mark[]
 ---@field public extends? boolean
 ```
 
-The `render` function parameters are:
+The `parse` function parameters are:
 
-- `namespace`: The id that this plugin interacts with when setting and clearing `extmark`s
 - `root`: The root treesitter node for the specified language
 - `buf`: The buffer containing the root node
 
@@ -31,45 +36,66 @@ a treesitter query is entirely up to the user if the functionality they want nee
 this. We do not provide any convenience functions, but you are more than welcome
 to use patterns from the builtin handlers.
 
+For each `mark` in the return value the fields mean:
+
+- `conceal`: determines if the mark should be hidden when cursor enters
+- `start_row`: only value used to check whether cursor is inside the `mark`
+- `start_col`: passed to `nvim_buf_set_extmark` as the 3rd argument
+- `opts`: passed directly to `nvim_buf_set_extmark`, no special handling
+
 ## Example 1: Disable a Builtin
 
-By not specifying the `extends` field and leaving the `render` implementation blank
-we can disable a builtin handler. Though this has little benefit and can be accomplished
-in other ways such as setting `{ latex_enabled = false }` for `LaTeX`.
+By not specifying the `extends` field and having the `parse` implementation return
+an empty table we can disable a builtin handler. Though this has little benefit and
+can be accomplished in other ways like setting `{ latex = { enabled = false } }`
+for `LaTeX`.
 
 Still as a toy example disabling the `LaTeX` handler can be done with:
 
 ```lua
 require('render-markdown').setup({
     custom_handlers = {
-        latex = { render = function() end },
+        latex = {
+            parse = function()
+                return {}
+            end,
+        },
     },
-}
+})
 ```
 
 ## Example 2: Highlight `python` Function Definitions
 
 This will require a treesitter query and using the range values of nodes.
 
 ```lua
--- Parse query outside of the render function to avoid doing it for each call
+-- Parse query outside of the function to avoid doing it for each call
 local query = vim.treesitter.query.parse('python', '(function_definition) @def')
-local function render_pyth    for id, node in query:iter_captures(root, buf) do
+local function parse_python(root, buf)
+    local marks = {}
+    for id, node in query:iter_captures(root, buf) do
         local capture = query.captures[id]
         local start_row, _, _, _ = node:range()
         if capture == 'def' then
-            vim.api.nvim_buf_set_extmark(buf, namespace, start_row, 0, {
-                end_row = start_row + 1,
-                end_col = 0,
-                hl_group = 'DiffDelete',
-                hl_eol = true,
+            table.insert(marks, {
+                conceal = true,
+                start_row = start_row,
+                start_col = 0,
+                opts = {
+                    end_row = start_row + 1,
+                    end_col = 0,
+                    hl_group = 'DiffDelete',
+                    hl_eol = true,
+                },
             })
         end
     end
+    return marks
 end
 require('render-markdown').setup({
+    file_types = { 'markdown', 'python' },
     custom_handlers = {
-        python = { render = render_python },
+        python = { parse = parse_python },
     },
-}
+})
 ```

demo/heading_code.gif

@@ -1,4 +1,4 @@
-*render-markdown.txt*           For 0.10.0           Last change: 2024 July 15
+*render-markdown.txt*           For 0.10.0           Last change: 2024 July 16
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -41,6 +41,8 @@ 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
 - Changes window options between `rendered` and `raw` view based on configuration
     - Effects `conceallevel` & `concealcursor` by default
 - Supports rendering `markdown` injected into other file types
@@ -202,6 +204,11 @@ Full Default Configuration ~
             -- Buftypes ignored by this plugin, see :h 'buftype'
             buftypes = {},
         },
+        anti_conceal = {
+            -- This enables hiding any added text on the line the cursor is on
+            -- This does have a performance penalty as we must listen to the 'CursorMoved' event
+            enabled = true,
+        },
         latex = {
             -- Whether LaTeX should be rendered, mainly used for health check
             enabled = true,
@@ -402,8 +409,8 @@ Full Default Configuration ~
             concealcursor = {
                 -- Used when not being rendered, get user setting
                 default = vim.api.nvim_get_option_value('concealcursor', {}),
-                -- Used when being rendered, conceal text in all modes
-                rendered = 'nvic',
+                -- Used when being rendered, disable concealing text in all modes
+                rendered = '',
             },
         },
         -- Mapping from treesitter language to user defined handlers