feat: add border option to headings

# Details

Request: #123

This add a `heading -> border` field that is a boolean. This is slightly
different to code borders since it does not seem likely that different
styles will be implemented, more just off and on. The characters added
above and below are also configurable as new options.

The logic attempts to overlay the border on empty lines but will use
virtual text lines if the line is not available. Must also be aware of
the previous heading that was overlayed since that effectively makes a
line non empty as well.

This is essentially a port of the `fat_headlines` option in
headlines.nvim: https://github.com/lukas-reineke/headlines.nvim

Author: MeanderingProgrammer

README.md

@@ -251,6 +251,12 @@ require('render-markdown').setup({
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
         min_width = 0,
+        -- Determins if a border is added above and below headings
+        border = false,
+        -- Used above heading for border
+        above = '▄',
+        -- Used below heading for border
+        below = '▀',
         -- The 'level' is used to index into the array using a clamp
         -- Highlight for the heading icon and extends through the entire line
         backgrounds = {
@@ -538,6 +544,12 @@ require('render-markdown').setup({
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
         min_width = 0,
+        -- Determins if a border is added above and below headings
+        border = false,
+        -- Used above heading for border
+        above = '▄',
+        -- Used below heading for border
+        below = '▀',
         -- The 'level' is used to index into the array using a clamp
         -- Highlight for the heading icon and extends through the entire line
         backgrounds = {

doc/render-markdown.txt

@@ -279,6 +279,12 @@ Full Default Configuration ~
             right_pad = 0,
             -- Minimum width to use for headings when width is 'block'
             min_width = 0,
+            -- Determins if a border is added above and below headings
+            border = false,
+            -- Used above heading for border
+            above = '▄',
+            -- Used below heading for border
+            below = '▀',
             -- The 'level' is used to index into the array using a clamp
             -- Highlight for the heading icon and extends through the entire line
             backgrounds = {
@@ -565,6 +571,12 @@ HEADINGS                                      *render-markdown-setup-headings*
             right_pad = 0,
             -- Minimum width to use for headings when width is 'block'
             min_width = 0,
+            -- Determins if a border is added above and below headings
+            border = false,
+            -- Used above heading for border
+            above = '▄',
+            -- Used below heading for border
+            below = '▀',
             -- The 'level' is used to index into the array using a clamp
             -- Highlight for the heading icon and extends through the entire line
             backgrounds = {

lua/render-markdown/handler/markdown.lua

@@ -13,6 +13,7 @@ local str = require('render-markdown.str')
 ---@class render.md.handler.buf.Markdown
 ---@field private buf integer
 ---@field private config render.md.BufferConfig
+---@field private last_heading_border integer
 ---@field private marks render.md.Mark[]
 local Handler = {}
 Handler.__index = Handler
@@ -23,6 +24,7 @@ function Handler.new(buf)
     local self = setmetatable({}, Handler)
     self.buf = buf
     self.config = state.get_config(buf)
+    self.last_heading_border = -1
     self.marks = {}
     return self
 end
@@ -98,20 +100,45 @@ function Handler:heading(info)
         hl_eol = true,
     })
 
+    local width = self:heading_width(info, icon_width)
+
     if heading.width == 'block' then
-        -- Overwrite anything beyond left_pad + heading width + right_pad with Normal
-        local width = heading.left_pad + icon_width + heading.right_pad
-        local content = info:sibling('inline')
-        if content ~= nil then
-            width = width + str.width(content.text) + self:added_width(content) - content:concealed()
-        end
+        -- Overwrite anything beyond width with Normal
         self:add(true, info.start_row, 0, {
             priority = 0,
             virt_text = { { str.pad(vim.o.columns * 2), 'Normal' } },
-            virt_text_win_col = math.max(width, heading.min_width),
+            virt_text_win_col = width,
         })
     end
 
+    if heading.border then
+        local text_above = { heading.above:rep(width), colors.inverse(background) }
+        if info:line('above') == '' and info.start_row - 1 ~= self.last_heading_border then
+            self:add(true, info.start_row - 1, 0, {
+                virt_text = { text_above },
+                virt_text_pos = 'overlay',
+            })
+        else
+            self:add(false, info.start_row, 0, {
+                virt_lines = { { text_above } },
+                virt_lines_above = true,
+            })
+        end
+
+        local text_below = { heading.below:rep(width), colors.inverse(background) }
+        if info:line('below') == '' then
+            self:add(true, info.end_row + 1, 0, {
+                virt_text = { text_below },
+                virt_text_pos = 'overlay',
+            })
+            self.last_heading_border = info.end_row + 1
+        else
+            self:add(false, info.end_row, 0, {
+                virt_lines = { { text_below } },
+            })
+        end
+    end
+
     if heading.left_pad > 0 then
         self:add(false, info.start_row, 0, {
             priority = 0,
@@ -160,6 +187,24 @@ function Handler:heading_icon(info, level, foreground, background)
     end
 end
 
+---@private
+---@param info render.md.NodeInfo
+---@param icon_width integer
+---@return integer
+function Handler:heading_width(info, icon_width)
+    local heading = self.config.heading
+    if heading.width == 'block' then
+        local width = heading.left_pad + icon_width + heading.right_pad
+        local content = info:sibling('inline')
+        if content ~= nil then
+            width = width + str.width(content.text) + self:added_width(content) - content:concealed()
+        end
+        return math.max(width, heading.min_width)
+    else
+        return context.get(self.buf):get_width()
+    end
+end
+
 ---@private
 ---@param info render.md.NodeInfo
 function Handler:dash(info)
@@ -287,7 +332,7 @@ function Handler:code_background(code_block, icon_added)
     })
 
     if code.width == 'block' then
-        -- Overwrite anything beyond left_pad + block width + right_pad with Normal
+        -- Overwrite anything beyond width with Normal
         local padding = str.pad(vim.o.columns * 2)
         for row = code_block.start_row, code_block.end_row - 1 do
             self:add(false, row, 0, {

lua/render-markdown/handler/markdown_inline.lua

@@ -80,8 +80,7 @@ function Handler:shortcut(info)
         return
     end
 
-    local line = info:lines()[1]
-    if line:find('[' .. info.text .. ']', 1, true) ~= nil then
+    if info:line('on'):find('[' .. info.text .. ']', 1, true) ~= nil then
         self:wiki_link(info)
         return
     end

lua/render-markdown/health.lua

@@ -5,7 +5,7 @@ local M = {}
 
 ---@private
 ---@type string
-M.version = '6.0.7'
+M.version = '6.0.8'
 
 function M.check()
     vim.health.start('render-markdown.nvim [version]')

lua/render-markdown/init.lua

@@ -108,6 +108,9 @@ local M = {}
 ---@field public left_pad? integer
 ---@field public right_pad? integer
 ---@field public min_width? integer
+---@field public border? boolean
+---@field public above? string
+---@field public below? string
 ---@field public backgrounds? string[]
 ---@field public foregrounds? string[]
 
@@ -260,6 +263,12 @@ M.default_config = {
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
         min_width = 0,
+        -- Determins if a border is added above and below headings
+        border = false,
+        -- Used above heading for border
+        above = '▄',
+        -- Used below heading for border
+        below = '▀',
         -- The 'level' is used to index into the array using a clamp
         -- Highlight for the heading icon and extends through the entire line
         backgrounds = {

lua/render-markdown/node_info.lua

@@ -110,13 +110,23 @@ function NodeInfo:for_each_child(callback)
     end
 end
 
+---@param position 'above'|'below'|'on'
+---@return string
+function NodeInfo:line(position)
+    local start_row = nil
+    if position == 'above' then
+        start_row = self.start_row - 1
+    elseif position == 'above' then
+        start_row = self.end_row + 1
+    else
+        start_row = self.start_row
+    end
+    return vim.api.nvim_buf_get_lines(self.buf, start_row, start_row + 1, false)[1]
+end
+
 ---@return string[]
 function NodeInfo:lines()
-    local end_row = self.end_row
-    if end_row == self.start_row then
-        end_row = end_row + 1
-    end
-    return vim.api.nvim_buf_get_lines(self.buf, self.start_row, end_row, false)
+    return vim.api.nvim_buf_get_lines(self.buf, self.start_row, self.end_row, false)
 end
 
 ---@return boolean

lua/render-markdown/state.lua

@@ -172,6 +172,9 @@ function M.validate()
                 left_pad = { heading.left_pad, 'number', nilable },
                 right_pad = { heading.right_pad, 'number', nilable },
                 min_width = { heading.min_width, 'number', nilable },
+                border = { heading.border, 'boolean', nilable },
+                above = { heading.above, 'string', nilable },
+                below = { heading.below, 'string', nilable },
                 backgrounds = string_array(heading.backgrounds, nilable),
                 foregrounds = string_array(heading.foregrounds, nilable),
             })

lua/render-markdown/types.lua

@@ -97,6 +97,9 @@
 ---@field public left_pad integer
 ---@field public right_pad integer
 ---@field public min_width integer
+---@field public border boolean
+---@field public above string
+---@field public below string
 ---@field public backgrounds string[]
 ---@field public foregrounds string[]