Markview.nvim 中实现 Markdown 列表折叠的技术方案

背景与需求分析

在 Neovim 生态中，Markview.nvim 正逐渐成为默认的 Markdown 插件。许多用户在使用过程中发现，传统的 Treesitter 对 Markdown 列表项的折叠支持存在缺陷，特别是当需要嵌套折叠子列表时（如仅折叠第三级列表而保持上级展开），原生方案往往无法满足需求。

核心解决方案

基础折叠配置

通过以下 Lua 配置可启用 Treesitter 的基础折叠功能：

vim.o.foldmethod = "expr"
vim.o.foldexpr = "v:lua.vim.treesitter.foldexpr()"
vim.o.foldtext = ""  -- 可选：清除折叠占位文本

建议将配置放置在 after/ftplugin/markdown.lua 文件中实现文件类型专属配置。

高级列表折叠控制

要实现精准的嵌套列表折叠，需要创建 Treesitter 查询文件。在指定路径创建 folds.scm 文件并写入以下 S-expression 语法：

((list) @fold
  (#offset! 0 0 -1 0))

这个查询规则实现了：

1. 识别所有列表结构作为折叠单元
2. 通过 offset 调整精确控制折叠范围
3. 支持多级列表的独立折叠操作

实际效果展示

配置生效后可实现：

• 任意层级列表的独立折叠
• 保持父级列表展开状态下折叠子项
• 折叠后显示原始行内容（非默认摘要文本）

典型工作场景示例：

1. 编写多级任务列表时折叠已完成条目
2. 大纲模式下折叠深层嵌套的论点
3. 代码文档中折叠参数说明列表

技术原理剖析

该方案的核心在于 Treesitter 的查询机制：

1. @fold 标签声明可折叠节点
2. #offset! 指令微调折叠范围
3. 与 Neovim 原生折叠系统的无缝集成

相比传统正则表达式折叠方案，Treesitter 方案具有：

• 精确的语法感知能力
• 无视缩进格式的稳定性
• 更好的性能表现

注意事项

1. 确保已安装最新版 nvim-treesitter
2. 不同 Markdown 解析器可能需要调整查询语法
3. 可通过 foldlevel 参数控制初始折叠状态

此方案已在 Markview.nvim 生态中验证可用，为 Markdown 文档编辑提供了专业级的结构化管理能力。