Quarto学习笔记
第一章：.qmd
.qmd 是 Quarto 系统的源文件格式（全称 Quarto Markdown）。
你可以把它理解为一种“包含了代码执行指令的 Markdown 文件”。它的核心逻辑是：“内容即代码，代码即结果”。
以下是 .qmd 文件的三个主要组成部分：
1. YAML 头部 (YAML Header)
这是文件的“元数据”区域，位于文件最上方，用 --- 包裹。它定义了文档的全局设置。
示例：
yaml
---
title: "我的数据分析报告"
author: "姓名"
format: html
---
这里指定了文档的标题、作者以及希望导出的格式（如 HTML、PDF 等）。
2. Markdown 正文 (Text)
这是你编写文字说明的部分，使用标准的 Markdown 语法（如 # 标题，**粗体**，[链接](url)）。你可以利用 Markdown 轻松地进行排版，而无需像 Word 那样频繁点击菜单调整格式。
3. 代码块 (Code Chunks)
这是 .qmd 的灵魂所在。你可以在特定的标记区域内插入代码。当你点击“渲染”（Render）时，Quarto 会调用相应的引擎（如 Python 的 Jupyter 或 R 的 Knitr）运行这些代码。
语法示例：
```{python}
#| label: fig-example
#| fig-cap: "这是一张示例图"
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [4, 5, 6])
plt.show()
* '#|'开头的行是**cell options**（单元格选项），可以控制代码块是否显示、图片大小、绘图标题等
为什么要使用 .qmd？
- 数据驱动：如果你的数据更新了，你只需要修改源数据文件，然后重新渲染一遍 .qmd，文档中的所有图表和计算数据就会自动更新。你不再需要手动把图表截图粘贴到 Word 里。
- 版本控制友好：由于 .qmd 本质上是纯文本文件，它非常适合使用 Git 进行版本控制。你可以清晰地看到文档在哪个版本修改了代码或文字。
- 跨语言集成：一个 .qmd 文件中甚至可以混合使用不同的代码块，比如一段处理数据的 R 代码，配合一段生成图表的 Python 代码。
与其他格式的对比
- .md (Markdown)：只能写纯文字和排版，无法运行代码，也无法在生成时自动计算图表。
- .ipynb (Jupyter Notebook)：.qmd 也可以作为 Jupyter Notebook 的一种替代方案。相比 .ipynb，.qmd 是更纯粹的文本文件，更适合写正式论文、书籍或复杂的报告，且处理长文档的排版能力更强。
总的来说，.qmd 是 Quarto 系统的“创作底稿”，它将文档的撰写、数据的分析和最终的排版整合在了一个文件中。
第二章：markdown语法
Markdown 是一种轻量级标记语言，它的核心目标是：易读、易写、易于转换为其他格式（如 HTML、PDF 等）。
在 Quarto (.qmd) 中，你撰写正文时使用的就是 Markdown。以下是日常写作中最常用的语法速查：
1. 标题 (Headings)
使用 # 符号，数量代表层级（1-6 级）。
# 一级标题
## 二级标题
### 三级标题
2. 文本格式 (Text Styles)
**加粗文本** 或 __加粗文本__
*斜体文本* 或 _斜体文本_
***粗斜体文本***
superscript^2^ / subscript~2~ 上标2/ 下标2
~~删除线~~
`行内代码`
3. 列表 (Lists)
你可以自由选择使用 -、+ 或 * 中的任何一个来创建列表。它们最终渲染出来的效果通常都是一样的（即一个圆点列表）
* unordered list
+ sub-item 1
+ sub-item 2
- sub-sub-item 1
* 无序列表项 1
* 无序列表项 2
* 子项
- 顶级项目
- 子项目 A
- 子项目 B
1. 有序列表项 1
2. 有序列表项 2
- [x] 已完成的任务
- [ ] 待办事项
- [ ] 另一个待办事项
4. 链接与图片 (Links & Images)
<https://quarto.org>
[链接文字](https://example.com)
示例：[Markdown Basics](./markdown-basics.qmd)
示例：[{fig-alt="Alt text"}](https://quarto.org)
5. 引用 (Blockquotes)
使用 > 符号。
> 这是引用的内容。
> 它可以跨越多行。
6. 代码块 (Code Blocks)
这是在 Quarto 中最重要的一部分，通过三个反引号（```）创建。
普通代码块：
```python
print("Hello World")
```
```{.python filename="run.py"}
code
```
Quarto 代码执行块（带 Cell Options）：
```{python}
#| label: my-plot
#| fig-cap: "这是一张图"
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
7. 表格 (Tables)
| 列标题 1 | 列标题 2 |
| :--- | :--- |
| 内容 1 | 内容 2 |
| 内容 3 | 内容 4 |
(注：:--- 代表左对齐，:---: 居中，---: 右对齐)
示例：
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1. | 1 | 1 |
8. 分割线与换行
分割线：使用三个短横线 ---。
强制换行：在行尾加上两个空格，或者使用 <br>。
给你的专业建议（基于你的使用习惯）：
考虑到你经常使用 Excel 进行数据建模和制作图表，在编写 .qmd 时，Markdown 的这些语法会非常高效：
- 交叉引用：在 Markdown 中写 See @fig-my-plot，Quarto 会自动生成“查看图 1”的超链接，且如果图表顺序变动，编号会自动更新。
- 调用框 (Callouts)：这是 Quarto 特有的 Markdown 扩展，非常适合强调分析结果：
::: {.callout-note}
这是一个提示框，用于强调结论。
:::
Quarto 内置了五种类型：
.callout-note (提示)
.callout-warning (警告)
.callout-important (重要)
.callout-tip (技巧)
.callout-caution (小心)
第三章：分区divs
在 Quarto 中，::: 被称为 Divs（分区容器），它是 Quarto 对 Markdown 语法最强大的扩展之一。
你可以把它理解为给一段文字、代码或图表加一个“容器（Box）”，从而可以对这个容器整体应用特殊的样式、颜色或功能。
1. 基本语法结构
容器必须由 ::: 开始，并由 ::: 结束。
::: {.my-class}
这里的内容会被包裹在一个带有 `my-class` CSS 类的 `<div>` 标签中。
:::
2. 高级排版：分栏布局 (Layout)
你可以使用 ::: {.column-xxx} 来实现多栏排版，这在制作汇报展示（如 Reveal.js 幻灯片）或精美的 HTML 报告时非常有用。
代码：
:::: {.columns}
::: {.column width="50%"}
左侧内容：IVE 品牌代言数据分析。
:::
::: {.column width="50%"}
右侧内容：Miu Miu 与 Balmain 市场占有率对比图。
:::
::::
3. 自定义样式 (CSS 封装)
如果你熟悉 CSS，你可以用它来创建自定义的模块。例如，你想让一段文字背景变为浅灰色且带有圆角：
::: {style="background-color: #f0f0f0; padding: 20px; border-radius: 5px;"}
这里是重要的补充说明。
:::