Quarto博客目录(TOC)无法正常显示问题求助

核心问题 #

配置toc: true后页面左侧预留了目录空间，但实际无目录内容显示，尝试了单篇文章YAML、全局_quarto.yml的不同层级配置，以及standalone参数调整均未解决。

排查与解决步骤 #

• 检查文章标题层级：Quarto的TOC仅识别二级及以上标题（即##、###开头的Markdown标题），如果文章只有最高层级的#标题，不会生成任何目录项。先确认你的文章内容里包含足够的层级标题。

• 修正toc配置位置：
  toc是HTML格式的专属配置，必须放在format.html节点下，根层级的toc: true不会生效：

  • 单篇文章正确配置示例：

    title: "Dependency management with renv R package"
    date: "2022-10-29"
    categories: [R, Dependency management]
    image: renv_thumbnail.png
    format:
      html:
        toc: true
        toc-depth: 3 # 可选，控制TOC显示的标题层级深度，默认是3
        fontsize: 0.9em
        code-tools: true
    comments: 
        utterances: 
          repo:  my_repo
          theme: photon-dark
    title-block-banner: false
    editor: visual
    

  • 全局_quarto.yml正确配置示例：

    project:
      type: website
    format:
      html:
        toc: true
        toc-depth: 3
        # 其他全局HTML配置
    

  注意：博客站点不需要设置standalone: true，该参数是针对单文档的，会破坏博客的多页面结构，直接去掉即可。

• 局部清理缓存（避免全量重建）：
  不用删除整个缓存文件夹，只需要清理单篇文章的缓存：

  1. 找到站点根目录下的_freeze文件夹，定位到对应文章的子目录并删除
  2. 单独渲染该文章：quarto render path/to/your/post.qmd
     或者直接禁用临时冻结渲染单篇：quarto render path/to/your/post.qmd --no-freeze，这样不会影响其他已渲染的文章。

• 升级Quarto版本：旧版本可能存在TOC渲染的bug，运行quarto check查看当前版本，执行quarto upgrade升级到最新稳定版后重试。

• 排查主题冲突：如果使用了自定义主题或第三方主题，可能会通过CSS隐藏了TOC元素。可以临时注释掉主题配置，切换回Quarto默认主题，重新渲染验证是否显示TOC。

内容的提问来源于stack exchange，提问作者Bezzus