# 用 Markdown 写作

用熟悉的 Markdown 起草，生成 PDF 或供合作者使用的可编辑文档。

Markdown 很适合研究笔记、报告和早期草稿。Oleafly 为它提供了专用的格式工具栏和基于 Pandoc 的构建路径，源文件在应用之外也能使用。

## 做一份报告

1. 选择 **新建项目 → 使用模板 → Blank Markdown document**。
2. 把项目命名为 **现场笔记**，然后打开 `main.md`。
3. 粘贴下面的示例，然后选择 **重新编译**，或按 **⌘Enter / Ctrl+Enter**。
4. 如果 Oleafly 提示设置所需的引擎，请完成设置后再次编译。

```markdown title="main.md"
---
title: "Field notes"
author: "Alex Chen"
date: ""
---

# Question

Does the revised procedure reduce measurement time?

## Method

1. Prepare the sample.
2. Repeat the measurement three times.
3. Record the elapsed time.

## Observations

| Run | Time (s) | Note |
| --- | --- | --- |
| 1 | 12 | First pass |
| 2 | 10 | Repeated pass |

The **mean time** will be compared with the baseline.
```

PDF 中应该包含标题、各级标题、有序列表和表格。第一对 `---` 之间的元数据控制文档的标题和作者。

## 文档类型

在 front matter 中加一行 `type`，就可以把文档构建成报告、图书、幻灯片、海报、信函或简历。没有 `type`，或者值是 Oleafly 不认识的，文档就会构建成文章。

| `type` | 构建成什么 | 你没有设置时自动填入 |
| --- | --- | --- |
| `article` | 文章 | 无 |
| `report` 或 `thesis` | 报告，每个 `#` 标题开始一章 | `documentclass: report` |
| `book` | 图书，每个 `#` 标题开始一章 | `documentclass: book` |
| `slides` | 16:9 的 Beamer 幻灯片。`#` 标题开始一个章节，`##` 标题开始一张幻灯片 | `aspectratio: 169` |
| `poster` | 单页 Beamer 海报，顶部是它的 `title`、`subtitle`、`author` 和 `institute` | A0 纸张，竖向 |
| `letter` | 带有你的地址和收信人地址、主题行、称呼和结束语的信函 | `documentclass: scrlttr2` |
| `cv` | 紧凑的文章 | `geometry: margin=2cm` 和 `pagestyle: empty` |

你自己写的 front matter 优先。你自己设置的值，例如 `documentclass`、`aspectratio` 或 `geometry`，会取代类型自动填入的值。

对于幻灯片，用 `slide-level` 选择由哪一级标题开始一张幻灯片。设为 `slide-level: 1` 时，每个 `#` 标题都开始一张。幻灯片会构建成普通的 PDF，所以预览工具栏上的**放映**可以展示它们。参见[放映幻灯片](/docs/present-slides/)。

海报默认是 A0，除非你把 `papersize` 设为 `a1`、`a2`、`a3` 或 `a4`。其他尺寸，例如 `letter` 或 `a5`，会被忽略。加上 `orientation: landscape` 可得到横向的海报。

信函的收信人地址取自 `to`，你的地址取自 `from`。`opening` 是称呼，`closing` 是你的名字之前的那一行，名字来自 `author`。`subject` 成为主题行，没有 `subject` 时则使用 `title`。地址写成列表，每项一行。

```markdown title="main.md"
---
type: letter
author: "Alex Chen"
from:
  - "Department of Physics"
  - "1 University Road"
to:
  - "Dr. Sam Lee"
  - "Editorial Office"
subject: "Revised manuscript"
opening: "Dear Dr. Lee,"
closing: "Yours sincerely,"
---

Thank you for the reviewers' comments. The revised manuscript answers each one.
```

