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)

![图片说明](path/to/image.png)

示例：[![](elephant.png){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;"}
这里是重要的补充说明。
:::

Quarto学习笔记