_quarto.yml配置中number-depth参数失效问题咨询

问题重现 #

配置_quarto.yml时，已在sidebar中设置number-depth: 3，但生成的网站侧边栏仅展示顶级章节（如Introduction、Methods）及对应.qmd文件，文件内的子章节完全不显示，number-depth参数未生效。

用户配置代码如下：

project:
  type: website

website:
  title: "Patatin Patatan"
  
  navbar:
    logo: "HSILab.png"
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - citation.qmd
  sidebar:
    logo: "HSILab.png"
    style: "docked"
    search: true
    number-sections: true
    number-depth: 3
    contents:
      - section: "Introduction"
        contents:
          - 00_Abstract.qmd
          - 01_Approach.qmd
      - section: "Methods"
        contents:
          - 02_Methods.qmd
      - section: "Results VISNIR"
        contents:
          - 03_Quality.qmd
          - 04_ImageSequences.qmd
          - 05_IQMosaics.qmd
          - _051_SimpleReferencing.qmd
          - _052_ImageStitching.qmd
      - section: "Results SWIR"
        contents:
          - 06_SWIR.qmd
      - section: "Conclusions"
        contents:
          - 07_Conclusions.qmd
format:
  html:
    theme: default
    css: styles.css
    toc: false
    toc-location: right
    code-fold: true
    code-summary: "code"
    page-layout: full
    smooth-scroll: true
    anchor-sections: true

editor: visual

生成的侧边栏效果：仅展示各顶级section及下属.qmd文件条目，无任何子章节展开。

问题原因 #

当你在sidebar.contents中手动定义了section和文件的层级结构时，Quarto会完全遵循你指定的结构渲染侧边栏，number-depth参数只会影响章节编号的深度，不会自动解析并添加.qmd文件内部的子章节到侧边栏中。

解决办法 #

方法1：自动生成侧边栏目录（推荐） #

如果你不需要自定义侧边栏结构，希望自动包含所有层级的章节，将contents设置为auto即可，Quarto会自动扫描所有.qmd文件的章节结构，并按照number-depth的设置展示对应层级：

website:
  # 保留其他配置不变
  sidebar:
    logo: "HSILab.png"
    style: "docked"
    search: true
    number-sections: true
    number-depth: 3
    contents: auto  # 替换手动定义的contents为auto

方法2：手动添加子章节（自定义结构场景） #

若需保留手动定义的section结构，同时展示文件内的子章节，需在对应的.qmd条目下嵌套contents，手动列出子章节的标题或锚点：

- section: "Results VISNIR"
  contents:
    - 03_Quality.qmd
    - 04_ImageSequences.qmd
    - 05_IQMosaics.qmd
      contents:
        - "# Simple Referencing"  # 对应文件内的## Simple Referencing标题
        - "# Image Stitching"     # 对应文件内的## Image Stitching标题
    - _051_SimpleReferencing.qmd
    - _052_ImageStitching.qmd

也可以使用锚点格式（标题的slug形式），比如：

- 05_IQMosaics.qmd
  contents:
    - 05_IQMosaics.qmd#simple-referencing
    - 05_IQMosaics.qmd#image-stitching

额外检查 #

确保你的.qmd文件内使用了正确的标题层级标记（##表示二级章节，###表示三级章节），这样number-depth:3才能正确识别并展示到三级标题。

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