如何正确编译带嵌套文件夹结构的Quarto网站？

子目录下的博客列表页渲染异常是手动为Quarto Website项目添加博客板块时的常见问题，核心诱因有两点：

• 旧版Quarto（RStudio Server 2022.02内置版本为1.0正式版早期构建）对嵌套目录下的listing列表路径解析存在兼容缺陷，且默认列表排序依赖文章日期字段，缺失字段会直接导致列表页渲染中断
• 首次新增子目录板块时未清理历史渲染缓存，旧的路径映射规则残留，导致子页面资源加载错位

• 清理历史渲染缓存
  关闭所有已打开的qmd编辑标签，删除项目根目录下的_site输出文件夹、.quarto缓存文件夹，两类文件夹均为Quarto自动生成，删除不会丢失任何源文件。
• 修正博客列表页配置
  替换blog/index.qmd的全部内容，通过./明确相对路径基准，避免Quarto错误从项目根目录解析posts路径，配置如下：

  ---
  title: This is my blog.
  listing:
    contents: ./posts
    type: default
    sort: "date desc"
    fields: [title, date, image]
  ---
  

• 补全博客文章必填元数据
  旧版Quarto默认列表按日期排序，缺失date字段会触发渲染错误，修改blog/posts/test-post/index.qmd内容如下，不要留空正文：

  ---
  title: My first blog post.
  date: 2024-01-01
  image: featured.jpg
  ---
  这是第一篇测试博客的正文内容，可自行替换为实际文本。
  

• 完善全局渲染规则
  在_quarto.yml的project配置块中新增显式渲染规则，明确要求Quarto渲染blog目录下所有层级的qmd文件，避免漏渲染，完整配置如下：

  project:
    type: website
    render: ["*.qmd", "blog/**/*.qmd"]
  
  website:
    title: "test-quarto-web"
    navbar:
      background: primary
      left:
        - href: index.qmd
          text: Home
        - about.qmd
        - href: blog/index.qmd
          text: Blog
  
  format:
    html:
      theme: cosmo
      css: styles.css
  
  editor: visual
  

• 全量重渲染网站
  不要使用增量渲染按钮，直接在R控制台运行以下命令完成全量渲染：

  quarto::quarto_render()
  

  渲染完成后通过RStudio Build面板的预览按钮打开网站，不要直接访问本地缓存的旧页面。

• 渲染完成后检查_site/blog/posts/test-post路径下，是否存在生成的index.html文件和拷贝过去的featured.jpg资源
• 点击导航栏Blog菜单可正常打开博客列表页，显示测试文章卡片，特色图加载正常
• 点击文章卡片可正常进入详情页，无路径跳转错误
• 如果按照上述步骤操作后仍存在异常，将RStudio内置Quarto版本升级至1.2及以上即可，2022.02版本内置的Quarto对listing功能的支持存在已知bug。

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