# Viết bằng Markdown

Soạn thảo với cú pháp Markdown quen thuộc và tạo PDF hoặc tài liệu chỉnh sửa được cho cộng sự.

Markdown phù hợp tốt cho ghi chú nghiên cứu, báo cáo và bản nháp sớm. Oleafly cung cấp cho nó một thanh định dạng riêng và một đường dựng bằng Pandoc, với các tệp nguồn bạn có thể dùng bên ngoài ứng dụng.

## Tạo một báo cáo

1. Chọn **New project → Use a template → Blank Markdown document**.
2. Đặt tên dự án là **Ghi chú thực địa** và mở `main.md`.
3. Dán ví dụ này, rồi chọn **Recompile** hoặc nhấn **⌘Enter / Ctrl+Enter**.
4. Nếu Oleafly đề nghị thiết lập một engine cần thiết, hoàn tất thiết lập đó và biên dịch lại.

```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 cần có một tiêu đề, các đề mục, một danh sách đánh số và một bảng. Siêu dữ liệu nằm giữa cặp dòng `---` đầu tiên điều khiển tiêu đề và tác giả của tài liệu.

## Kiểu tài liệu

Thêm một dòng `type` vào front matter để dựng tài liệu thành báo cáo, sách, bản trình chiếu, poster, thư hoặc CV. Khi không có `type`, hoặc có một giá trị mà Oleafly không biết, tài liệu được dựng thành một bài báo.

| `type` | Dựng thành gì | Được điền sẵn trừ khi bạn đặt |
| --- | --- | --- |
| `article` | Một bài báo | Không có gì |
| `report` hoặc `thesis` | Một báo cáo, với một chương ở mỗi tiêu đề `#` | `documentclass: report` |
| `book` | Một cuốn sách, với một chương ở mỗi tiêu đề `#` | `documentclass: book` |
| `slides` | Slide Beamer 16:9. Một tiêu đề `#` bắt đầu một phần và một tiêu đề `##` bắt đầu một slide | `aspectratio: 169` |
| `poster` | Một poster Beamer một trang, đứng đầu bởi `title`, `subtitle`, `author` và `institute` của nó | Giấy A0, khổ dọc |
| `letter` | Một bức thư có địa chỉ của bạn và của người nhận, dòng tiêu đề, lời chào mở đầu và lời kết | `documentclass: scrlttr2` |
| `cv` | Một bài báo gọn | `geometry: margin=2cm` và `pagestyle: empty` |

Front matter của chính bạn được ưu tiên. Một giá trị bạn tự đặt, chẳng hạn `documentclass`, `aspectratio` hoặc `geometry`, thay thế giá trị mà kiểu đã điền sẵn.

Với slide, đặt `slide-level` để chọn cấp tiêu đề bắt đầu một slide. Với `slide-level: 1`, mỗi tiêu đề `#` bắt đầu một slide. Slide được dựng thành một PDF thông thường, nên **Present** trên thanh công cụ xem trước có thể trình chiếu chúng. Xem [Trình chiếu slide](/docs/present-slides/).

Một poster là A0 trừ khi bạn đặt `papersize` thành `a1`, `a2`, `a3` hoặc `a4`. Các khổ khác, chẳng hạn `letter` hoặc `a5`, bị bỏ qua. Thêm `orientation: landscape` cho một poster khổ ngang.

Một bức thư lấy địa chỉ người nhận từ `to` và địa chỉ của bạn từ `from`. `opening` là lời chào, và `closing` là dòng đứng trước tên bạn, vốn lấy từ `author`. `subject` trở thành dòng tiêu đề, hoặc `title` nếu không có `subject`. Hãy viết một địa chỉ dưới dạng danh sách, mỗi mục một dòng.

```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.
```

