feat: configurable language border

## Details

This change allows the user to configure how the space around the
language (above a code block) is filled, allowing for the appearance of
"tabs", rather than always having an even fill.

Previously this was not supported because of all the potential edge
cases around the language info section, user configuration, and overall
configuration (like differences in concealing).

To avoid all this complexity the implementation has been re-written to
fully overlay the border lines, removing anything custom underneath the
user may have set. This may cause problems for some obscure usage but I
can't currently think of any.

To continue supporting any potential additional info set in the language
section (a not very popular feature but it exists), the info section is
now added to the overlay. Two new features control this behavior,
`code.language_info` decides whether to include the text in general
(true by default), and `code.highlight_info` is the highlight used for
that part of the virtual text.

The main new option is `code.language_border`, which is the icon that
will be used to fill in any additional space on the language info line.
By default it is set to the full block character `█`, so when the
highlight is applied it continues to look like the `thick` border style
that was used before. To get something that looks more like a tab use
the half block character `▄`. More options may be added in the future
like a prefix and a suffix to further improve how border is rendered.

There is an edge case for users who have set `code.highlight_border` to
false, the `language_border` icon will get ignored and a space `' '` is
used to fill the gaps instead. This is because any configured characters
are unlikely to look good with the padding highlight applied to them.

As a consequence of this updated behavior we no longer rely on `inline`
virtual text to render the language, so neovim versions < `0.10.0` will
now work with the left aligned language.

While there might be some differences in behavior for some users, for
the most part the defaults we are using should result in no visible
changes out of the box.

Co-authored-by: malasee <[email protected]>

Author: MeanderingProgrammer

README.md

