render-markdown.nvim:以 demo/heading_code.md 为例,逐层拆解标题、图片与代码块的渲染实现
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` 分支把 `[ | 解析 `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 的工作流分两步:
-
生成 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 渲染效果”的对照图。 -
最小运行配置: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_inlineparser 是必需的(渲染全部基于语法树节点),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 处理样例最后的围栏代码块,几个与测试视图直接相关的决策点:
- 只处理真正的代码块:
self.node:height() <= 2直接跳过(L29-L31),单行围栏块不属于此渲染器。 - 解析 info 字符串:从
info_string中取出language子节点(python),样例里的{filename="demo.py"}属于info的其余部分,会由language_info = true(默认)原样渲染在语言名之后,使用RenderMarkdownCodeInfo高亮(L154-L160)。 - 语言标题栏:
language = true(默认)时,用图标提供方取python图标(测试视图中的第二个),拼成language_left + 图标 + 语言名 + info + language_right,再用language_border = '█'(默认值)填充到块宽;position = 'left'(默认)决定填充方向(L177-L186),这正是视图中{filename="demo.py"}后面一长串█的来源。 - 边框
border = 'hide'(默认):上下围栏行(```)整行 conceal(L210-L212),视觉上由语言标题栏“代替”上围栏;若语言渲染被关闭(如disable = { 'python' }),则回退渲染above/below边框。 - 背景:
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 列符号”这些默认配置的效果一次性钉死在测试里——这正是本仓库“配置默认值 → 渲染器实现 → 演示样例 → 测试断言”四层保持一致性的典型样本。