feat: indent mode icon

## Details

Request: #343

Adds `icon` & `highlight` values to `indent` configuration. By default
the `icon` is set to the empty string resulting in no change.

However when an `icon` is provided, for example:

```lua
require('render-markdown').setup({
    indent = {
        enabled = true,
        per_level = 4,
        icon = '▎',
    },
})
```

We end up with behavior similar to `indent-blankline.nvim`, where each
set of 4 spaces starts with the configured icon, giving a quick visual
of how far indented the current section is. The icon is not limited to
one character, but users will likely choose one that is, otherwise
things get cluttered rather quickly.

Author: MeanderingProgrammer

CHANGELOG.md

@@ -14,6 +14,8 @@
   [17a7746](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/17a77463f945c4b9e4f371c752efd90e3e1bf604)
 - update troubleshooting doc [f6c9e18](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/f6c9e1841cf644a258eb037dae587e3cf407d696)
 - update `lazy` preset to match `LazyVim` [4a28c13](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/4a28c135bc3548e398ba38178fec3f705cb26fe6)
+- latex position below [#347](https://github.com/MeanderingProgrammer/render-markdown.nvim/issues/347)
+  [43a971e](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/43a971e7da82e5622797b36450424ebd66cc9046)
 
 ### Bug Fixes
 

README.md

@@ -680,6 +680,10 @@ require('render-markdown').setup({
         skip_level = 1,
         -- Do not indent heading titles, only the body
         skip_heading = false,
+        -- Prefix added when indenting, one per level
+        icon = '',
+        -- Applied to icon
+        highlight = 'RenderMarkdownIndent',
     },
     html = {
         -- Turn on / off all HTML rendering
@@ -1336,6 +1340,10 @@ require('render-markdown').setup({
         skip_level = 1,
         -- Do not indent heading titles, only the body
         skip_heading = false,
+        -- Prefix added when indenting, one per level
+        icon = '',
+        -- Applied to icon
+        highlight = 'RenderMarkdownIndent',
     },
 })
 ```
@@ -1368,6 +1376,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                |
+| RenderMarkdownIndent          | Whitespace                         | Indent icon                |
 | RenderMarkdownHtmlComment     | @comment                           | HTML comment inline text   |
 | RenderMarkdownLink            | @markup.link.label.markdown_inline | Image & hyperlink icons    |
 | RenderMarkdownWikiLink        | RenderMarkdownLink                 | WikiLink icon & text       |

doc/render-markdown.txt

@@ -741,6 +741,10 @@ Default Configuration ~
             skip_level = 1,
             -- Do not indent heading titles, only the body
             skip_heading = false,
+            -- Prefix added when indenting, one per level
+            icon = '',
+            -- Applied to icon
+            highlight = 'RenderMarkdownIndent',
         },
         html = {
             -- Turn on / off all HTML rendering
@@ -1373,6 +1377,10 @@ Indent Configuration ~
             skip_level = 1,
             -- Do not indent heading titles, only the body
             skip_heading = false,
+            -- Prefix added when indenting, one per level
+            icon = '',
+            -- Applied to icon
+            highlight = 'RenderMarkdownIndent',
         },
     })
 <
@@ -1431,6 +1439,8 @@ The table below shows all the highlight groups with their default link
 
   RenderMarkdownMath              @markup.math                         LaTeX lines
 
+  RenderMarkdownIndent            Whitespace                           Indent icon
+
   RenderMarkdownHtmlComment       @comment                             HTML comment inline
                                                                        text
 

lua/render-markdown/colors.lua

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

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -62,6 +62,8 @@ local M = {}
 ---@field public per_level? integer
 ---@field public skip_level? integer
 ---@field public skip_heading? boolean
+---@field public icon? string
+---@field public highlight? string
 
 ---@class (exact) render.md.UserInlineHighlight: render.md.UserBaseComponent
 ---@field public highlight? string
@@ -814,6 +816,10 @@ M.default_config = {
         skip_level = 1,
         -- Do not indent heading titles, only the body
         skip_heading = false,
+        -- Prefix added when indenting, one per level
+        icon = '',
+        -- Applied to icon
+        highlight = 'RenderMarkdownIndent',
     },
     html = {
         -- Turn on / off all HTML rendering

lua/render-markdown/render/base.lua

@@ -2,6 +2,12 @@ local Iter = require('render-markdown.lib.iter')
 local Str = require('render-markdown.lib.str')
 local colors = require('render-markdown.colors')
 
+---@class render.md.line.Text
+---@field [1] string text
+---@field [2] string|string[] highlights
+
+---@alias render.md.Line render.md.line.Text[]
+
 ---@class render.md.Renderer
 ---@field protected marks render.md.Marks
 ---@field protected config render.md.buffer.Config
@@ -75,42 +81,64 @@ function Base:from_destination(icon, highlight, destination)
 end
 
 ---@protected
----@param line { [1]: string, [2]: string }[]
+---@param virtual boolean
 ---@param level? integer
----@return { [1]: string, [2]: string }[]
-function Base:indent_virt_line(line, level)
-    local amount = self:indent(level)
-    if amount > 0 then
-        table.insert(line, 1, self:padding_text(amount))
+---@return render.md.Line
+function Base:indent_line(virtual, level)
+    if virtual then
+        level = self:indent_level(level)
+    else
+        assert(level ~= nil, 'Level must be known for real lines')
+    end
+    local line = {}
+    if level > 0 then
+        local indent = self.config.indent
+        local icon_width = Str.width(indent.icon)
+        if icon_width == 0 then
+            table.insert(line, self:padding_text(indent.per_level * level))
+        else
+            for _ = 1, level do
+                table.insert(line, { indent.icon, indent.highlight })
+                table.insert(line, self:padding_text(indent.per_level - icon_width))
+            end
+        end
     end
     return line
 end
 
 ---@protected
 ---@param level? integer
 ---@return integer
-function Base:indent(level)
+function Base:indent_size(level)
+    return self.config.indent.per_level * self:indent_level(level)
+end
+
+---@private
+---@param level? integer
+---@return integer
+function Base:indent_level(level)
     local indent = self.config.indent
     if self.context:skip(indent) then
         return 0
     end
     if level == nil then
+        -- Level is not known, get it from the closest parent section
         level = self.node:level(true)
-    elseif indent.skip_heading then
-        local parent = self.node:parent('section')
-        level = parent ~= nil and parent:level(true) or 0
-    end
-    level = level - indent.skip_level
-    if level <= 0 then
-        return 0
+    else
+        -- Level is known, must be a heading
+        if indent.skip_heading then
+            -- Account for ability to skip headings
+            local parent = self.node:parent('section')
+            level = parent ~= nil and parent:level(true) or 0
+        end
     end
-    return indent.per_level * level
+    return math.max(level - indent.skip_level, 0)
 end
 
 ---@protected
 ---@param width integer
 ---@param highlight? string
----@return { [1]: string, [2]: string }
+---@return render.md.line.Text
 function Base:padding_text(width, highlight)
     return { Str.pad(width), highlight or self.config.padding.highlight }
 end

lua/render-markdown/render/code.lua

@@ -64,7 +64,7 @@ function Render:setup()
         padding = left_padding,
         max_width = max_width,
         empty_rows = empty_rows,
-        indent = self:indent(),
+        indent = self:indent_size(),
     }
 
     return true

lua/render-markdown/render/heading.lua

@@ -99,7 +99,8 @@ function Render:render()
     self:background(width)
     self:left_pad(width)
     if self.data.atx then
-        self:border(width)
+        self:border(width, 'above', self.heading.above, self.node.start_row - 1)
+        self:border(width, 'below', self.heading.below, self.node.end_row)
     else
         self:conceal_underline()
     end
@@ -205,7 +206,7 @@ function Render:background(width)
     end
     local win_col, padding = 0, {}
     if self.data.width == 'block' then
-        win_col = width.margin + width.content + self:indent(self.data.level)
+        win_col = width.margin + width.content + self:indent_size(self.data.level)
         table.insert(padding, self:padding_text(vim.o.columns * 2))
     end
     for row = self.node.start_row, self.node.end_row - 1 do
@@ -227,73 +228,44 @@ end
 
 ---@private
 ---@param width render.md.width.Heading
-function Render:border(width)
+---@param position 'above'|'below'
+---@param icon string
+---@param row integer
+function Render:border(width, position, icon, row)
     if not self.data.border then
         return
     end
 
     local foreground = self.data.foreground
     local background = self.data.background and colors.bg_to_fg(self.data.background)
+    local total_width = self.data.width == 'block' and width.content or vim.o.columns
     local prefix = self.heading.border_prefix and self.data.level or 0
-    local virtual = self.heading.border_virtual
 
-    ---@param icon string
-    ---@return { [1]: string, [2]: string }[]
-    local function line(icon)
-        ---@param size integer
-        ---@param highlight? string
-        ---@return { [1]: string, [2]: string }
-        local function section(size, highlight)
-            if highlight ~= nil then
-                return { icon:rep(size), highlight }
-            else
-                return self:padding_text(size)
-            end
-        end
-        local content_width = self.data.width == 'block' and width.content or vim.o.columns
-        return {
-            section(width.margin, nil),
-            section(width.padding, background),
-            section(prefix, foreground),
-            section(content_width - width.padding - prefix, background),
-        }
-    end
+    local line = {
+        self:padding_text(width.margin),
+        { icon:rep(width.padding), background },
+        { icon:rep(prefix), foreground },
+        { icon:rep(total_width - width.padding - prefix), background },
+    }
 
-    local line_above = line(self.heading.above)
-    if not virtual and self:empty_line('above') and self.node.start_row - 1 ~= self.context.last_heading then
-        self.marks:add('head_border', self.node.start_row - 1, 0, {
-            virt_text = line_above,
-            virt_text_pos = 'overlay',
-        })
-    else
-        self.marks:add(false, self.node.start_row, 0, {
-            virt_lines = { self:indent_virt_line(line_above, self.data.level) },
-            virt_lines_above = true,
-        })
-    end
+    local virtual = self.heading.border_virtual
+    local target_line = self.node:line(position, 1)
+    local line_available = target_line ~= nil and Str.width(target_line) == 0
 
-    local line_below = line(self.heading.below)
-    if not virtual and self:empty_line('below') then
-        self.marks:add('head_border', self.node.end_row, 0, {
-            virt_text = line_below,
+    if not virtual and line_available and row ~= self.context.last_heading then
+        self.marks:add('head_border', row, 0, {
+            virt_text = line,
             virt_text_pos = 'overlay',
         })
-        self.context.last_heading = self.node.end_row
+        self.context.last_heading = row
     else
         self.marks:add(false, self.node.start_row, 0, {
-            virt_lines = { self:indent_virt_line(line_below, self.data.level) },
+            virt_lines = { vim.list_extend(self:indent_line(true, self.data.level), line) },
+            virt_lines_above = position == 'above',
         })
     end
 end
 
----@private
----@param position 'above'|'below'
----@return boolean
-function Render:empty_line(position)
-    local line = self.node:line(position, 1)
-    return line ~= nil and Str.width(line) == 0
-end
-
 ---@private
 ---@param width render.md.width.Heading
 function Render:left_pad(width)

lua/render-markdown/render/section.lua

@@ -27,38 +27,48 @@ function Render:setup()
 end
 
 function Render:render()
-    local start_row = nil
+    local start_row = self:get_start_row()
+    local end_row = self:get_end_row()
+    -- Each level stacks inline marks so we only need to process change in level
+    local virt_text = self:indent_line(false, self.level_change)
+    for row = start_row, end_row do
+        self.marks:add(false, row, 0, {
+            priority = 0,
+            virt_text = virt_text,
+            virt_text_pos = 'inline',
+        })
+    end
+end
+
+---@private
+---@return integer
+function Render:get_start_row()
     if self.indent.skip_heading then
         -- Exclude any lines potentially used by section heading
         local second = self.node:line('first', 1)
         local start_offset = Str.width(second) == 0 and 1 or 0
-        start_row = self.node.start_row + 1 + start_offset
+        return self.node.start_row + 1 + start_offset
     else
         -- Include last empty line in previous section
         -- Exclude if it is the only empty line in that section
         local above, two_above = self.node:line('above', 1), self.node:line('above', 2)
         local above_is_empty = Str.width(above) == 0
         local two_above_is_section = two_above ~= nil and vim.startswith(two_above, '#')
         local start_offset = (above_is_empty and not two_above_is_section) and 1 or 0
-        start_row = math.max(self.node.start_row - start_offset, 0)
+        return math.max(self.node.start_row - start_offset, 0)
     end
+end
 
+---@private
+---@return integer
+function Render:get_end_row()
     -- Exclude last empty line in current section
     -- Include if it is the only empty line of the last subsection
     local last, second_last = self.node:line('last', 0), self.node:line('last', 1)
     local last_is_empty = Str.width(last) == 0
     local second_last_is_section = second_last ~= nil and vim.startswith(second_last, '#')
     local end_offset = (last_is_empty and not second_last_is_section) and 1 or 0
-    local end_row = self.node.end_row - 1 - end_offset
-
-    -- Each level stacks inline marks so we only need to multiply based on any skipped levels
-    for row = start_row, end_row do
-        self.marks:add(false, row, 0, {
-            priority = 0,
-            virt_text = { self:padding_text(self.indent.per_level * self.level_change) },
-            virt_text_pos = 'inline',
-        })
-    end
+    return self.node.end_row - 1 - end_offset
 end
 
 return Render