@@ -436,6 +436,8 @@ require('render-markdown').setup({
         language_icon = true,
         -- Whether to include the language name above code blocks.
         language_name = true,
+        -- Whether to include the language info above code blocks.
+        language_info = true,
         -- A list of language names for which background highlighting will be disabled.
         -- Likely because that language has background highlights itself.
         -- Use a boolean to make behavior apply to all languages.
@@ -463,6 +465,8 @@ require('render-markdown').setup({
         -- | thin  | when lines are empty overlay the above & below icons |
         -- | hide  | conceal lines unless language name or icon is added  |
         border = 'hide',
+        -- Used above code blocks to fill remaining space around language.
+        language_border = '█',
         -- Used above code blocks for thin border.
         above = '▄',
         -- Used below code blocks for thin border.
@@ -475,6 +479,8 @@ require('render-markdown').setup({
         inline_pad = 0,
         -- Highlight for code blocks.
         highlight = 'RenderMarkdownCode',
+        -- Highlight for code info section, after the language.
+        highlight_info = 'RenderMarkdownCodeInfo',
         -- Highlight for language, overrides icon provider value.
         highlight_language = nil,
         -- Highlight for border, use false to add no highlight.
@@ -1047,6 +1053,8 @@ require('render-markdown').setup({
         language_icon = true,
         -- Whether to include the language name above code blocks.
         language_name = true,
+        -- Whether to include the language info above code blocks.
+        language_info = true,
         -- A list of language names for which background highlighting will be disabled.
         -- Likely because that language has background highlights itself.
         -- Use a boolean to make behavior apply to all languages.
@@ -1074,6 +1082,8 @@ require('render-markdown').setup({
         -- | thin  | when lines are empty overlay the above & below icons |
         -- | hide  | conceal lines unless language name or icon is added  |
         border = 'hide',
+        -- Used above code blocks to fill remaining space around language.
+        language_border = '█',
         -- Used above code blocks for thin border.
         above = '▄',
         -- Used below code blocks for thin border.
@@ -1086,6 +1096,8 @@ require('render-markdown').setup({
         inline_pad = 0,
         -- Highlight for code blocks.
         highlight = 'RenderMarkdownCode',
+        -- Highlight for code info section, after the language.
+        highlight_info = 'RenderMarkdownCodeInfo',
         -- Highlight for language, overrides icon provider value.
         highlight_language = nil,
         -- Highlight for border, use false to add no highlight.
@@ -1547,6 +1559,7 @@ The table below shows all the highlight groups with their default link
 | RenderMarkdownH5Bg            | Visual                             | H5 background line         |
 | RenderMarkdownH6Bg            | CursorColumn                       | H6 background line         |
 | RenderMarkdownCode            | ColorColumn                        | Code block background      |
+| RenderMarkdownCodeInfo        | @label                             | Code info, after language  |
 | RenderMarkdownCodeBorder      | RenderMarkdownCode                 | Code border background     |
 | RenderMarkdownCodeFallback    | Normal                             | Fallback for code language |
 | RenderMarkdownCodeInline      | RenderMarkdownCode                 | Inline code background     |

doc/render-markdown.txt

@@ -501,6 +501,8 @@ Default Configuration ~
             language_icon = true,
             -- Whether to include the language name above code blocks.
             language_name = true,
+            -- Whether to include the language info above code blocks.
+            language_info = true,
             -- A list of language names for which background highlighting will be disabled.
             -- Likely because that language has background highlights itself.
             -- Use a boolean to make behavior apply to all languages.
@@ -528,6 +530,8 @@ Default Configuration ~
             -- | thin  | when lines are empty overlay the above & below icons |
             -- | hide  | conceal lines unless language name or icon is added  |
             border = 'hide',
+            -- Used above code blocks to fill remaining space around language.
+            language_border = '█',
             -- Used above code blocks for thin border.
             above = '▄',
             -- Used below code blocks for thin border.
@@ -540,6 +544,8 @@ Default Configuration ~
             inline_pad = 0,
             -- Highlight for code blocks.
             highlight = 'RenderMarkdownCode',
+            -- Highlight for code info section, after the language.
+            highlight_info = 'RenderMarkdownCodeInfo',
             -- Highlight for language, overrides icon provider value.
             highlight_language = nil,
             -- Highlight for border, use false to add no highlight.
@@ -1106,6 +1112,8 @@ Code Block Configuration ~
             language_icon = true,
             -- Whether to include the language name above code blocks.
             language_name = true,
+            -- Whether to include the language info above code blocks.
+            language_info = true,
             -- A list of language names for which background highlighting will be disabled.
             -- Likely because that language has background highlights itself.
             -- Use a boolean to make behavior apply to all languages.
@@ -1133,6 +1141,8 @@ Code Block Configuration ~
             -- | thin  | when lines are empty overlay the above & below icons |
             -- | hide  | conceal lines unless language name or icon is added  |
             border = 'hide',
+            -- Used above code blocks to fill remaining space around language.
+            language_border = '█',
             -- Used above code blocks for thin border.
             above = '▄',
             -- Used below code blocks for thin border.
@@ -1145,6 +1155,8 @@ Code Block Configuration ~
             inline_pad = 0,
             -- Highlight for code blocks.
             highlight = 'RenderMarkdownCode',
+            -- Highlight for code info section, after the language.
+            highlight_info = 'RenderMarkdownCodeInfo',
             -- Highlight for language, overrides icon provider value.
             highlight_language = nil,
             -- Highlight for border, use false to add no highlight.
@@ -1603,6 +1615,9 @@ The table below shows all the highlight groups with their default link
   RenderMarkdownCode              ColorColumn                          Code block
                                                                        background
 
+  RenderMarkdownCodeInfo          @label                               Code info, after
+                                                                       language
+
   RenderMarkdownCodeBorder        RenderMarkdownCode                   Code border
                                                                        background
 

lua/render-markdown/config/code.lua

@@ -5,19 +5,22 @@
 ---@field language_pad number
 ---@field language_icon boolean
 ---@field language_name boolean
+---@field language_info boolean
 ---@field disable_background boolean|string[]
 ---@field width render.md.code.Width
 ---@field left_margin number
 ---@field left_pad number
 ---@field right_pad number
 ---@field min_width integer
 ---@field border render.md.code.Border
+---@field language_border string
 ---@field above string
 ---@field below string
 ---@field inline_left string
 ---@field inline_right string
 ---@field inline_pad integer
 ---@field highlight string
+---@field highlight_info string
 ---@field highlight_language? string
 ---@field highlight_border false|string
 ---@field highlight_fallback string
@@ -79,6 +82,8 @@ M.default = {
     language_icon = true,
     -- Whether to include the language name above code blocks.
     language_name = true,
+    -- Whether to include the language info above code blocks.
+    language_info = true,
     -- A list of language names for which background highlighting will be disabled.
     -- Likely because that language has background highlights itself.
     -- Use a boolean to make behavior apply to all languages.
@@ -106,6 +111,8 @@ M.default = {
     -- | thin  | when lines are empty overlay the above & below icons |
     -- | hide  | conceal lines unless language name or icon is added  |
     border = 'hide',
+    -- Used above code blocks to fill remaining space around language.
+    language_border = '█',
     -- Used above code blocks for thin border.
     above = '▄',
     -- Used below code blocks for thin border.
@@ -118,6 +125,8 @@ M.default = {
     inline_pad = 0,
     -- Highlight for code blocks.
     highlight = 'RenderMarkdownCode',
+    -- Highlight for code info section, after the language.
+    highlight_info = 'RenderMarkdownCodeInfo',
     -- Highlight for language, overrides icon provider value.
     highlight_language = nil,
     -- Highlight for border, use false to add no highlight.
@@ -137,19 +146,22 @@ function M.validate(spec)
     spec:type('language_pad', 'number')
     spec:type('language_icon', 'boolean')
     spec:type('language_name', 'boolean')
+    spec:type('language_info', 'boolean')
     spec:list('disable_background', 'string', 'boolean')
     spec:one_of('width', vim.tbl_values(Width))
     spec:type('left_margin', 'number')
     spec:type('left_pad', 'number')
     spec:type('right_pad', 'number')
     spec:type('min_width', 'number')
     spec:one_of('border', vim.tbl_values(Border))
+    spec:type('language_border', 'string')
     spec:type('above', 'string')
     spec:type('below', 'string')
     spec:type('inline_left', 'string')
     spec:type('inline_right', 'string')
     spec:type('inline_pad', 'number')
     spec:type('highlight', 'string')
+    spec:type('highlight_info', 'string')
     spec:type('highlight_language', { 'string', 'nil' })
     spec:one_of('highlight_border', { false }, 'string')
     spec:type('highlight_fallback', 'string')

lua/render-markdown/core/colors.lua

@@ -25,6 +25,7 @@ M.colors = {
     H6Bg            = 'CursorColumn',
     -- Code
     Code            = 'ColorColumn',
+    CodeInfo        = '@label',
     CodeBorder      = 'RenderMarkdownCode',
     CodeFallback    = 'Normal',
     CodeInline      = 'RenderMarkdownCode',

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -130,9 +130,6 @@ function M.resolve_config(user)
     end
     -- override settings incompatible with neovim version with compatible alternatives
     local compat = require('render-markdown.lib.compat')
-    if config.code.position == 'left' and not compat.has_10 then
-        config.code.position = 'right'
-    end
     if config.code.border == 'hide' and not compat.has_11 then
         config.code.border = 'thin'
     end

lua/render-markdown/lib/line.lua

@@ -1,3 +1,5 @@
+local str = require('render-markdown.lib.str')
+
 ---@class render.md.Line
 ---@field private highlight string
 ---@field private line render.md.mark.Line
@@ -23,6 +25,11 @@ function Line:empty()
     return #self.line == 0
 end
 
+---@return integer
+function Line:width()
+    return str.line_width(self.line)
+end
+
 ---@param other render.md.Line
 ---@return render.md.Line
 function Line:extend(other)
@@ -44,8 +51,16 @@ end
 ---@param highlight? render.md.mark.Hl
 ---@return render.md.Line
 function Line:pad(n, highlight)
+    return self:rep(' ', n, highlight)
+end
+
+---@param s string
+---@param n integer
+---@param highlight? render.md.mark.Hl
+---@return render.md.Line
+function Line:rep(s, n, highlight)
     if n > 0 then
-        self:add((' '):rep(n), highlight)
+        self:add(s:rep(n), highlight)
     end
     return self
 end