VSCode Markdown扩展：如何从目录中跳过主标题

VSCode Markdown扩展：如何从目录中跳过主标题

vscode-markdown Markdown All in One 项目地址: https://gitcode.com/gh_mirrors/vs/vscode-markdown

在编写Markdown文档时，文档结构通常包含一个主标题（#级标题）作为整个文档的标题，后跟多个次级标题（##级及以下）作为章节划分。然而，当使用VSCode的Markdown扩展自动生成目录时，主标题默认会被包含在目录中，这可能导致目录结构显得冗余。

问题背景

许多Markdown文档遵循这样的结构规范：

• 单个主标题（#级）作为文档名称
• 多个次级标题（##级）作为章节标题
• 更深层级的标题（###级及以下）作为子章节

这种结构符合markdownlint的MD025规则（禁止同一文档中出现多个顶级标题）的要求。但在自动生成目录时，主标题的包含可能并不理想，因为：

1. 主标题作为文档名称，通常不需要在目录中重复出现
2. 目录的主要作用是导航文档章节，而非重复文档标题

解决方案

VSCode Markdown扩展提供了多种方法来控制目录生成行为：

方法一：使用HTML注释标记

在需要排除的标题前或标题后添加特殊注释：

# 主文档标题 <!-- omit from toc -->

## 第一章
### 1.1节

或者：

<!-- omit from toc -->
# 主文档标题

## 第一章
### 1.1节

这种方法：

• 不会违反markdownlint的MD023规则（标题必须从行首开始）
• 不会触发MD033规则（禁止内联HTML），因为这是特殊注释而非标准HTML标签
• 简单直观，无需修改配置文件

方法二：通过配置文件全局设置

在VSCode的settings.json中添加配置：

"markdown.extension.toc.omittedFromToc": {
  "README.md": [
    "# 主文档标题",
    "## 需要排除的特定章节"
  ]
}

这种方法适合：

• 需要批量排除多个标题的情况
• 需要为特定文件定制目录结构
• 团队项目中保持一致的目录生成规则

方法三：调整目录级别设置

通过toc.levels设置可以控制目录包含的标题层级：

"markdown.extension.toc.levels": "2..6"

这种方法会将#级标题（主标题）排除在目录外，但需要注意：

• 会同时影响所有#级标题
• 如果文档中有多个#级标题（违反MD025规则），都会被排除

最佳实践建议

1. 单一主标题文档：推荐使用方法一，简单直接
2. 复杂文档结构：考虑使用方法二进行精细控制
3. 团队协作项目：使用方法二配置共享设置
4. 多文件管理：结合方法二和方法三实现统一标准

注意事项

1. 使用HTML注释方法时，确保注释与标题在同一行或紧邻标题上方
2. 配置文件修改后需要重启VSCode生效
3. 排除主标题后，建议检查文档的整体导航逻辑是否清晰
4. 在多人协作项目中，应在文档规范中明确目录生成规则

通过合理使用这些方法，可以生成更简洁、专业的文档目录结构，提升文档的可读性和可用性。

vscode-markdown Markdown All in One 项目地址: https://gitcode.com/gh_mirrors/vs/vscode-markdown