# 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` | 1 ページの 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/)を参照してください。

ポスターは、`papersize` に `a1`、`a2`、`a3`、`a4` を指定しない限り、A0 です。`letter` や `a5` などのほかのサイズは無視されます。横長のポスターにするには、`orientation: landscape` を加えます。

手紙では、宛先の住所を `to` から、自分の住所を `from` から取ります。`opening` は挨拶、`closing` は、`author` から取る名前の前の 1 行です。`subject` は件名になり、`subject` がなければ `title` が使われます。住所は、1 行を 1 項目にしたリストで書きます。

```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) は、すべての種類を、アプリと同じようにビルドします。

## ソース編集とビジュアル編集

ツールバーの先頭にあるスイッチには 3 つのモードがあります。**コード**は 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~`。

下線とハイライトは、書式が PDF にも引き継がれるように、Pandoc の属性を使います。原稿に生の HTML タグを加える代わりに、これらのコントロールを使ってください。

### リンクを挿入

**コード**モードでは、`[link text](url)` を挿入します。2 つのプレースホルダーを両方とも置き換えます。

**ビジュアル**モードでは、**リンクの 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 で保存し直してください。

### 表を挿入

**コード**モードでは、3 列、見出し行、データ 2 行を挿入します。列名とセルを置き換えます。

**ビジュアル**モードでは、同じ開始サイズの編集できる表を挿入します。

### 図を描く

Mermaid モードで[ダイアグラムコンポーザー](/docs/figures-diagrams/)を開きます。キャンバスにフローチャートを描くか Mermaid のコードを編集してから、**Mermaid として挿入**を選ぶと、カーソル位置に、`mermaid` のフェンス付きコードブロックとして追加されます。[Mermaid ダイアグラム](#mermaid-diagrams)を参照してください。

### 文書の分析

文書の見出し、図、表、数式、ラベル、引用、to-do を、ソースの順に、それぞれの行へのリンク付きで一覧します。タイトル、著者、キーワード、日付、概要も front matter から読み取り、投稿フォーム用にコピーできます。[文書の分析](/docs/document-insights/)を参照してください。

### 文書の設定

文書の種類、文書クラス、用紙サイズ、段数、余白、本文フォント、フォントサイズ、言語、行間、セクション番号を変更します。Oleafly は、選択した内容を Pandoc が読む YAML front matter に書き込み、ファイルに front matter がない場合はそのブロックを追加します。[文書の設定](/docs/document-settings/#markdown)を参照してください。

### プロジェクト情報

**コード**モードでは、プロジェクトの統計と選択範囲の情報を表示します。

**ビジュアル**モードでは、ビジュアル編集画面の統計を表示します。

### 検索

**コード**モードでは、⌘F / Ctrl+F でアクティブなファイルの検索を開きます。

**ビジュアル**モードでは、ソースのツールバーの検索ボタンは非表示です。

画像は、参照する前にファイルツリーから読み込みます。画像のパスは原稿からの相対パスにしておくと、ソースのアーカイブが別のコンピュータでも動きます。

![Markdown の実験ノートをソースとビジュアルで編集しても、表と ToDo リストは同期したままです。](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## 数式とコードブロック

行内の数式は `$x^2$` と書きます。ディスプレイ数式は、ドル記号 2 つのペアの間に置きます。

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

コードのサンプルは、コードを 3 つのバッククォートで囲み、開きのフェンスの後ろに言語を書きます。これらはソース上の構文です。Markdown のツールバーには、数式やフェンス付きコードブロックの専用ボタンはありません。

ビジュアルモードでは、フェンス付きのブロックはコードブロックのままで、言語と空行も保たれるので、Mermaid のダイアグラムも失われません。3 つのバッククォートを入力すると新しいブロックが始まり、ブロックの中では 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/)で説明しています。
