# 用 Markdown 寫作

用熟悉的 Markdown 撰寫草稿，並產生 PDF 或供協作者使用的可編輯文件。

Markdown 很適合用來寫研究筆記、報告與早期草稿。Oleafly 為它提供專用的格式工具列與 Pandoc 建置路徑，原始碼檔案在應用程式之外也能使用。

## 製作報告

1. 選擇 **「新增專案 → 使用範本 → Blank Markdown document」**。
2. 將專案命名為 **「Field notes」**，並開啟 `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 應該會包含標題、各級標題、編號清單與表格。第一對 `---` 之間的中繼資料，控制文件的標題與作者。

## 文件類型

在前置資料中加入一行 `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` |

以你自己的前置資料為優先。你自己設定的值，例如 `documentclass`、`aspectratio` 或 `geometry`，會取代該類型自動填入的值。

對於投影片，設定 `slide-level` 可以選擇哪一級標題開啟一張投影片。設為 `slide-level: 1` 時，每個 `#` 標題都會開啟一張。投影片會建置成一般的 PDF，所以預覽工具列上的**放映**可以顯示它們。請參閱[放映投影片](/docs/present-slides/)。

除非你把 `papersize` 設為 `a1`、`a2`、`a3` 或 `a4`，否則海報是 A0。其他尺寸，例如 `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 會依文件中找到的文字選擇字型，所以韓文、日文、中文、阿拉伯文、希伯來文、希臘文、西里爾文、天城文、泰文和其他數種文字，都不用設定就能顯示。符號和表情符號也會有字型，表情符號是黑白的。主要用阿拉伯文或希伯來文寫成的文件會由右到左排列。

中文字元同時出現在中文和日文文字中，所以請在 front matter 中設定 `lang` 以取得正確的字型：日文用 `ja`，簡體中文用 `zh`，繁體中文用 `zh-TW`，韓文用 `ko`。沒有 `lang` 時，Oleafly 會依文字判斷：假名表示日文，諺文表示韓文。

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

你自己選的字型優先。當 front matter 設定了 `mainfont` 或 `CJKmainfont`，或 `header-includes` 設定了字型，Oleafly 就不會動那一部分。

### PDF 中缺少的字元

當使用中的字型都沒有某個字元時，PDF 仍會建置但不含該字元，而編譯會顯示警告，附上缺少字元的範例。修正方式：

- 對於韓文、中文或日文文字，請在 front matter 中把 `CJKmainfont` 設為你電腦上已安裝、含有這些字元的字型。
- 對於其他文字，請用同樣的方式設定 `mainfont`。[文件設定](/docs/document-settings/#markdown)中的 **「內文字型」** 會替你寫入。
- 對於罕見的符號，請改用影像。

## 引用與參考文獻

匯入或建立 `references.bib`，在 YAML 中繼資料加入 `bibliography: references.bib`，並用 `[@citation-key]` 引用既有的鍵。Pandoc 會使用參考文獻來產生格式化的引用與參考文獻清單。

如果 front matter 沒有指定參考文獻，或指定的檔案不存在，編譯會使用專案中含有你所引用之鍵的 `.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 略過某些內容時，匯出會附帶警告儲存，而 **「顯示警告」** 會列出被捨棄的內容。用原始碼 ZIP 分享原始的 Markdown 與它的資源。[匯出你的作品](/docs/export/)涵蓋流程，以及在轉換後的檔案中該做的檢查。
