# Markdown으로 쓰기

익숙한 Markdown으로 초안을 쓰고 PDF나 협업자를 위한 편집 가능한 문서를 만듭니다.

Markdown은 연구 노트, 보고서, 초기 초안에 잘 맞습니다. Oleafly는 Markdown에 전용 서식 툴바와 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에는 제목, 소제목, 번호 목록, 표가 있어야 합니다. 첫 번째 `---` 줄 한 쌍 사이의 메타데이터가 문서 제목과 저자를 정합니다.

## 문서 유형

프런트 매터에 `type` 줄을 추가하면 문서를 보고서, 책, 슬라이드, 포스터, 편지, 이력서로 빌드합니다. `type`이 없거나 Oleafly가 모르는 값이면 문서는 논문으로 빌드됩니다.

| `type` | 빌드되는 것 | 직접 설정하지 않으면 채워지는 것 |
| --- | --- | --- |
| `article` | 논문 | 없음 |
| `report` 또는 `thesis` | `#` 제목마다 장이 있는 보고서 | `documentclass: report` |
| `book` | `#` 제목마다 장이 있는 책 | `documentclass: book` |
| `slides` | 16:9 Beamer 슬라이드. `#` 제목은 섹션을, `##` 제목은 슬라이드를 시작합니다 | `aspectratio: 169` |
| `poster` | `title`, `subtitle`, `author`, `institute`가 머리말로 들어가는 한 페이지 Beamer 포스터 | 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에 들어갑니다. SVG, GIF, WebP는 컴파일할 때 Oleafly가 대신 변환합니다. TIFF, AVIF, HEIC, JPEG XL 이미지는 넣을 수 없습니다. 컴파일이 멈추고 그 파일 이름을 알려 주므로, 다른 형식으로 저장한 뒤 다시 컴파일하세요. 변환에 실패하면 이미지가 열리는지 확인하거나 PNG나 PDF로 저장하세요.

### 표 삽입

**코드** 모드: 열 세 개, 머리글, 데이터 행 두 개가 삽입됩니다. 열 이름과 셀을 바꾸세요.

**비주얼** 모드: 같은 크기로 시작하는 편집 가능한 표가 삽입됩니다.

### 다이어그램 그리기

[다이어그램 작성기](/docs/figures-diagrams/)를 Mermaid 모드로 엽니다. 캔버스에 순서도를 그리거나 Mermaid 코드를 편집한 다음 **Mermaid로 삽입**을 선택하면 펜스로 감싼 `mermaid` 코드 블록으로 커서 위치에 추가됩니다. [Mermaid 다이어그램](#mermaid-diagrams)을 참고하세요.

### 문서 분석

문서의 제목, 그림, 표, 수식, 레이블, 인용, 할 일을 소스 순서대로 해당 줄로 연결된 목록으로 보여 줍니다. 또한 앞부분 메타데이터(front matter)에서 제목, 저자, 키워드, 날짜, 초록을 읽어 제출 양식에 쓸 수 있도록 복사할 수 있습니다. [문서 분석](/docs/document-insights/)을 참고하세요.

### 문서 설정

문서 유형, 문서 클래스, 용지 크기, 단, 여백, 본문 글꼴, 글꼴 크기, 언어, 줄 간격, 절 번호 매기기를 바꿉니다. Oleafly가 선택한 값을 Pandoc이 읽는 YAML front matter에 쓰며, 파일에 front matter 블록이 없으면 추가합니다. [문서 설정](/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` 파일을 가져오거나 만들고, YAML 메타데이터에 `bibliography: references.bib` 줄을 추가한 다음, `[@citation-key]`로 기존 키를 인용하세요. Pandoc이 참고문헌을 사용해 서식이 갖춰진 인용과 참고문헌 목록을 만듭니다.

머리말이 참고문헌을 지정하지 않았거나 없는 파일을 지정하면, 컴파일은 인용한 키가 들어 있는 프로젝트의 `.bib` 파일을 사용합니다. 참고문헌이 아예 없는 인용은 `[@smith2020]`처럼 입력한 그대로 PDF에 남으므로, 먼저 글을 쓰고 나중에 참고문헌을 추가할 수 있습니다. 아무것도 인용하지 않는 문서는 `.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/)에서 순서와 변환된 파일에서 확인할 사항을 다룹니다.
