编写或迁移 Quarto 文档时：用 QMD 语法…

当用户明确使用 Quarto、.qmd、_quarto.yml、Quarto 项目或从 R Markdown/bookdown/blogdown/xaringan/distill/Jupyter 迁移到 Quarto 时，按任务查参考并遵循 QMD 核心语法。

适用场景

解决思路

1. 写新的 Quarto 文档时：先遵循“QMD Essentials”，再按具体任务查看对应参考文件。
2. 添加交叉引用时：读取 `references/cross-references.md`。
3. 配置代码单元格时：读取 `references/code-cells.md`。
4. 添加带标题的图时：读取 `references/figures.md`。
5. 创建表格时：读取 `references/tables.md`。
6. 添加引用和参考文献时：读取 `references/citations.md`。
7. 添加 callout 块时：读取 `references/callouts.md`。
8. 添加图表（Mermaid、Graphviz）时：读取 `references/diagrams.md`。
9. 控制页面布局时：读取 `references/layout.md`。
10. 使用 shortcodes 时：读取 `references/shortcodes.md`。
11. 添加条件内容时：读取 `references/conditional-content.md`。
12. 使用 divs 和 spans 时：读取 `references/divs-and-spans.md`。
13. 配置 YAML front matter 时：读取 `references/yaml-front-matter.md`。
14. 查找和使用扩展时：读取 `references/extensions.md`。
15. 应用 markdown linting 规则时：读取 `references/markdown-linting.md`。
16. 选择或配置计算引擎（knitr、jupyter、julia）时：读取 `references/engines.md`。
17. 迁移现有项目时：仅在用户明确要求转换/迁移时读取匹配源格式的参考文件；不要在新写 Quarto 文档时读取这些迁移参考。
18. R Markdown（.Rmd）迁移到 Quarto 时：读取 `references/conversion-rmarkdown.md`。
19. bookdown 项目迁移时：读取 `references/conversion-bookdown.md`。
20. xaringan 幻灯片迁移时：读取 `references/conversion-xaringan.md`。
21. distill 文章迁移时：读取 `references/conversion-distill.md`。
22. blogdown 站点迁移时：读取 `references/conversion-blogdown.md`。
23. Jupyter notebook（.ipynb）与 Quarto 互转时：读取 `references/conversion-jupyter.md`。
24. 基本文档结构：Quarto 文档由两部分组成——顶部用 `---` 包裹的 YAML front matter（元数据和配置），以及使用标准 markdown 语法的 Markdown 正文内容。
25. 基本文档模板：在 YAML front matter 中设置 `title`、`author`、`date: today`、`format: html`，然后在下方写正文。
26. Divs：使用三个冒号的围栏语法：`::: {.class-name}` 和结尾 `:::`。
27. Spans：使用方括号语法：`[important text]{.highlight}`。
28. 代码单元格语法：代码单元格以三个反引号和花括号中的语言标识符开始；代码单元格是可执行并产生输出的代码块。
29. 代码单元格选项：Quarto 使用对应语言的注释符号加 `|`；选项使用连字符而不是点（例如 `fig-cap` 而不是 `fig.cap`）。
30. 代码单元格选项注释符：R、Python、Julia 用 `#|`；Mermaid 用 `%%|`；Graphviz/DOT 用 `//|`。
31. 代码单元格选项示例：使用 `#| label: fig-example`、`#| echo: false`、`#| fig-cap: "A scatter plot example."`。
32. 文档级默认执行选项：在 YAML front matter 中用 `execute:` 设置，例如 `echo: false`、`warning: false`。
33. 缓存关键差异：只对 R 代码单元格（knitr 引擎）建议 `#| cache: true`；绝不要对其他语言单元格建议它，因为它不工作且会被静默忽略。
34. 非 knitr 引擎缓存：唯一正确做法是在顶层 YAML front matter 中设置 `execute:` 下的 `cache: true`；Python/Jupyter 需要 `jupyter-cache`（`pip install jupyter-cache`）。
35. 交叉引用标签：标签必须以类型前缀开头，并用 `@` 引用。
36. 图交叉引用：用 `fig-` 前缀，例如 `#| label: fig-plot` → `@fig-plot`。
37. 表交叉引用：用 `tbl-` 前缀，例如 `#| label: tbl-data` → `@tbl-data`。
38. 节交叉引用：用 `sec-` 前缀，例如 `{#sec-intro}` → `@sec-intro`。
39. 公式交叉引用：用 `eq-` 前缀，例如 `{#eq-model}` → `@eq-model`。
40. 交叉引用示例：代码单元格设置 `#| label: fig-plot` 和 `#| fig-cap: "A caption for the plot."`，正文用 `See @fig-plot for the results.` 引用。
41. Callout 类型：五种为 `note`、`warning`、`important`、`tip`、`caution`。
42. Callout 语法：`::: {.callout-note}` ... `:::`；警告可用 `## Custom Title` 添加自定义标题。
43. 图片语法：`{#fig-name fig-alt="Alt text"}`。
44. 子图语法：用 `::: {#fig-group layout-ncol=2}` 包裹多个 `{#fig-sub1}`、`{#fig-sub2}` 等子图，并在组内写主标题。
45. 表格语法：用 `::: {#tbl-example}` 包裹 markdown 表格，并在组内写表标题。
46. 引用语法：正文写 `According to @smith2020, the results show...`；多引用写 `[@smith2020; @jones2021]`。
47. 引用配置：在 YAML 中设置 `bibliography: references.bib` 和 `csl: apa.csl`。
48. 创建 HTML 文档：YAML 设置 `format: html`，可配置 `toc: true`、`code-fold: true`、`theme: cosmo`，并设置 `title`、`author`、`date: today`。
49. 创建 PDF 文档：YAML 设置 `format: pdf`，可配置 `documentclass: article`、`papersize: a4`，并设置 `title`。
50. 创建 RevealJS 演示：YAML 设置 `format: revealjs`，用 `##` 创建幻灯片标题，例如 `## First Slide`、`## Second Slide`。
51. 设置 Quarto 项目：在项目根目录创建 `_quarto.yml`，配置 `project: type: website`、`website: title`、`navbar`（如 `href: index.qmd text: Home`、`href: about.qmd text: About`）、`format: html:` 下的 `theme: cosmo`。
52. 需要更多信息时：查阅 Quarto Documentation、Quarto Guide、Quarto Extensions 和 Community Extensions List（链接见原文）。

适用边界 · 注意事项

• 不要用于一般 R Markdown 或相关格式问题，除非明确提到 Quarto 或迁移到 Quarto。
• 写新的 Quarto 文档时不要读取迁移参考文件；仅在明确要求转换/迁移现有项目时读取对应源格式文件。
• 不要给非 R 代码单元格建议 `#| cache: true`；它不生效且会被静默忽略。