render-markdown.nvim:以 demo/heading_code.md 为例,逐层拆解标题、图片与代码块的渲染实现

原创2026-10-12 09:07:371,444 阅读
文章标签:开发工具

render-markdown.nvim:以 demo/heading_code.md 为例,逐层拆解标题、图片与代码块的渲染实现

demo/heading_code.md 是 render-markdown.nvim 仓库中最小但信息量完整的演示样例:仅 23 行文本,就同时覆盖了 atx 标题、图片链接、带 info 字符串的围栏代码块三类元素。本文以该文件为主轴,结合 渲染器源码、测试断言 与 演示生成脚本,完整讲清这份样例在 Neovim 中被渲染成什么样、为什么是这样,以及如何复现官方的演示 GIF。

一、样例文件本身:一份“最小渲染清单”

demo/heading_code.md 的完整内容如下:

# Heading 1

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Image

```python {filename="demo.py"}
def main() -> None:
    sum = 0
    for i in range(10):
        sum += i
    print(sum)


if __name__ == "__main__":
    main()

从源码结构看,这个文件恰好挑中了三条核心渲染路径:

| 元素 | 覆盖的渲染器 | 关键行为 |
| --- | --- | --- |
| `#`~`######` 标题(缺 H2,共 5 级) | <a href="https://link.gitcode.com/i/1b7d60485e594915d0068cf4d5a91f7f" target="_blank">heading.lua</a> | `#` 记号被 conceal,替换为按级别取值的图标,整行铺背景色,sign 列加符号 |
| `Image` | <a href="https://link.gitcode.com/i/84ffcbc2e131cb32b40b58de865df76a" target="_blank">link.lua</a> | `image` 分支把 `[![` 替换为图片图标,目标文件不存在的链接不影响渲染 |
| `python {filename="demo.py"}` 围栏代码块 | <a href="https://link.gitcode.com/i/b75a67cd7722dd7a09d2233f2526ac88" target="_blank">code.lua</a>](https://gitcode.com/gh_mirrors/ma/markdown.nvim?utm_source=gitcode_repo_files) | 解析 `info_string` 中的语言与额外参数,生成语言标题栏、背景与边框 |

值得注意的是样例刻意省略了 H2:<a href="https://link.gitcode.com/i/e8b544e21b48b676f4d8db82d803b8a9" target="_blank">demo/run.py</a> 的 `DEMOS` 表为 `heading_code` 配置了第二个参数 `"## Heading 2"`,演示 GIF 会在录制过程中实时输入这一行,展示标题编辑后的即时重渲染(H2 图标与 H1 不同)。

## 二、演示生产管线:从 markdown 文件到 GIF

`justfile` 定义了完整的录制入口(<a href="https://link.gitcode.com/i/9199882379302ad6af29bbf7517035bb" target="_blank">justfile</a>):

```console
just demo      # 依次生成 heading / table / quote / callout / latex 五组演示
just heading   # 等价于 python demo/run.py --name "heading_code"

run.py 的工作流分两步:

  1. 生成 GIF:读取模板 demo/format.tape,替换其中的 INPUT(输入文件)、OUTPUT(输出 gif)、WIDTH/HEIGHT、WRITE(是否输入 ## Heading 2)与 MOVE(逐行滚动指令)占位符,再交给 chancez/vhs 执行。format.tape 的核心动作是:

    Type "nvim -u demo/minit.lua INPUT" Enter   # 用最小配置打开样例
    Down
    Type "i" Sleep 0.5s
    Screenshot default.png                       # 插入模式(未渲染)截图
    Escape Sleep 0.5s
    Screenshot rendered.png                      # 普通模式(已渲染)截图
    

    随后 create_screenshot 会把 default.png 与 rendered.png 左右拼接成 demo/heading_code.png,形成“原始文本 vs 渲染效果”的对照图。

  2. 最小运行配置:demo/minit.lua 展示了让该样例正确渲染所需的完整依赖面:

    vim.pack.add({
        'https://github.com/folke/tokyonight.nvim',
        'https://github.com/nvim-treesitter/nvim-treesitter',
        'https://github.com/nvim-mini/mini.nvim',
        'https://github.com/nvim-lualine/lualine.nvim',
    })
    vim.cmd.packadd('render-markdown.nvim')
    require('nvim-treesitter')
        .install({ 'html', 'latex', 'markdown', 'markdown_inline', 'yaml' })
        :wait()
    -- mini.icons 负责提供代码块语言图标(󰌠)
    local icons = require('mini.icons')
    icons.setup({})
    icons.mock_nvim_web_devicons()
    require('render-markdown').setup({})
    

    关键点:Treesitter 的 markdown / markdown_inline parser 是必需的(渲染全部基于语法树节点),mini.icons(或 nvim-web-devicons)是可选的图标提供方,用于代码块语言图标与图片图标。

在克隆本仓库并安装 vhs、Pillow 后,执行 just heading 即可复现官方演示产物。

三、测试断言:23 行文本渲染成什么

tests/demo/heading_code_spec.lua 对同一文件做了逐 mark 断言,其 assert_view 给出的最终视图是验证渲染效果最权威的依据:

󰫎 󰲡 Heading 1
<空行>
󰫎   󰲥 Heading 3
<空行>
󰫎    󰲧 Heading 4
<空行>
󰫎     󰲩 Heading 5
<空行>
󰫎      󰲫 Heading 6
<空行>
  󰥶 Image
<空行>
󰌠 󰌠 python {filename="demo.py"}█████████████████████████████████████████████████
  def main() -> None:
      sum = 0
      for i in range(10):
          sum += i
      print(sum)
<空行>
<空行>
  if __name__ == "__main__":
      main()

对照 heading_code_spec.lua 的 mark 断言可以读出三层叠加关系:

  • sign 列:util.heading.sign(level) —— 每级标题在 sign 列都插入 󰫎(来自 heading.signs 默认值 { '󰫎 ' },按级别 cycle);
  • 行首图标:util.heading.icon(level) —— # 记号被 conceal,原位置覆盖为级别图标(H1 是 󰲡,H3~H6 依次是 󰲥/󰲧/󰲩/󰲫);
  • 行背景:util.heading.bg(level) —— 整行 hl_eol 高亮,分别对应 RenderMarkdownH1Bg~RenderMarkdownH6Bg。

代码块部分,测试断言了 util.code.sign('python')(sign 列语言图标)、util.code.border('█', true, 'python', ' {filename="demo.py"}', 1)(语言标题栏)以及 util.conceal_lines()(上下围栏行被整行 conceal,即 border = 'hide' 的行为),正文每一行都带 util.code.bg() 背景。

四、标题渲染实现拆解(heading.lua)

heading.lua 的 setup 先做节点类型分派(L46-L56):

  • atx_heading:level = str.char_count(marker.text, '#'),即直接数 # 的个数得出级别;
  • setext_heading:按下划线节点类型区分 1 级(setext_h1_underline)与 2 级;
  • 两者对应的开关分别是 heading.atx 与 heading.setext,样例中的 5 个标题走的都是 atx 分支。

随后把配置按级别“摊平”为具体值(L58-L72),list.clamp / list.cycle 意味着多数参数既可以传单个值,也可以传按 H1~H6 索引的数组:

require('render-markdown').setup({
    heading = {
        enabled = true,          -- 总开关
        atx = true, setext = true,
        sign = true,            -- sign 列符号
        -- 按级别循环取值:H1='󰲡 ', H2='󰲣 ', … H6='󰲫 '
        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
        -- 图标如何填充 '#'+1 的空间
        -- | eol     | 隐藏 '#',图标放在最右列 |
        -- | right   | 隐藏 '#',图标附加在右侧 |
        -- | inline  | 隐藏 '#',图标内联在左侧 |
        -- | overlay | 图标左补空格后覆盖,恰好盖住所有 '#' |
        position = 'overlay',
        signs = { '󰫎 ' },
        width = 'full',         -- 'full' 整行背景 | 'block' 仅标题文本宽
        left_margin = 0, left_pad = 0, right_pad = 0,
        min_width = 0,          -- width='block' 时的最小宽度
        border = false,         -- 是否上下加边框('▄'/'▀')
        border_virtual = false,
        border_prefix = false,
        above = '▄', below = '▀',
        backgrounds = { 'RenderMarkdownH1Bg', 'RenderMarkdownH2Bg', 'RenderMarkdownH3Bg',
                        'RenderMarkdownH4Bg', 'RenderMarkdownH5Bg', 'RenderMarkdownH6Bg' },
        foregrounds = { 'RenderMarkdownH1', 'RenderMarkdownH2', 'RenderMarkdownH3',
                        'RenderMarkdownH4', 'RenderMarkdownH5', 'RenderMarkdownH6' },
        custom = {},            -- 按 lua-pattern 匹配标题文本,覆盖 icon/background/foreground
    },
})

样例的渲染结果与该配置一一对应:position = 'overlay' 的默认值让 6 个空格 + 图标恰好覆盖 ######(见 L159-L163 的 str.pad(space) .. icon 覆盖写法),所以测试视图中每个标题行都保持原始列宽不变。custom 参数允许按标题文本匹配(self.node.text:find(custom.pattern),L78-L85)单独改某几个标题的图标与配色。

五、代码块渲染实现拆解(code.lua)

code.lua 处理样例最后的围栏代码块,几个与测试视图直接相关的决策点:

  1. 只处理真正的代码块:self.node:height() <= 2 直接跳过(L29-L31),单行围栏块不属于此渲染器。
  2. 解析 info 字符串:从 info_string 中取出 language 子节点(python),样例里的 {filename="demo.py"} 属于 info 的其余部分,会由 language_info = true(默认)原样渲染在语言名之后,使用 RenderMarkdownCodeInfo 高亮(L154-L160)。
  3. 语言标题栏:language = true(默认)时,用图标提供方取 python 图标(测试视图中的第二个 󰌠),拼成 language_left + 图标 + 语言名 + info + language_right,再用 language_border = '█'(默认值)填充到块宽;position = 'left'(默认)决定填充方向(L177-L186),这正是视图中 {filename="demo.py"} 后面一长串 █ 的来源。
  4. 边框 border = 'hide'(默认):上下围栏行(```)整行 conceal(L210-L212),视觉上由语言标题栏“代替”上围栏;若语言渲染被关闭(如 disable = { 'python' }),则回退渲染 above/below 边框。
  5. 背景:width = 'full'(默认)使 RenderMarkdownCode 背景铺满整行(hl_eol),background_inset = 1 让首尾各留一行不铺背景——对应测试中 for _ = 14, 22 do 只对正文行断言背景。disable_background = { 'diff' } 是内置例外:diff 块自带背景高亮。

