feat: combine latex virtual lines use center positioning

## Details

Request: #520

This is a fairly substantial re-work of how latex formulas ultimately
get rendered.

The first major change is now, regardless of positioning, we will
attempt to combine virtual lines related to latex formulas. This means
for instance if the position is set to `above`, there are 3 formulas on
a particular row, and each of them renders as 3 lines, these will get
padded and combined together such that only 3 virtual lines are added to
show all the formulas, rather than 3 lines each, producing 9 hard to
follow virtual lines. This is possible thanks to the recent changes that
allow us to process all the nodes at once and do a row level ordering.

The second change is the addition of the `center` position value, which
is also the new default. When this is set virtual lines flow through the
actual text. What this means is if a formula is rendered as 3 lines, one
virtual line will be added above, one virtual line will be added below,
and the center line will be inlined into the actual text. This makes the
rendering feel much more like it is part of the document rather than
entirely separate. This is only possible if the underlying latex nodes
are a single line exactly. Once you have multi-line nodes we end up with
much more edge cases, so multi-line nodes are rendered using the `above`
value if `center` is set. If the position is set to `above` or `below`
then no override happens.

The `latex.virtual` parameter has been removed, as it is now redundant.
Users who set a position of `above` or `below` will always get only
virtual lines so there is no need for the additional setting. It is now
the case that only the `center` position is capable of any amount of
inline rendering, and again, it is limited to single line equations
only.

Author: MeanderingProgrammer

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Pre-release
 
+### Features
+
+- remove delimiters around latex text before converting [2c6cf12](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/2c6cf127c577712bd29d38f6391b3045c5f0180a)
+- convert latex asynchronously [44cbac6](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/44cbac697e50ae32e4644652da08cf692b9a5a57)
+
+### Bug Fixes
+
+- use display width of concealed ranges [b4885a9](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/b4885a95e5082a6ed164830c581aac257a74f355)
+
 ## 8.8.0 (2025-09-09)
 
 ### Features

README.md

@@ -276,15 +276,14 @@ require('render-markdown').setup({
         -- Highlight for latex blocks.
         highlight = 'RenderMarkdownMath',
         -- Determines where latex formula is rendered relative to block.
-        -- | above | above latex block |
-        -- | below | below latex block |
-        position = 'above',
+        -- | above  | above latex block                               |
+        -- | below  | below latex block                               |
+        -- | center | centered with latex block (must be single line) |
+        position = 'center',
         -- Number of empty lines above latex blocks.
         top_pad = 0,
         -- Number of empty lines below latex blocks.
         bottom_pad = 0,
-        -- Always use virtual lines for rendering instead of attempting to inline.
-        virtual = false,
     },
     on = {
         -- Called when plugin initially attaches to a buffer.

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*      For NVIM v0.11.4     Last change: 2025 September 14
+*render-markdown.txt*      For NVIM v0.11.4     Last change: 2025 September 15
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -338,15 +338,14 @@ Default Configuration ~
             -- Highlight for latex blocks.
             highlight = 'RenderMarkdownMath',
             -- Determines where latex formula is rendered relative to block.
-            -- | above | above latex block |
-            -- | below | below latex block |
-            position = 'above',
+            -- | above  | above latex block                               |
+            -- | below  | below latex block                               |
+            -- | center | centered with latex block (must be single line) |
+            position = 'center',
             -- Number of empty lines above latex blocks.
             top_pad = 0,
             -- Number of empty lines below latex blocks.
             bottom_pad = 0,
-            -- Always use virtual lines for rendering instead of attempting to inline.
-            virtual = false,
         },
         on = {
             -- Called when plugin initially attaches to a buffer.

lua/render-markdown/config/latex.lua

@@ -4,12 +4,12 @@
 ---@field position render.md.latex.Position
 ---@field top_pad integer
 ---@field bottom_pad integer
----@field virtual boolean
 
 ---@enum render.md.latex.Position
 local Position = {
     above = 'above',
     below = 'below',
+    center = 'center',
 }
 
 ---@class render.md.latex.Cfg
@@ -26,15 +26,14 @@ M.default = {
     -- Highlight for latex blocks.
     highlight = 'RenderMarkdownMath',
     -- Determines where latex formula is rendered relative to block.
-    -- | above | above latex block |
-    -- | below | below latex block |
-    position = 'above',
+    -- | above  | above latex block                               |
+    -- | below  | below latex block                               |
+    -- | center | centered with latex block (must be single line) |
+    position = 'center',
     -- Number of empty lines above latex blocks.
     top_pad = 0,
     -- Number of empty lines below latex blocks.
     bottom_pad = 0,
-    -- Always use virtual lines for rendering instead of attempting to inline.
-    virtual = false,
 }
 
 ---@return render.md.Schema
@@ -45,7 +44,6 @@ function M.schema()
         position = { enum = Position },
         top_pad = { type = 'number' },
         bottom_pad = { type = 'number' },
-        virtual = { type = 'boolean' },
     })
 end
 

