feat: add ability to center headings and code blocks

## Details

Issue: #179

This change allows `left_pad` and `right_pad` for both headings and code
blocks to interpret floating point values < 1 as a percentage of
available space. I.e. a value of 0.5 will mean 50% of the available
window space after removing the max width of the block, i.e. center it.
Integer values >= 1 continue to function as before.

- The `language_pad` option is also interpreted in this way now

The term block is used because we do not want to center every line of a
code block individually, instead we want the entire block to be centered.
This also applies to headings but these are generally one line anyway so
no real difference.

This also adds a `left_margin` option to both headings and code blocks.
The differences between padding and margin are:

- Paddings uses the highlight associated with the block
- Margin uses the overall window background color so it's "inivisible"
- It is also important to note that margin is computed after accounting for padding

As an example lets say we have a heading that occupies 40% of the
windows width. And lets say we are applying the following config:
`{ width = 'block', left_pad = 0.33, right_pad = 0.33, left_margin = 0.5 }`

- We find that 60% of the width is availble
- We add 33% of this to the left and right side, i.e. 20% of total, with
  the heading background
- For margin we find that 100% - (40% + 20% + 20%) = 20% of the space is
  available so we add half (10%) to the left with the background color
- Naturally this will leave the remaining 10% on the right so things
  should look centered
- I find this pretty neat :)

In a general sense margin is probably not very useful for `full` widths
but you can use it if you like.

Author: MeanderingProgrammer

README.md

