Obsidian.nvim 中代码块隐藏问题的解决方案

问题背景

在使用 Obsidian.nvim 插件进行 Markdown 文档编辑时，许多用户遇到了一个共同的问题：当设置 conceallevel 参数后，代码块的三重反引号（```）会被自动隐藏。虽然这种隐藏效果对于提升文档的整洁度有一定帮助，但对于需要明确显示代码块边界的用户来说，这反而造成了困扰。

技术原理分析

这个问题的根源在于 Neovim 的 treesitter 语法高亮机制。Treesitter 是 Neovim 内置的语法分析工具，它通过特定的查询文件（highlights.scm）来定义不同语法元素的显示方式。对于 Markdown 文件，treesitter 默认会将代码块的边界符号（三重反引号）设置为可隐藏（conceal）状态。

解决方案探索

临时替代方案

有用户提出了一种临时解决方案，通过自定义语法匹配规则，将隐藏的三重反引号替换为其他可见字符：

vim.api.nvim_create_autocmd('VimEnter', {
  callback = function() {
    vim.cmd [[
      augroup MarkdownSyntaxMatch
        autocmd! 
        autocmd FileType markdown syntax match @conceal /```/ conceal cchar=⋯
      augroup END
    ]]
  },
})

这种方法虽然能够显示代码块边界，但存在两个问题：

1. 当代码块指定语言时（如 ```bash），会显示多个替代字符
2. 破坏了 Markdown 原有的语法高亮一致性

根本解决方案

经过深入分析，正确的解决方法是直接修改 treesitter 对 Markdown 代码块的语法高亮定义。我们可以通过以下 Lua 代码覆盖默认设置：

require("vim.treesitter.query").set(
  "markdown",
  "highlights",
  "(fenced_code_block_delimiter) @punctuation.delimiter"
)

这段代码的作用是：

1. 定位到 Markdown 的语法高亮规则
2. 将代码块分隔符（三重反引号）的语法标记为标点符号分隔符
3. 移除原有的隐藏属性

高级配置建议

对于需要更精细控制的用户，可以完全自定义 Markdown 的语法高亮规则。以下是一个完整的配置示例，它不仅解决了代码块隐藏问题，还保留了其他 Markdown 元素的高亮：

require("vim.treesitter.query").set("markdown", "highlights", [[
  ; 保留原有的标题高亮规则
  (setext_heading
    (paragraph) @markup.heading.1
    (setext_h1_underline) @markup.heading.1)

  ; 其他标题规则...

  ; 修改代码块高亮规则
  (fenced_code_block
    (fenced_code_block_delimiter) @punctuation.delimiter)

  (fenced_code_block
    (info_string
      (language) @label))

  ; 保留其他Markdown元素的高亮...
]])

最佳实践

1. 选择性隐藏：如果确实需要隐藏某些元素，可以考虑只对特定场景（如列表标记）使用隐藏功能，而不是全局设置
2. 优先级设置：通过 (#set! priority 90) 可以确保某些重要语法元素的高亮优先级
3. 语法检查：修改后建议使用 :TSHighlightCapturesUnderCursor 命令检查语法高亮效果

总结

Obsidian.nvim 中代码块隐藏问题本质上是 treesitter 语法高亮配置的结果。通过理解 treesitter 的工作原理，我们可以灵活地定制 Markdown 的显示效果，既保持文档的整洁性，又确保必要的语法元素可见。对于大多数用户来说，简单的规则覆盖就能解决问题；而对于高级用户，完全自定义语法高亮规则提供了更大的灵活性。