feat: margin for paragraphs

## Details

Request: #200

Adds a new paragraph configuration which has 2 properties in addition to
the standard `enabled` field.

- `min_width`: allows you to specify a minimum width for each paragraph
  to improve general alignment when using long and short paragraphs
- `left_margin`: this functions in the same way as heading and code
  block margin where a value < 1 is treated as a fraction of the
  available window space and values >= 1 are just then number of cells
  to use for margin.

We use margin rather than padding since paragraphs do not support a
background so padding would not have any visual distenction.

Includes a minor refactor to allow `list.clamp` to resolve either a
single value or an array of values rather than only having this availble
in the heading module. That's still the only place that it's used but in
general I think it makes sense to have it more available.

Author: MeanderingProgrammer

README.md

@@ -259,6 +259,15 @@ require('render-markdown').setup({
             'RenderMarkdownH6',
         },
     },
+    paragraph = {
+        -- Turn on / off paragraph rendering
+        enabled = true,
+        -- Amount of margin to add to the left of paragraphs
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        left_margin = 0,
+        -- Minimum width to use for paragraphs
+        min_width = 0,
+    },
     code = {
         -- Turn on / off code block & inline code rendering
         enabled = true,
@@ -525,8 +534,9 @@ require('render-markdown').setup({
     -- More granular configuration mechanism, allows different aspects of buffers
     -- to have their own behavior. Values default to the top level configuration
     -- if no override is provided. Supports the following fields:
-    --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding, heading, code,
-    --   dash, bullet, checkbox, quote, pipe_table, callout, link, sign, indent, win_options
+    --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding,
+    --   heading, paragraph, code, dash, bullet, checkbox, quote, pipe_table,
+    --   callout, link, sign, indent, win_options
     overrides = {
         -- Overrides for different buftypes, see :h 'buftype'
         buftype = {
@@ -637,6 +647,30 @@ require('render-markdown').setup({
 
 </details>
 
+## Paragraphs
+
+[Wiki Page](https://github.com/MeanderingProgrammer/render-markdown.nvim/wiki/Paragraphs)
+
+<details>
+
+<summary>Paragraph Configuration</summary>
+
+```lua
+require('render-markdown').setup({
+    paragraph = {
+        -- Turn on / off paragraph rendering
+        enabled = true,
+        -- Amount of margin to add to the left of paragraphs
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        left_margin = 0,
+        -- Minimum width to use for paragraphs
+        min_width = 0,
+    },
+})
+```
+
+</details>
+
 ## Code Blocks
 
 [Wiki Page](https://github.com/MeanderingProgrammer/render-markdown.nvim/wiki/CodeBlocks)

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*          For 0.10.0         Last change: 2024 October 04
+*render-markdown.txt*          For 0.10.0         Last change: 2024 October 07
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -13,6 +13,7 @@ Table of Contents                          *render-markdown-table-of-contents*
 5. Commands                                         |render-markdown-commands|
 6. Setup                                               |render-markdown-setup|
   - Headings                                  |render-markdown-setup-headings|
+  - Paragraphs                              |render-markdown-setup-paragraphs|
   - Code Blocks                            |render-markdown-setup-code-blocks|
   - Dashed Line                            |render-markdown-setup-dashed-line|
   - List Bullets                          |render-markdown-setup-list-bullets|
@@ -307,6 +308,15 @@ Default Configuration ~
                 'RenderMarkdownH6',
             },
         },
+        paragraph = {
+            -- Turn on / off paragraph rendering
+            enabled = true,
+            -- Amount of margin to add to the left of paragraphs
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            left_margin = 0,
+            -- Minimum width to use for paragraphs
+            min_width = 0,
+        },
         code = {
             -- Turn on / off code block & inline code rendering
             enabled = true,
@@ -573,8 +583,9 @@ Default Configuration ~
         -- More granular configuration mechanism, allows different aspects of buffers
         -- to have their own behavior. Values default to the top level configuration
         -- if no override is provided. Supports the following fields:
-        --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding, heading, code,
-        --   dash, bullet, checkbox, quote, pipe_table, callout, link, sign, indent, win_options
+        --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding,
+        --   heading, paragraph, code, dash, bullet, checkbox, quote, pipe_table,
+        --   callout, link, sign, indent, win_options
         overrides = {
             -- Overrides for different buftypes, see :h 'buftype'
             buftype = {
@@ -682,6 +693,28 @@ Heading Configuration ~
 <
 
 
+PARAGRAPHS                                  *render-markdown-setup-paragraphs*
+
+Wiki Page
+<https://github.com/MeanderingProgrammer/render-markdown.nvim/wiki/Paragraphs>
+
+Paragraph Configuration ~
+
+>lua
+    require('render-markdown').setup({
+        paragraph = {
+            -- Turn on / off paragraph rendering
+            enabled = true,
+            -- Amount of margin to add to the left of paragraphs
+            -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+            left_margin = 0,
+            -- Minimum width to use for paragraphs
+            min_width = 0,
+        },
+    })
+<
+
+
 CODE BLOCKS                                *render-markdown-setup-code-blocks*
 
 Wiki Page

lua/render-markdown/core/list.lua

@@ -64,12 +64,16 @@ function M.cycle(values, index)
 end
 
 ---@generic T
----@param values T[]
+---@param values `T`|T[]
 ---@param index integer
 ---@return T
 function M.clamp(values, index)
-    assert(#values >= 1, 'Must have at least one value')
-    return values[math.min(index, #values)]
+    if type(values) == 'table' then
+        assert(#values >= 1, 'Must have at least one value')
+        return values[math.min(index, #values)]
+    else
+        return values
+    end
 end
 
 return M

lua/render-markdown/handler/markdown.lua

@@ -35,14 +35,16 @@ function Handler.new(buf)
             ] @heading)
             (setext_heading) @heading
 
+            (section (paragraph) @paragraph)
+
+            (fenced_code_block) @code
+
             [
                 (thematic_break)
                 (minus_metadata)
                 (plus_metadata)
             ] @dash
 
-            (fenced_code_block) @code
-
             [
                 (list_marker_plus)
                 (list_marker_minus)
@@ -65,6 +67,7 @@ function Handler.new(buf)
         dash = require('render-markdown.render.dash'),
         heading = require('render-markdown.render.heading'),
         list_marker = require('render-markdown.render.list_marker'),
+        paragraph = require('render-markdown.render.paragraph'),
         quote = require('render-markdown.render.quote'),
         section = require('render-markdown.render.section'),
         table = require('render-markdown.render.table'),

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -134,6 +134,11 @@ local M = {}
 ---@field public highlight? string
 ---@field public highlight_inline? string
 
+---@class (exact) render.md.UserParagraph
+---@field public enabled? boolean
+---@field public left_margin? number
+---@field public min_width? integer
+
 ---@alias render.md.heading.Position 'overlay'|'inline'
 ---@alias render.md.heading.Width 'full'|'block'
 
@@ -176,6 +181,7 @@ local M = {}
 ---@field public anti_conceal? render.md.UserAntiConceal
 ---@field public padding? render.md.UserPadding
 ---@field public heading? render.md.UserHeading
+---@field public paragraph? render.md.UserParagraph
 ---@field public code? render.md.UserCode
 ---@field public dash? render.md.UserDash
 ---@field public bullet? render.md.UserBullet
@@ -335,6 +341,15 @@ M.default_config = {
             'RenderMarkdownH6',
         },
     },
+    paragraph = {
+        -- Turn on / off paragraph rendering
+        enabled = true,
+        -- Amount of margin to add to the left of paragraphs
+        -- If a floating point value < 1 is provided it is treated as a percentage of the available window space
+        left_margin = 0,
+        -- Minimum width to use for paragraphs
+        min_width = 0,
+    },
     code = {
         -- Turn on / off code block & inline code rendering
         enabled = true,
@@ -601,8 +616,9 @@ M.default_config = {
     -- More granular configuration mechanism, allows different aspects of buffers
     -- to have their own behavior. Values default to the top level configuration
     -- if no override is provided. Supports the following fields:
-    --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding, heading, code,
-    --   dash, bullet, checkbox, quote, pipe_table, callout, link, sign, indent, win_options
+    --   enabled, max_file_size, debounce, render_modes, anti_conceal, padding,
+    --   heading, paragraph, code, dash, bullet, checkbox, quote, pipe_table,
+    --   callout, link, sign, indent, win_options
     overrides = {
         -- Overrides for different buftypes, see :h 'buftype'
         buftype = {

lua/render-markdown/render/heading.lua

@@ -59,30 +59,17 @@ function Render:setup()
         sign = list.cycle(self.heading.signs, level),
         foreground = list.clamp(self.heading.foregrounds, level),
         background = list.clamp(self.heading.backgrounds, level),
-        width = Render.resolve(self.heading.width, level),
-        left_margin = Render.resolve(self.heading.left_margin, level),
-        left_pad = Render.resolve(self.heading.left_pad, level),
-        right_pad = Render.resolve(self.heading.right_pad, level),
-        min_width = Render.resolve(self.heading.min_width, level),
+        width = list.clamp(self.heading.width, level),
+        left_margin = list.clamp(self.heading.left_margin, level),
+        left_pad = list.clamp(self.heading.left_pad, level),
+        right_pad = list.clamp(self.heading.right_pad, level),
+        min_width = list.clamp(self.heading.min_width, level),
         end_row = self.info.end_row + (atx and 1 or 0),
     }
 
     return true
 end
 
----@private
----@generic T
----@param values `T`|T[]
----@param level integer
----@return T
-function Render.resolve(values, level)
-    if type(values) == 'table' then
-        return list.clamp(values, level)
-    else
-        return values
-    end
-end
-
 function Render:render()
     local width = self:width(self:icon())
     if self.heading.sign then

lua/render-markdown/render/paragraph.lua

@@ -0,0 +1,43 @@
+local Base = require('render-markdown.render.base')
+local Iter = require('render-markdown.core.iter')
+local str = require('render-markdown.core.str')
+
+---@class render.md.render.Paragraph: render.md.Renderer
+---@field private paragraph render.md.Paragraph
+local Render = setmetatable({}, Base)
+Render.__index = Render
+
+---@param marks render.md.Marks
+---@param config render.md.buffer.Config
+---@param context render.md.Context
+---@param info render.md.NodeInfo
+---@return render.md.Renderer
+function Render:new(marks, config, context, info)
+    return Base.new(self, marks, config, context, info)
+end
+
+---@return boolean
+function Render:setup()
+    self.paragraph = self.config.paragraph
+    return self.paragraph.enabled and self.paragraph.left_margin > 0
+end
+
+function Render:render()
+    local width = vim.fn.max(Iter.list.map(self.info:lines(), str.width))
+    width = math.max(width, self.paragraph.min_width)
+    local margin = self.context:resolve_offset(self.paragraph.left_margin, width)
+    if margin <= 0 then
+        return
+    end
+
+    local virt_text = { { str.pad(margin), self.config.padding.highlight } }
+    for row = self.info.start_row, self.info.end_row - 1 do
+        self.marks:add(false, row, 0, {
+            priority = 0,
+            virt_text = virt_text,
+            virt_text_pos = 'inline',
+        })
+    end
+end
+
+return Render

lua/render-markdown/state.lua

@@ -104,6 +104,7 @@ function M.default_buffer_config()
         anti_conceal = config.anti_conceal,
         padding = config.padding,
         heading = config.heading,
+        paragraph = config.paragraph,
         code = config.code,
         dash = config.dash,
         bullet = config.bullet,
@@ -145,6 +146,12 @@ function M.validate()
             :one_or_list_of('width', { 'full', 'block' })
             :check()
 
+        validator
+            :spec(path, config, 'paragraph', nilable)
+            :type('enabled', 'boolean')
+            :type({ 'left_margin', 'min_width' }, 'number')
+            :check()
+
         validator
             :spec(path, config, 'code', nilable)
             :type({ 'enabled', 'sign' }, 'boolean')
@@ -241,8 +248,9 @@ function M.validate()
         :spec('', config)
         :type('enabled', 'boolean')
         :type({ 'max_file_size', 'debounce' }, 'number')
-        :type({ 'anti_conceal', 'padding', 'heading', 'code', 'dash', 'bullet', 'checkbox' }, 'table')
-        :type({ 'quote', 'pipe_table', 'callout', 'link', 'sign', 'indent', 'win_options' }, 'table')
+        :type({ 'anti_conceal', 'padding', 'heading', 'paragraph', 'code' }, 'table')
+        :type({ 'dash', 'bullet', 'checkbox', 'quote', 'pipe_table' }, 'table')
+        :type({ 'callout', 'link', 'sign', 'indent', 'win_options' }, 'table')
         :list('render_modes', 'string', 'boolean')
         :type('log_runtime', 'boolean')
         :type({ 'injections', 'latex', 'overrides', 'custom_handlers' }, 'table')
@@ -270,8 +278,9 @@ function M.validate()
         override_spec:for_each(function(spec)
             spec:type('enabled', 'boolean')
                 :type({ 'max_file_size', 'debounce' }, 'number')
-                :type({ 'anti_conceal', 'padding', 'heading', 'code', 'dash', 'bullet', 'checkbox' }, 'table')
-                :type({ 'quote', 'pipe_table', 'callout', 'link', 'sign', 'indent', 'win_options' }, 'table')
+                :type({ 'anti_conceal', 'padding', 'heading', 'paragraph', 'code' }, 'table')
+                :type({ 'dash', 'bullet', 'checkbox', 'quote', 'pipe_table' }, 'table')
+                :type({ 'callout', 'link', 'sign', 'indent', 'win_options' }, 'table')
                 :list('render_modes', 'string', 'boolean')
                 :check()
             validate_buffer_config(spec:get_suffix(), spec:get_input(), true)

lua/render-markdown/types.lua

@@ -110,6 +110,11 @@
 ---@field public highlight string
 ---@field public highlight_inline string
 
+---@class (exact) render.md.Paragraph
+---@field public enabled boolean
+---@field public left_margin number
+---@field public min_width integer
+
 ---@class (exact) render.md.Heading
 ---@field public enabled boolean
 ---@field public sign boolean
@@ -149,6 +154,7 @@
 ---@field public anti_conceal render.md.AntiConceal
 ---@field public padding render.md.Padding
 ---@field public heading render.md.Heading
+---@field public paragraph render.md.Paragraph
 ---@field public code render.md.Code
 ---@field public dash render.md.Dash
 ---@field public bullet render.md.Bullet

scripts/update.py

@@ -83,6 +83,7 @@ def update_readme(init_file: Path, readme_file: Path) -> None:
 
     parameters: list[str] = [
         "heading",
+        "paragraph",
         "code",
         "dash",
         "bullet",