@@ -256,9 +256,15 @@ require('render-markdown').setup({
         -- Can also be an array of the above values in which case the 'level' is used
         -- to index into the array using a clamp
         width = 'full',
+        -- Amount of margin to add to the left of headings
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Margin available space is computed after accounting for padding
+        left_margin = 0,
         -- Amount of padding to add to the left of headings
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         left_pad = 0,
         -- Amount of padding to add to the right of headings when width is 'block'
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
         min_width = 0,
@@ -307,6 +313,7 @@ require('render-markdown').setup({
         --  left:  left side of code block
         position = 'left',
         -- Amount of padding to add around the language
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         language_pad = 0,
         -- An array of language names for which background highlighting will be disabled
         -- Likely because that language has background highlights itself
@@ -315,9 +322,15 @@ require('render-markdown').setup({
         --  block: width of the code block
         --  full:  full width of the window
         width = 'full',
+        -- Amount of margin to add to the left of code blocks
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Margin available space is computed after accounting for padding
+        left_margin = 0,
         -- Amount of padding to add to the left of code blocks
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         left_pad = 0,
         -- Amount of padding to add to the right of code blocks when width is 'block'
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         right_pad = 0,
         -- Minimum width to use for code blocks when width is 'block'
         min_width = 0,
@@ -601,9 +614,15 @@ require('render-markdown').setup({
         -- Can also be an array of the above values in which case the 'level' is used
         -- to index into the array using a clamp
         width = 'full',
+        -- Amount of margin to add to the left of headings
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Margin available space is computed after accounting for padding
+        left_margin = 0,
         -- Amount of padding to add to the left of headings
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         left_pad = 0,
         -- Amount of padding to add to the right of headings when width is 'block'
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
         min_width = 0,
@@ -661,6 +680,7 @@ require('render-markdown').setup({
         --  left:  left side of code block
         position = 'left',
         -- Amount of padding to add around the language
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         language_pad = 0,
         -- An array of language names for which background highlighting will be disabled
         -- Likely because that language has background highlights itself
@@ -669,9 +689,15 @@ require('render-markdown').setup({
         --  block: width of the code block
         --  full:  full width of the window
         width = 'full',
+        -- Amount of margin to add to the left of code blocks
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Margin available space is computed after accounting for padding
+        left_margin = 0,
         -- Amount of padding to add to the left of code blocks
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         left_pad = 0,
         -- Amount of padding to add to the right of code blocks when width is 'block'
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         right_pad = 0,
         -- Minimum width to use for code blocks when width is 'block'
         min_width = 0,

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*         For 0.10.0        Last change: 2024 September 23
+*render-markdown.txt*         For 0.10.0        Last change: 2024 September 24
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -302,9 +302,15 @@ Full Default Configuration ~
             -- Can also be an array of the above values in which case the 'level' is used
             -- to index into the array using a clamp
             width = 'full',
+            -- Amount of margin to add to the left of headings
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Margin available space is computed after accounting for padding
+            left_margin = 0,
             -- Amount of padding to add to the left of headings
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             left_pad = 0,
             -- Amount of padding to add to the right of headings when width is 'block'
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             right_pad = 0,
             -- Minimum width to use for headings when width is 'block'
             min_width = 0,
@@ -353,6 +359,7 @@ Full Default Configuration ~
             --  left:  left side of code block
             position = 'left',
             -- Amount of padding to add around the language
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             language_pad = 0,
             -- An array of language names for which background highlighting will be disabled
             -- Likely because that language has background highlights itself
@@ -361,9 +368,15 @@ Full Default Configuration ~
             --  block: width of the code block
             --  full:  full width of the window
             width = 'full',
+            -- Amount of margin to add to the left of code blocks
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Margin available space is computed after accounting for padding
+            left_margin = 0,
             -- Amount of padding to add to the left of code blocks
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             left_pad = 0,
             -- Amount of padding to add to the right of code blocks when width is 'block'
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             right_pad = 0,
             -- Minimum width to use for code blocks when width is 'block'
             min_width = 0,
@@ -647,9 +660,15 @@ Wiki Page
             -- Can also be an array of the above values in which case the 'level' is used
             -- to index into the array using a clamp
             width = 'full',
+            -- Amount of margin to add to the left of headings
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Margin available space is computed after accounting for padding
+            left_margin = 0,
             -- Amount of padding to add to the left of headings
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             left_pad = 0,
             -- Amount of padding to add to the right of headings when width is 'block'
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             right_pad = 0,
             -- Minimum width to use for headings when width is 'block'
             min_width = 0,
@@ -709,6 +728,7 @@ Wiki Page
             --  left:  left side of code block
             position = 'left',
             -- Amount of padding to add around the language
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             language_pad = 0,
             -- An array of language names for which background highlighting will be disabled
             -- Likely because that language has background highlights itself
@@ -717,9 +737,15 @@ Wiki Page
             --  block: width of the code block
             --  full:  full width of the window
             width = 'full',
+            -- Amount of margin to add to the left of code blocks
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            -- Margin available space is computed after accounting for padding
+            left_margin = 0,
             -- Amount of padding to add to the left of code blocks
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             left_pad = 0,
             -- Amount of padding to add to the right of code blocks when width is 'block'
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
             right_pad = 0,
             -- Minimum width to use for code blocks when width is 'block'
             min_width = 0,

lua/render-markdown/core/context.lua

@@ -97,6 +97,19 @@ function Context:get_offset(info)
     return result
 end
 
+---@param offset number
+---@param width integer
+---@return integer
+function Context:resolve_offset(offset, width)
+    if offset <= 0 then
+        return 0
+    elseif offset < 1 then
+        return math.floor(((self:get_width() - width) * offset) + 0.5)
+    else
+        return offset
+    end
+end
+
 ---@return integer
 function Context:get_width()
     return vim.api.nvim_win_get_width(self.win)

lua/render-markdown/health.lua

@@ -4,7 +4,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '7.1.5'
+M.version = '7.1.6'
 
 function M.check()
     M.start('version')

lua/render-markdown/init.lua

@@ -112,11 +112,12 @@ local M = {}
 ---@field public sign? boolean
 ---@field public style? render.md.code.Style
 ---@field public position? render.md.code.Position
----@field public language_pad? integer
+---@field public language_pad? number
 ---@field public disable_background? string[]
 ---@field public width? render.md.code.Width
----@field public left_pad? integer
----@field public right_pad? integer
+---@field public left_margin? number
+---@field public left_pad? number
+---@field public right_pad? number
 ---@field public min_width? integer
 ---@field public border? render.md.code.Border
 ---@field public above? string
@@ -134,8 +135,9 @@ local M = {}
 ---@field public icons? string[]
 ---@field public signs? string[]
 ---@field public width? render.md.heading.Width|(render.md.heading.Width)[]
----@field public left_pad? integer
----@field public right_pad? integer
+---@field public left_margin? number
+---@field public left_pad? number
+---@field public right_pad? number
 ---@field public min_width? integer
 ---@field public border? boolean
 ---@field public border_prefix? boolean
@@ -327,9 +329,15 @@ M.default_config = {
         -- Can also be an array of the above values in which case the 'level' is used
         -- to index into the array using a clamp
         width = 'full',
+        -- Amount of margin to add to the left of headings
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Margin available space is computed after accounting for padding
+        left_margin = 0,
         -- Amount of padding to add to the left of headings
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         left_pad = 0,
         -- Amount of padding to add to the right of headings when width is 'block'
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         right_pad = 0,
         -- Minimum width to use for headings when width is 'block'
         min_width = 0,
@@ -378,6 +386,7 @@ M.default_config = {
         --  left:  left side of code block
         position = 'left',
         -- Amount of padding to add around the language
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         language_pad = 0,
         -- An array of language names for which background highlighting will be disabled
         -- Likely because that language has background highlights itself
@@ -386,9 +395,15 @@ M.default_config = {
         --  block: width of the code block
         --  full:  full width of the window
         width = 'full',
+        -- Amount of margin to add to the left of code blocks
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        -- Margin available space is computed after accounting for padding
+        left_margin = 0,
         -- Amount of padding to add to the left of code blocks
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         left_pad = 0,
         -- Amount of padding to add to the right of code blocks when width is 'block'
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
         right_pad = 0,
         -- Minimum width to use for code blocks when width is 'block'
         min_width = 0,