对应的可调配置(摘自 settings.lua 默认值):

require('render-markdown').setup({
    code = {
        enabled = true, sign = true,
        conceal_delimiters = true,   -- 隐藏上下围栏
        language = true, position = 'left',  -- left | center | right
        language_icon = true, language_name = true, language_info = true,
        disable = {},                 -- 按语言名禁用渲染
        disable_background = { 'diff' },
        background_inset = 1,         -- 首尾各留空行数
        width = 'full',              -- full | block
        left_margin = 0, left_pad = 0, right_pad = 0, min_width = 0,
        border = 'hide',             -- hide | thin | thick | none
        language_border = '█', above = '▄', below = '▀',
        highlight = 'RenderMarkdownCode',
        highlight_info = 'RenderMarkdownCodeInfo',
        highlight_border = 'RenderMarkdownCodeBorder',
        style = 'full',              -- full | normal | language | none 的预设组合
    },
})

六、图片元素与编辑体验

Image 在 link.lua 的 image 分支中处理:图标取自 link 配置(测试视图中呈现为 󰥶),链接文本 Image 保持可见,example.png 不存在也不会报错——渲染只依赖语法树节点,不校验资源。

编辑体验上还有两点值得知道:

  • anti-conceal:默认 anti_conceal.enabled = true,光标所在行的虚拟文本会被临时隐藏,保证编辑标题 # 或围栏 ``` 时看到的是真实字符而非图标;:RenderMarkdown expand / :RenderMarkdown contract 可以调节光标上下仍显示渲染效果的范围(settings.lua)。
  • 模式感知:各渲染器都继承 render_modes 配置(默认 false,即除插入模式外的所有模式渲染)。演示 GIF 中 Type "i" 进入插入模式截图 default.png、Escape 返回普通模式截图 rendered.png 的对照设计,正是利用了这一点。

七、验证路径与延伸阅读

  • 运行单测验证样例渲染:just test(底层是 nvim --headless -u tests/minimal_init.lua 执行 busted,见 justfile),其中 tests/demo/heading_code_spec.lua 即本文第三节所述断言;
  • 健康检查:just health 对应 nvim -c "checkhealth render-markdown",可用于核对 parser 与图标提供方是否就绪;
  • 开关渲染::RenderMarkdown toggle / :RenderMarkdown buf_toggle,调试用 :RenderMarkdown debug 查看当前行的 mark 信息;
  • 深入源码:标题 heading.lua、代码块 code.lua、链接 link.lua、配置默认值 settings.lua、最小演示环境 demo/minit.lua。

demo/heading_code.md 用 23 行样例把“标题分级配色、语言标题栏、围栏隐藏、背景宽度、sign 列符号”这些默认配置的效果一次性钉死在测试里——这正是本仓库“配置默认值 → 渲染器实现 → 演示样例 → 测试断言”四层保持一致性的典型样本。

登录后查看全文
markdown.nvim