VS Code中Quarto数学环境折叠与大纲显示异常问题求助

开发者阿泽

2026-6-12

解决Quarto在VS Code中折叠与大纲混乱的问题

问题背景

在Quarto中使用带二级标题（##）的自定义div块时，编译正常，但VS Code的编辑器折叠和大纲导航会完全混乱，大文件里根本没法正常导航。示例代码：

::: {#def-system}
## Example title
This is a definition
:::

可行解决思路

替换标题语法，避免编辑器识别为章节标题
不用Markdown的##语法，改用加粗文本模拟标题，再通过Quarto样式定义让它显示成标题效果。示例：
```
::: {#def-system .custom-def}
**Example title**
This is a definition
:::
```
然后在_quarto.yml或自定义CSS里添加样式：
```
.custom-def strong {
  font-size: 1.25em;
  font-weight: bold;
  margin: 1em 0 0.5em;
  display: block;
}
```
这样编辑器不会把加粗文本当成章节标题，大纲和折叠就不会乱，编译后也能显示出标题样式。
用Quarto内置的带标题环境语法
Quarto支持给自定义div添加title属性，编译时会自动渲染成标题，编辑器里不会出现##，也就不会干扰大纲。示例：
```
::: {#def-system .definition title="Example title"}
This is a definition
:::
```
同样可以通过CSS调整这个标题的样式，确保显示效果符合需求。
调整VS Code的大纲识别规则
在VS Code的settings.json里修改Markdown大纲的识别逻辑，让它忽略div块内的二级标题。添加以下配置：
```
"markdown.outline.customHeadings": [
  {
    "level": 2,
    "pattern": "^##(?!.*:::).*$"
  }
]
```
这个正则会让编辑器只识别不在:::块开头的##作为二级标题，可根据你的文件结构微调正则匹配范围。
改用Raw HTML标题
用HTML的<h2>标签代替Markdown的##，VS Code的Markdown大纲通常不会把HTML标题纳入章节大纲，也就不会打乱折叠。示例：
```
::: {#def-system}
<h2>Example title</h2>
This is a definition
:::
```
Quarto编译时会正常渲染这个HTML标题，显示效果和##一致，但编辑器的大纲不会受影响。