# 用 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 中应该包含标题、各级标题、有序列表和表格。第一对 `---` 之间的元数据控制文档的标题和作者。

## 源码与可视化编辑

工具栏开头的切换开关有三种模式。**代码** 直接编辑 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`，然后应用。

### 插入表格

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

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

### 绘制图表

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

### 文档分析

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

### 文档设置

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

### 项目信息

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

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

### 查找

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

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

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

## 公式和代码块

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

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

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

## Mermaid 图表

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

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

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

## 引用与参考文献

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

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

## 导入与导出

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

编译即可得到 PDF，或用 **导出** 生成 Word、HTML、Typst、LaTeX 或纯文本。要分享原始的 Markdown 及其资源，请使用源码 ZIP。[导出你的工作](/docs/export/)介绍了操作顺序，以及在转换后的文件中应做哪些检查。