[文档设置](/docs/document-settings/#markdown)中的**文档类型**会替你写下 `type` 这一行。[LaTeX 导出](/docs/export/#what-each-format-keeps)同样遵循这个类型，幻灯片的 [PowerPoint 导出](/docs/export/#presentation-and-book-exports)使用同一个 `slide-level`。[`oleafly build`](/docs/cli/#build-a-project)会按应用的方式构建每一种类型。

## 源码与可视化编辑

工具栏开头的切换开关有三种模式。**代码** 直接编辑 Markdown。**可视化** 为标题、段落、列表、链接、图片和表格提供格式化编辑。**两者** 同时显示源码和格式化后的文字。打开它的菜单可以选择 **上下** 或 **分屏**。新项目默认以代码模式打开，每个项目会记住你离开时所处的模式。

下划线、高亮、上标和下标是代码模式下的 Pandoc 格式控件。它们的按钮在可视化模式下是隐藏的。处理元数据、引用语法或其他源码结构时，请使用代码模式。

[下载示例源码](/examples/writing-example.md)

## 每一个工具栏工具

点击格式控件之前先选中文字。在代码模式下，大多数工具会包裹所选内容或插入占位符。打开 **更多格式选项**（`…`），可以使用栏里放不下的控件。

### 代码 / 可视化

在 **代码**、**可视化** 和 **两者** 之间切换。无论哪种模式，文档始终是 Markdown 源码。

### 撤销

撤销上一次编辑。⌘Z / Ctrl+Z。

### 重做

恢复被撤销的编辑。**⌘Shift+Z / Ctrl+Shift+Z**。

### 标题 → 标题

从标题菜单中选择 **标题**，插入 `# Title`。把标题文字替换成你自己的标题。

### 标题 → 章节

从标题菜单中选择 **章节**，插入 `## Section`。把标题文字替换成你自己的标题。

### 标题 → 小节

从标题菜单中选择 **小节**，插入 `### Subsection`。把标题文字替换成你自己的标题。

### 标题 → 子小节

从标题菜单中选择 **子小节**，插入 `#### Subsubsection`。把标题文字替换成你自己的标题。

### 标题 → 小标题

从标题菜单中选择 **小标题**，插入 `##### Minor heading`。把标题文字替换成你自己的标题。

### 标题 → 段落标题

从标题菜单中选择 **段落标题**，插入 `###### Paragraph heading`。把标题文字替换成你自己的标题。

### 无序列表

开始一个无序列表。`- Item`。

### 有序列表

开始一个有序序列。`1. Item`。

### 任务列表

在代码模式下，添加一个任务，完成时把 `[ ]` 改为 `[x]`。`- [ ] Task`。

### 引用块

把引文单独放在一行。`> quoted text`。

### 加粗

强调选中的文字。`**text**`；⌘B / Ctrl+B。

### 斜体

强调一个术语。`*text*`；⌘I / Ctrl+I。

### 删除线

把文字标记为已被取代。`~~text~~`。

### 行内代码

格式化文件名、命令或标识符。用反引号括起来的文字。

### 下划线

在代码模式下选中一个短语。`[text]{.underline}`。

### 高亮

在代码模式下选中一个短语。`[text]{.mark}`。

### 上标

在代码模式下选中指数。`^text^`。

### 下标

在代码模式下选中下标。`~text~`。

下划线和高亮使用 Pandoc 属性，因此格式能够进入 PDF。请使用这些控件，而不要在稿件中添加原始 HTML 标签。

### 插入链接

在 **代码** 模式下：插入 `[link text](url)`。替换这两个占位符。

在 **可视化** 模式下：打开 **链接 URL**。输入地址并应用到你的选区。用 **移除链接** 可以保留文字而去掉链接。

### 插入图像

在 **代码** 模式下：插入 `![caption](image-filename)`。替换路径和图注。

在 **可视化** 模式下：打开 **图片文件**。输入项目路径，例如 `figures/plot.png`，然后应用。

PNG、JPG、PDF、SVG、GIF、WebP 和 BMP 图片都可以放进 PDF。编译时，Oleafly 会为你转换 SVG、GIF 和 WebP。TIFF、AVIF、HEIC 和 JPEG XL 图片无法放入：编译会停止并指出该文件，请把它另存为其他格式后再编译。如果转换失败，请检查图片能否打开，或将其另存为 PNG 或 PDF。

### 插入表格

在 **代码** 模式下：插入三列、一个表头和两行数据。替换列名和单元格。

在 **可视化** 模式下：插入同样起始尺寸的可编辑表格。

### 绘制图表

以 Mermaid 模式打开[图表编排器](/docs/figures-diagrams/)。在画布上绘制流程图，或编辑 Mermaid 代码，然后选择 **以 Mermaid 插入**，把它作为带围栏的 `mermaid` 代码块添加到光标处。参见 [Mermaid 图表](#mermaid-diagrams)。

### 文档分析

按源码顺序列出文档的标题、图片、表格、公式、标签、引用和待办事项，每一项都链接到所在的行。它还会从前置元数据中读取标题、作者、关键词、日期和摘要，并可以复制它们用于投稿表单。参见[文档分析](/docs/document-insights/)。

### 文档设置

更改文档类型、文档类、页面大小、分栏、页边距、正文字体、字号、语言、行距和章节编号。Oleafly 会把你的选择写入 Pandoc 读取的 YAML 前置元数据；如果文件没有前置元数据块，就会添加一个。参见[文档设置](/docs/document-settings/#markdown)。

### 项目信息

在 **代码** 模式下：显示项目统计和所选内容的信息。

在 **可视化** 模式下：显示可视化编辑区的统计。

### 查找

在 **代码** 模式下：用 ⌘F / Ctrl+F 打开当前文件的搜索。

在 **可视化** 模式下：源码工具栏的查找按钮是隐藏的。

引用图片之前，先通过文件树导入它。让图片路径相对于稿件，这样源码压缩包在另一台电脑上也能使用。

![在源码和可视化视图中编辑 Markdown 实验记录本，表格和待办清单始终保持同步。](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## 公式和代码块

把行内公式写成 `$x^2$`。把行间公式放在两对美元符号之间：

```markdown
$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$
```

对于代码示例，用三个反引号括起代码，并把语言名放在起始围栏之后。这些都是源码结构；Markdown 工具栏没有单独的公式或围栏代码块按钮。

在可视化模式下，围栏块仍是代码块，并保留它的语言和空行，所以 Mermaid 图表不会丢失。输入三个反引号可以开始一个新的块，在块内按 Tab 可以缩进。

## Mermaid 图表

选择工具栏上的 **绘制图表**，在图表编排器中制作 Mermaid 流程图。**以 Mermaid 插入** 会把它作为围栏代码块添加：

````markdown
```mermaid
flowchart LR
  A[Sample] --> B[Measure]
```
````

在 **两者** 模式下，格式化的一侧会把该代码块绘制成图表。PDF 需要图片，所以编排器还会把渲染好的 PNG 保存到 `figures/mermaid-<hash>.png`，编译时会用这张图片替换该代码块。因此图表也会出现在编译后的 PDF 中，也会出现在 Word、HTML、EPUB 和 PowerPoint 导出中。如果之后你手动编辑了该代码块，PDF 会显示代码，直到你再次从编排器插入或保存该图表。参见 [Markdown 文档中的 Mermaid](/docs/figures-diagrams/#mermaid-in-markdown-documents)。

## 其他语言的文本

Oleafly 会为文档中出现的文字选择字体，所以韩文、日文、中文、阿拉伯文、希伯来文、希腊文、西里尔文、天城文、泰文和其他几种文字无需任何设置就能正常显示。符号和表情符号也有字体，其中表情符号是黑白的。主要用阿拉伯文或希伯来文写成的文档，会从右向左排版。

汉字同时出现在中文和日文文本中，所以请在前置元数据中设置 `lang` 以得到正确的字体：日文用 `ja`，简体中文用 `zh`，繁体中文用 `zh-TW`，韩文用 `ko`。没有 `lang` 时，Oleafly 按文本判断：有假名就是日文，有谚文就是韩文。

```markdown title="main.md"
---
title: "実験ノート"
lang: ja
---
```

你自己选择的字体优先。当前置元数据设置了 `mainfont` 或 `CJKmainfont`，或 `header-includes` 设置了字体时，Oleafly 不会动那一部分。

### PDF 中缺失的字符

当所用字体都没有某个字符时，PDF 仍会构建，只是不含该字符，编译会显示一条警告，附上缺失字符的示例。修复方法：

- 对于韩文、中文或日文文本，请在前置元数据中把 `CJKmainfont` 设为你电脑上已安装、且包含这些字符的字体。
- 对于其他文本，用同样的方式设置 `mainfont`。[文档设置](/docs/document-settings/#markdown)中的**正文字体**会替你写入。
- 对于罕见的符号，请改用图片。

## 引用与参考文献

导入或创建 `references.bib`，把 `bibliography: references.bib` 添加到 YAML 元数据中，并用 `[@citation-key]` 引用已有的键。Pandoc 会利用该参考文献生成格式化的引用和参考文献列表。

如果前置元数据没有指定参考文献，或指定的文件不存在，编译会使用项目中包含你所引用的键的 `.bib` 文件。完全没有参考文献时，引用会按你输入的样子保留在 PDF 中，例如 `[@smith2020]`，这样你可以先写作，之后再添加参考文献。没有引用任何内容的文档，构建时不会读取任何 `.bib` 文件。

[查找和管理参考文献 →](/docs/citations/)

## 导入与导出

要让已有草稿继续保持 Markdown 形式，请创建一个 Blank Markdown document，把草稿粘贴到 `main.md`，并导入它的图片和参考文献。项目库中单独的 **Markdown 文档** 导入目前会把草稿转换为 LaTeX。[导入途径](/docs/import-project/)介绍了这两条路径。

编译即可得到 PDF，或用 **导出** 生成 Word、HTML、Typst、LaTeX、PowerPoint、EPUB 或纯文本。导出到 LaTeX 和 Typst 时会保留参考文献，并链接到你的图片文件而不是复制它们，所以请把这些文件放在导出文件旁边。Pandoc 略去某些内容时，导出会带警告保存，**显示警告**会列出被丢弃的内容。要分享原始的 Markdown 及其资源，请使用源码 ZIP。[导出你的工作](/docs/export/)介绍了操作顺序，以及在转换后的文件中应做哪些检查。