lua/render-markdown/handler/latex.lua

@@ -44,8 +44,9 @@ function Handler:run(root, last)
     if last then
         local nodes = self.context.latex:get()
         self:convert(nodes)
-        for _, row in ipairs(self:rows(nodes)) do
-            self:render(row)
+        local rows = self:rows(nodes)
+        for row, row_nodes in pairs(rows) do
+            self:render(row, row_nodes)
         end
     end
     return self.marks:get()
@@ -90,67 +91,156 @@ end
 
 ---@private
 ---@param nodes render.md.Node[]
----@return render.md.Node[][]
+---@return table<integer, render.md.Node[]>
 function Handler:rows(nodes)
-    table.sort(nodes)
-    local result = {} ---@type render.md.Node[][]
-    result[#result + 1] = { nodes[1] }
-    for i = 2, #nodes do
-        local node, last = nodes[i], result[#result]
-        if node.start_row == last[#last].start_row then
-            last[#last + 1] = node
+    local position = self.config.position
+
+    ---@param node render.md.Node
+    ---@return integer, integer
+    local function get(node)
+        if position == 'below' and node:height() > 1 then
+            return node.end_row, 0
+        else
+            return node.start_row, node.start_col
+        end
+    end
+
+    table.sort(nodes, function(a, b)
+        local a_row, a_col = get(a)
+        local b_row, b_col = get(b)
+        if a_row ~= b_row then
+            return a_row < b_row
         else
-            result[#result + 1] = { node }
+            return a_col < b_col
+        end
+    end)
+
+    local result = {} ---@type table<integer, render.md.Node[]>
+    for _, node in ipairs(nodes) do
+        local node_row = get(node)
+        if not result[node_row] then
+            result[node_row] = {}
         end
+        local row = result[node_row]
+        row[#row + 1] = node
     end
     return result
 end
 
 ---@private
+---@param row integer
 ---@param nodes render.md.Node[]
-function Handler:render(nodes)
+function Handler:render(row, nodes)
     local first = nodes[1]
     local indent = self:indent(first)
-    local _, line = first:line('first', 0)
+
+    local lines_above = {} ---@type string[]
+    local lines_below = {} ---@type string[]
+    local current = 0
 
     for _, node in ipairs(nodes) do
         local output = str.split(Handler.cache[Handler.text(node)], '\n', true)
-        if self.config.virtual or #output > 1 then
-            local col = node.start_col
-            local prefix = str.pad(line and str.width(line:sub(1, col)) or col)
-            local width = vim.fn.max(iter.list.map(output, str.width))
-
-            local texts = {} ---@type string[]
-            for _ = 1, self.config.top_pad do
-                texts[#texts + 1] = ''
-            end
-            for _, text in ipairs(output) do
-                local suffix = str.pad(width - str.width(text))
-                texts[#texts + 1] = prefix .. text .. suffix
-            end
-            for _ = 1, self.config.bottom_pad do
-                texts[#texts + 1] = ''
-            end
 
-            local lines = iter.list.map(texts, function(text)
-                return indent:copy():text(text, self.config.highlight):get()
-            end)
+        -- pad lines to the same width
+        local width = vim.fn.max(iter.list.map(output, str.width))
+        for i, line in ipairs(output) do
+            output[i] = line .. str.pad(width - str.width(line))
+        end
 
-            local above = self.config.position == 'above'
-            local row = above and node.start_row or node.end_row
+        -- center is only possible if formula is a single line
+        local position = self.config.position
+        if position == 'center' and node:height() > 1 then
+            position = 'above'
+        end
 
-            self.marks:add(self.config, 'virtual_lines', row, 0, {
-                virt_lines = lines,
-                virt_lines_above = above,
+        -- absolute formula column
+        local col ---@type integer
+        if position == 'below' and node:height() > 1 then
+            -- latex blocks include last line, unlike markdown blocks
+            local _, line = node:line('below', 1)
+            col = line and str.spaces('start', line) or 0
+        else
+            local _, line = node:line('above', 0)
+            col = self.context:width({
+                text = line and line:sub(1, node.start_col) or '',
+                start_row = node.start_row,
+                start_col = 0,
+                end_row = node.start_row,
+                end_col = node.start_col,
             })
+        end
+
+        -- convert column to relative offset, include padding between formulas
+        local prefix = math.max(col - current, current == 0 and 0 or 1)
+
+        local above ---@type integer
+        local below ---@type integer
+        if position == 'above' then
+            above = #output
+            below = 0
+        elseif position == 'below' then
+            above = 0
+            below = #output
         else
+            assert(node:height() == 1, 'invalid center height')
+            local center = math.floor(#output / 2) + 1
+            above = center - 1
+            below = #output - center
             self.marks:over(self.config, true, node, {
-                virt_text = { { output[1], self.config.highlight } },
+                virt_text = { { output[center], self.config.highlight } },
                 virt_text_pos = 'inline',
                 conceal = '',
             })
         end
+
+        -- fill in new lines at top and bottom
+        while #lines_above < above do
+            table.insert(lines_above, 1, str.pad(current))
+        end
+        while #lines_below < below do
+            lines_below[#lines_below + 1] = str.pad(current)
+        end
+
+        -- concatenate output onto lines
+        for i, line in ipairs(lines_above) do
+            local index = i - (#lines_above - above)
+            local body = output[index] or str.pad(width)
+            lines_above[i] = line .. str.pad(prefix) .. body
+        end
+        for i, line in ipairs(lines_below) do
+            local index = i + (#output - below)
+            local body = output[index] or str.pad(width)
+            lines_below[i] = line .. str.pad(prefix) .. body
+        end
+
+        -- update current width of lines
+        current = current + prefix + width
     end
+
+    ---@param lines string[]
+    ---@param top boolean
+    ---@param bottom boolean
+    ---@param above boolean
+    local function add_lines(lines, top, bottom, above)
+        if #lines == 0 then
+            return
+        end
+        for _ = 1, (top and self.config.top_pad or 0) do
+            table.insert(lines, 1, '')
+        end
+        for _ = 1, (bottom and self.config.bottom_pad or 0) do
+            lines[#lines + 1] = ''
+        end
+        self.marks:add(self.config, 'virtual_lines', row, 0, {
+            virt_lines = iter.list.map(lines, function(line)
+                return indent:copy():text(line, self.config.highlight):get()
+            end),
+            virt_lines_above = above,
+        })
+    end
+
+    add_lines(lines_above, true, #lines_below == 0, true)
+    add_lines(lines_below, #lines_above == 0, true, false)
 end
 
 ---@private

lua/render-markdown/health.lua

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

lua/render-markdown/lib/node.lua

@@ -63,6 +63,11 @@ function Node:get()
     return self.node
 end
 
+---@return integer
+function Node:height()
+    return self.end_row - self.start_row + 1
+end
+
 ---@return integer[]
 function Node:sections()
     local result = {} ---@type integer[]
@@ -218,15 +223,14 @@ end
 ---@return integer, string?
 function Node:line(position, by)
     local row ---@type integer
-    local single = self.start_row == self.end_row
     if position == Position.above then
         row = self.start_row - by
     elseif position == Position.first then
         row = self.start_row + by
     elseif position == Position.below then
-        row = self.end_row - (single and 0 or 1) + by
+        row = self.end_row - (self:height() == 1 and 0 or 1) + by
     elseif position == Position.last then
-        row = self.end_row - (single and 0 or 1) - by
+        row = self.end_row - (self:height() == 1 and 0 or 1) - by
     else
         error(('invalid position: %s'):format(position))
     end

lua/render-markdown/types.lua

@@ -198,7 +198,6 @@
 ---@field position? render.md.latex.Position
 ---@field top_pad? integer
 ---@field bottom_pad? integer
----@field virtual? boolean
 
 ---@class (exact) render.md.link.UserConfig: render.md.base.UserConfig
 ---@field footnote? render.md.link.footnote.UserConfig