**Document type** trong [Document settings](/docs/document-settings/#markdown) viết dòng `type` giúp bạn. Một [bản xuất LaTeX](/docs/export/#what-each-format-keeps) cũng theo kiểu này, và một [bản xuất PowerPoint](/docs/export/#presentation-and-book-exports) của slide dùng cùng `slide-level`. [`oleafly build`](/docs/cli/#build-a-project) dựng mọi kiểu giống như ứng dụng.

## Soạn thảo mã nguồn và Visual

Công tắc ở đầu thanh công cụ có ba chế độ. **Code** chỉnh sửa Markdown trực tiếp. **Visual** cung cấp soạn thảo có định dạng cho tiêu đề, đoạn văn, danh sách, liên kết, hình ảnh và bảng. **Both** hiển thị mã nguồn và văn bản đã định dạng cạnh nhau. Mở menu của nó để chọn **Stacked** hoặc **Split**. Dự án mới mở ở chế độ Code, và mỗi dự án ghi nhớ chế độ bạn để lại.

Gạch chân, tô sáng, chỉ số trên và chỉ số dưới là các nút định dạng Pandoc ở chế độ Code. Nút của chúng bị ẩn ở chế độ Visual. Dùng Code khi làm việc với siêu dữ liệu, cú pháp trích dẫn hoặc các thành phần mã nguồn khác.

[Tải mã nguồn ví dụ](/examples/writing-example.md)

## Mọi công cụ trên thanh công cụ

Chọn văn bản trước khi nhấp một nút định dạng. Ở chế độ Code, hầu hết công cụ sẽ bọc phần chọn hoặc chèn một phần giữ chỗ. Mở **More formatting options** (`…`) để đến những nút không vừa trên thanh.

### Code / Visual

Chuyển giữa **Code**, **Visual** và **Both**. Tài liệu vẫn là mã nguồn Markdown trong mọi chế độ.

### Undo

Hoàn tác chỉnh sửa gần nhất. ⌘Z / Ctrl+Z.

### Redo

Làm lại một chỉnh sửa đã hoàn tác. **⌘Shift+Z / Ctrl+Shift+Z**.

### Heading → Title

Chọn **Title** từ menu tiêu đề để chèn `# Title`. Thay văn bản tiêu đề bằng tiêu đề của riêng bạn.

### Heading → Section

Chọn **Section** từ menu tiêu đề để chèn `## Section`. Thay văn bản tiêu đề bằng tiêu đề của riêng bạn.

### Heading → Subsection

Chọn **Subsection** từ menu tiêu đề để chèn `### Subsection`. Thay văn bản tiêu đề bằng tiêu đề của riêng bạn.

### Heading → Subsubsection

Chọn **Subsubsection** từ menu tiêu đề để chèn `#### Subsubsection`. Thay văn bản tiêu đề bằng tiêu đề của riêng bạn.

### Heading → Minor heading

Chọn **Minor heading** từ menu tiêu đề để chèn `##### Minor heading`. Thay văn bản tiêu đề bằng tiêu đề của riêng bạn.

### Heading → Paragraph heading

Chọn **Paragraph heading** từ menu tiêu đề để chèn `###### Paragraph heading`. Thay văn bản tiêu đề bằng tiêu đề của riêng bạn.

### Bulleted list

Bắt đầu một danh sách không thứ tự. `- Item`.

### Numbered list

Bắt đầu một dãy có thứ tự. `1. Item`.

### Task list

Ở chế độ Code, thêm một việc và đổi `[ ]` thành `[x]` khi hoàn thành. `- [ ] Task`.

### Blockquote

Đặt một đoạn trích trên dòng riêng của nó. `> quoted text`.

### Bold

Nhấn mạnh văn bản được chọn. `**text**`; ⌘B / Ctrl+B.

### Italic

Nhấn mạnh một thuật ngữ. `*text*`; ⌘I / Ctrl+I.

### Strikethrough

Đánh dấu văn bản đã lỗi thời. `~~text~~`.

### Inline code

Định dạng một tên tệp, lệnh hoặc định danh. Văn bản được bao bằng dấu backtick.

### Underline

Chọn một cụm từ ở chế độ Code. `[text]{.underline}`.

### Highlight

Chọn một cụm từ ở chế độ Code. `[text]{.mark}`.

### Superscript

Chọn số mũ ở chế độ Code. `^text^`.

### Subscript

Chọn chỉ số dưới ở chế độ Code. `~text~`.

Gạch chân và tô sáng dùng thuộc tính Pandoc để định dạng có thể đi vào PDF. Dùng các nút này thay vì thêm thẻ HTML thô vào bản thảo.

### Insert link

Ở chế độ **Code**: Chèn `[link text](url)`. Thay cả hai phần giữ chỗ.

Ở chế độ **Visual**: Mở **Link URL**. Nhập địa chỉ và áp dụng cho phần chọn của bạn. Dùng **Remove link** để giữ văn bản mà bỏ liên kết.

### Insert image

Ở chế độ **Code**: Chèn `![caption](image-filename)`. Thay đường dẫn và chú thích.

Ở chế độ **Visual**: Mở **Image file**. Nhập một đường dẫn trong dự án như `figures/plot.png` và áp dụng.

Các ảnh PNG, JPG, PDF, SVG, GIF, WebP và BMP đều vào được PDF. Oleafly chuyển đổi SVG, GIF và WebP giúp bạn khi biên dịch. Ảnh TIFF, AVIF, HEIC và JPEG XL không vào được: lần biên dịch dừng lại và nêu tên tệp, nên hãy lưu ảnh ở một trong các định dạng còn lại rồi biên dịch lại. Nếu một lần chuyển đổi thất bại, hãy kiểm tra xem ảnh có mở được không, hoặc lưu nó thành PNG hay PDF.

### Insert table

Ở chế độ **Code**: Chèn ba cột, một hàng tiêu đề và hai hàng dữ liệu. Thay tên cột và các ô.

Ở chế độ **Visual**: Chèn một bảng có thể chỉnh sửa với kích thước ban đầu như vậy.

### Draw a diagram

Mở [trình soạn thảo sơ đồ](/docs/figures-diagrams/) ở chế độ Mermaid. Vẽ một lưu đồ trên canvas hoặc chỉnh sửa mã Mermaid, rồi chọn **Insert as Mermaid** để thêm nó tại vị trí con trỏ dưới dạng một khối mã `mermaid` trong cặp ba dấu backtick. Xem [Sơ đồ Mermaid](#mermaid-diagrams).

### Document insights

Liệt kê các tiêu đề, hình, bảng, phương trình, nhãn, trích dẫn và việc cần làm của tài liệu theo thứ tự trong mã nguồn, mỗi mục liên kết đến dòng của nó. Nó cũng đọc tiêu đề, tác giả, từ khóa, ngày tháng và tóm tắt từ phần front matter, và có thể sao chép chúng cho một mẫu nộp bài. Xem [Document insights](/docs/document-insights/).

### Document settings

Thay đổi kiểu tài liệu, lớp tài liệu, khổ giấy, số cột, lề, phông chữ nội dung, cỡ chữ, ngôn ngữ, giãn dòng và đánh số mục. Oleafly ghi các lựa chọn của bạn vào phần front matter YAML mà Pandoc đọc, và thêm một khối front matter nếu tệp chưa có. Xem [Document settings](/docs/document-settings/#markdown).

### Project info

Ở chế độ **Code**: Hiển thị thống kê dự án và thông tin về phần chọn.

Ở chế độ **Visual**: Hiển thị thống kê cho bề mặt soạn thảo trực quan.

### Find

Ở chế độ **Code**: Mở tìm kiếm trong tệp đang mở bằng ⌘F / Ctrl+F.

Ở chế độ **Visual**: Nút Find trên thanh công cụ mã nguồn bị ẩn.

Nhập hình ảnh qua cây tệp trước khi tham chiếu đến nó. Giữ đường dẫn hình ảnh tương đối so với bản thảo, để tệp nén mã nguồn chạy được trên máy tính khác.

![Một sổ tay thí nghiệm Markdown được chỉnh sửa ở chế độ mã nguồn và Visual, còn bảng và danh sách việc cần làm luôn đồng bộ.](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## Phương trình và khối mã

Viết toán học cùng dòng dưới dạng `$x^2$`. Đặt một phương trình hiển thị giữa hai cặp dấu dollar:

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

Với một mẫu mã, bao mã bằng ba dấu backtick và đặt ngôn ngữ của nó sau fence mở. Đây là các thành phần mã nguồn; thanh công cụ Markdown không có nút riêng cho phương trình hay khối mã trong fence.

Trong chế độ Visual, một khối có fence vẫn là một khối mã và giữ nguyên ngôn ngữ cùng các dòng trống của nó, nên sơ đồ Mermaid được bảo toàn. Gõ ba dấu backtick để bắt đầu một khối mới, và nhấn Tab để thụt lề bên trong khối.

## Sơ đồ Mermaid

Chọn **Draw a diagram** trên thanh công cụ để tạo một lưu đồ Mermaid trong trình soạn thảo sơ đồ. **Insert as Mermaid** thêm nó dưới dạng một khối mã trong cặp ba dấu backtick:

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

Ở chế độ **Both**, bên đã định dạng vẽ khối đó thành sơ đồ. PDF cần một hình ảnh, nên trình soạn thảo sơ đồ cũng lưu một PNG đã kết xuất tại `figures/mermaid-<hash>.png`, và lần biên dịch đặt hình ảnh đó vào chỗ của khối mã. Sơ đồ nhờ vậy cũng xuất hiện trong PDF đã biên dịch, và trong các bản xuất Word, HTML, EPUB và PowerPoint. Nếu bạn chỉnh sửa khối mã bằng tay sau đó, PDF sẽ hiển thị mã cho đến khi bạn chèn hoặc lưu lại sơ đồ từ trình soạn thảo sơ đồ. Xem [Mermaid trong tài liệu Markdown](/docs/figures-diagrams/#mermaid-in-markdown-documents).

## Văn bản bằng các ngôn ngữ khác

Oleafly chọn phông chữ cho các hệ chữ nó tìm thấy trong tài liệu, nên tiếng Hàn, tiếng Nhật, tiếng Trung, tiếng Ả Rập, tiếng Do Thái, tiếng Hy Lạp, chữ Cyrillic, Devanagari, tiếng Thái và nhiều hệ chữ khác hiển thị mà không cần thiết lập gì. Ký hiệu và emoji cũng nhận một phông chữ, với emoji màu đen trắng. Một tài liệu viết chủ yếu bằng tiếng Ả Rập hoặc tiếng Do Thái chạy từ phải sang trái.

Chữ Hán xuất hiện trong cả văn bản tiếng Trung lẫn tiếng Nhật, nên hãy đặt `lang` trong front matter để có đúng phông chữ: `ja` cho tiếng Nhật, `zh` cho tiếng Trung giản thể, `zh-TW` cho tiếng Trung phồn thể, hoặc `ko` cho tiếng Hàn. Khi không có `lang`, Oleafly dựa vào văn bản: kana nghĩa là tiếng Nhật và Hangul nghĩa là tiếng Hàn.

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

Phông chữ bạn tự chọn được ưu tiên trước. Khi front matter đặt `mainfont` hoặc `CJKmainfont`, hoặc `header-includes` thiết lập phông chữ, Oleafly để yên phần đó.

### Ký tự bị thiếu trong PDF

Khi không phông chữ nào đang dùng có một ký tự, PDF vẫn dựng được mà thiếu nó, và lần biên dịch hiển thị một cảnh báo kèm một vài ký tự bị thiếu làm mẫu. Để khắc phục:

- Với văn bản tiếng Hàn, tiếng Trung hoặc tiếng Nhật, đặt `CJKmainfont` trong front matter thành một phông chữ đã cài trên máy tính của bạn có các ký tự đó.
- Với văn bản khác, đặt `mainfont` theo cách tương tự. **Body font** trong [Cài đặt tài liệu](/docs/document-settings/#markdown) ghi nó giúp bạn.
- Với một ký hiệu hiếm, hãy dùng một hình ảnh thay thế.

## Trích dẫn và danh mục tài liệu tham khảo

Nhập hoặc tạo `references.bib`, thêm `bibliography: references.bib` vào siêu dữ liệu YAML, và trích dẫn một khóa sẵn có bằng `[@citation-key]`. Pandoc dùng danh mục tài liệu để tạo các trích dẫn đã định dạng và một danh mục tài liệu tham khảo.

Nếu front matter không nêu danh mục tài liệu nào, hoặc nêu một tệp không có ở đó, lần biên dịch dùng các tệp `.bib` của dự án có chứa các khóa bạn trích dẫn. Một trích dẫn mà hoàn toàn không có danh mục tài liệu nào vẫn ở lại trong PDF đúng như bạn gõ, chẳng hạn `[@smith2020]`, để bạn có thể viết trước và thêm tài liệu tham khảo sau. Một tài liệu không trích dẫn gì sẽ dựng mà không đọc tệp `.bib` nào.

[Tìm và quản lý tài liệu tham khảo →](/docs/citations/)

## Nhập và xuất

Để giữ một bản nháp sẵn có ở định dạng Markdown, tạo một Blank Markdown document, dán bản nháp vào `main.md`, rồi nhập hình ảnh và danh mục tài liệu của nó. Lệnh nhập **Markdown document** riêng trong thư viện hiện chuyển bản nháp sang LaTeX. [Các đường nhập dự án](/docs/import-project/) giải thích cả hai con đường.

Biên dịch để có PDF, hoặc dùng **Export** để tạo Word, HTML, Typst, LaTeX, PowerPoint, EPUB hoặc văn bản thuần. Các bản xuất sang LaTeX và Typst giữ danh mục tài liệu tham khảo, và liên kết đến các tệp hình của bạn thay vì sao chép chúng, nên hãy giữ các tệp đó cạnh bản xuất. Khi Pandoc bỏ qua điều gì đó, bản xuất được lưu kèm cảnh báo, và **Show warnings** liệt kê những gì đã bị bỏ. Dùng ZIP mã nguồn để chia sẻ Markdown gốc và các tệp đi kèm. [Xuất tác phẩm của bạn](/docs/export/) trình bày trình tự và những điều cần kiểm tra trong tệp đã chuyển đổi.
