feat!: allow skipping heading indents so body is offset

## Details

Request: #161

There is a breaking change:

- `indent.skip` -> `indent.skip_level`

I added this a few hours ago so hopefully not used by many people but
noting it down in either case.

The feature request was to add an indent to section bodies offsetting
them from the section titles.

This is done, but in the other way. Instead indenting headings can be
skipped using `indent.skip_heading`. This makes it easier to calculate
reasonable offsets based on parent sections. It also avoids inconsistent
definitions for level based indentation. For instance if you're working
in an H2 then add an H4 but you still want the heading to line up with
the content of the H2 it gets strange. You might be able to count
nesting levels but this puts us back in a state we moved away from.

By skipping headings instead all the sematics and definitions stay the
same. And by simply not indenting the heading it will naturally line up
with the content of the parent section.

Author: MeanderingProgrammer

CHANGELOG.md

@@ -10,6 +10,7 @@
   - anyone using `acknowledge_conflicts` in their config should remove it
 - performance getting callouts and checkboxes [5513e28](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/5513e283973627385aec9758b00fc018e3a8303f)
 - indent based on heading level rather than nesting [27cc6ce](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/27cc6ce2605a2d42900b02648673a1de9b8cb933)
+- configurable starting indent level [cdb58fc](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/cdb58fc97c49a1ab75b35d99183c35b5863e845a)
 
 ### Bug Fixes
 
@@ -18,6 +19,7 @@
 - leading spaces in checkbox bullet [#158](https://github.com/MeanderingProgrammer/render-markdown.nvim/issues/158)
   [06337f6](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/06337f64367ef1f1115f0a9ba41e49b84a04b1a4)
 - heading borders with indentation [#164](https://github.com/MeanderingProgrammer/render-markdown.nvim/pull/164)
+- indenting heading borders with single empty line between [2ddb145](https://github.com/MeanderingProgrammer/render-markdown.nvim/commit/2ddb145c9e60267a723083b5966189b13febc72b)
 
 ### Collaborator Shoutouts
 

README.md

@@ -514,7 +514,9 @@ require('render-markdown').setup({
         per_level = 2,
         -- Heading levels <= this value will not be indented
         -- Use 0 to begin indenting from the very first level
-        skip = 1,
+        skip_level = 1,
+        -- Do not indent heading titles, only the body
+        skip_heading = false,
     },
     -- Window options to use that change between rendered and raw view
     win_options = {
@@ -941,7 +943,9 @@ require('render-markdown').setup({
         per_level = 2,
         -- Heading levels <= this value will not be indented
         -- Use 0 to begin indenting from the very first level
-        skip = 1,
+        skip_level = 1,
+        -- Do not indent heading titles, only the body
+        skip_heading = false,
     },
 })
 ```

doc/render-markdown.txt

@@ -547,7 +547,9 @@ Full Default Configuration ~
             per_level = 2,
             -- Heading levels <= this value will not be indented
             -- Use 0 to begin indenting from the very first level
-            skip = 1,
+            skip_level = 1,
+            -- Do not indent heading titles, only the body
+            skip_heading = false,
         },
         -- Window options to use that change between rendered and raw view
         win_options = {
@@ -994,7 +996,9 @@ Wiki Page
             per_level = 2,
             -- Heading levels <= this value will not be indented
             -- Use 0 to begin indenting from the very first level
-            skip = 1,
+            skip_level = 1,
+            -- Do not indent heading titles, only the body
+            skip_heading = false,
         },
     })
 <

lua/render-markdown/health.lua

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

lua/render-markdown/init.lua

@@ -29,7 +29,8 @@ local M = {}
 ---@class (exact) render.md.UserIndent
 ---@field public enabled? boolean
 ---@field public per_level? integer
----@field public skip? integer
+---@field public skip_level? integer
+---@field public skip_heading? boolean
 
 ---@class (exact) render.md.UserSign
 ---@field public enabled? boolean
@@ -579,7 +580,9 @@ M.default_config = {
         per_level = 2,
         -- Heading levels <= this value will not be indented
         -- Use 0 to begin indenting from the very first level
-        skip = 1,
+        skip_level = 1,
+        -- Do not indent heading titles, only the body
+        skip_heading = false,
     },
     -- Window options to use that change between rendered and raw view
     win_options = {

lua/render-markdown/render/base.lua

@@ -41,13 +41,20 @@ end
 
 ---@protected
 ---@param line { [1]: string, [2]: string }[]
+---@param level? integer
 ---@return { [1]: string, [2]: string }[]
-function Base:indent_virt_line(line)
+function Base:indent_virt_line(line, level)
     local indent = self.config.indent
     if not indent.enabled then
         return line
     end
-    local level = self.info:heading_level(true) - indent.skip
+    if level == nil then
+        level = self.info:heading_level(true)
+    elseif indent.skip_heading then
+        local parent = self.info:parent('section')
+        level = parent ~= nil and parent:heading_level(true) or 0
+    end
+    level = level - indent.skip_level
     if level <= 0 then
         return line
     end

lua/render-markdown/render/heading.lua

@@ -181,7 +181,7 @@ function Render:border(width)
         })
     else
         self.marks:add(false, self.info.start_row, 0, {
-            virt_lines = { self:indent_virt_line(line_above) },
+            virt_lines = { self:indent_virt_line(line_above, self.data.level) },
             virt_lines_above = true,
         })
     end
@@ -199,7 +199,7 @@ function Render:border(width)
         self.context.last_heading = self.info.end_row + 1
     else
         self.marks:add(false, self.info.end_row, 0, {
-            virt_lines = { self:indent_virt_line(line_below) },
+            virt_lines = { self:indent_virt_line(line_below, self.data.level) },
         })
     end
 end

lua/render-markdown/render/section.lua

@@ -24,7 +24,7 @@ function Render:setup()
     end
 
     local current_level = self.info:heading_level(false)
-    local parent_level = math.max(self.info:heading_level(true), self.indent.skip)
+    local parent_level = math.max(self.info:heading_level(true), self.indent.skip_level)
     self.level_change = current_level - parent_level
 
     -- Nothing to do if there is not a change in level
@@ -36,13 +36,21 @@ function Render:setup()
 end
 
 function Render:render()
-    -- Include last empty line in previous section
-    -- Exclude if it is the only empty line in that section
-    local above, two_above = self.info:line('above', 1), self.info: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
-    local start_row = math.max(self.info.start_row - start_offset, 0)
+    local start_row = nil
+    if self.indent.skip_heading then
+        -- Exclude any lines potentially used by section heading
+        local second = self.info:line('first', 1)
+        local start_offset = str.width(second) == 0 and 1 or 0
+        start_row = self.info.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.info:line('above', 1), self.info: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.info.start_row - start_offset, 0)
+    end
 
     -- Exclude last empty line in current section
     -- Include if it is the only empty line of the last subsection

lua/render-markdown/state.lua

@@ -386,7 +386,8 @@ function M.validate()
             append_errors(path .. '.indent', indent, {
                 enabled = { indent.enabled, 'boolean', nilable },
                 per_level = { indent.per_level, 'number', nilable },
-                skip = { indent.skip, 'number', nilable },
+                skip_level = { indent.skip_level, 'number', nilable },
+                skip_heading = { indent.skip_heading, 'boolean', nilable },
             })
         end
 

lua/render-markdown/types.lua

@@ -18,7 +18,8 @@
 ---@class (exact) render.md.Indent
 ---@field public enabled boolean
 ---@field public per_level integer
----@field public skip integer
+---@field public skip_level integer
+---@field public skip_heading boolean
 
 ---@class (exact) render.md.Sign
 ---@field public enabled boolean