# 文書形式

> Postextが解析するMarkdownのサブセットと、原稿となる文書を書くときの規則

- HTML版: https://postext.dev/ja/docs/document-format
- 最終更新: 2026-10-05
- 読了時間: 10分
- 他の言語: [en](https://postext.dev/en/docs/document-format.md), [es](https://postext.dev/es/docs/document-format.md), [ca](https://postext.dev/ca/docs/document-format.md), [zh](https://postext.dev/zh/docs/document-format.md), [ar](https://postext.dev/ar/docs/document-format.md)

## かんたんな説明

このページでは、Postextが組める文章の書き方を説明します。文章はMarkdownで書きます。Markdownは、いくつかの記号で見出し、リスト、太字、リンクを表す簡単な書き方です。Postextは、囲み、脚注、画像、表、数式のための追加の記号も理解します。このページには、受け付ける記号と無視する記号をすべて載せています。最後に、読みやすい文章を書くための助言があります。

**Postextが読むMarkdownの方言は、意図的に小さくしてあります。**

パーサーは完全なCommonMark実装ではなく手書きのトークナイザーなので、原稿の形式は狭く、予測しやすいものになっています。ねらいは2つあります。エンジンを小さく高速に保つことと、PostextとほかのCommonMarkリーダー（Obsidian、Pandoc、VS Code…）との間で文書をそのまま持ち運べるようにすることです。このページに載っていないものは、プレーンテキストとして扱われるか、インラインの流れから取り除かれます。

プログラムで文書を組み立てる場合は、`parseMarkdown`関数（[設定 › 解析](/ja/docs/configuration#解析)を参照）が、組版エンジンが受け取るブロック構造そのものを返します。

## フロントマター

文書の先頭には、`---`の行で囲んだYAMLのフロントマターを置くことができます（省略可）。

```md
---
title: Chapter One
author: Jane Doe
publishDate: 2026-04-15
---

# Chapter One

The story begins here…
```

`extractFrontmatter(source)`を呼ぶと、フロントマターと本文が分かれます。解析したメタデータのオブジェクトが、残りのMarkdown、および本文が始まる文字オフセットとともに返されます。エラーやカーソル位置を元の原稿の位置に対応させたいときに役立ちます。

フロントマターは[`gray-matter`](https://github.com/jonschlinkert/gray-matter)で解析するので、YAMLの形は問いません。Postext自身が見るのは`title`、`subtitle`、`author`、`publishDate`だけです。それ以外のキーは`PostextContent.metadata`にそのまま残るので、自由に使えます。

YAMLは値に型を付けます。`1984`は数値、`2026-04-15`は日付、`[Ana Gil, Luis Paz]`はリストです。Postextはこの4つのフィールドを、型にかかわらずテキストとして出力します。

- 数値は通常の10進表記で、真偽値は`true`または`false`として出力します（`title: 1984`は「1984」と出力）。YAMLは数値を1桁ずつではなく値として読むので、`1.50`は「1.5」、`017`（8進数）は「15」、`1:30`（60進数）は「90」と出力します。
- 日付は暦の日付として、文書の言語（`locale`設定、なければハイフネーションのロケール）で書き表します。`publishDate: 2026-04-15`は、英語では「April 15, 2026」、スペイン語では「15 de abril de 2026」、ドイツ語では「15. April 2026」と出力します。アラビア語の日付は、タグが別の暦を指定しない限りグレゴリオ暦を使い（`ar-u-ca-islamic`ならヒジュラ暦の日付）、数字はタグが示すものを使います（`ar-EG`：١٥ أبريل ٢٠٢٦、`ar-u-nu-latn`：15 أبريل 2026）。時刻付きの日付は、UTCでの日付を出力し、時刻は捨てます。`2026-09-24T23:30:00-05:00`はUTCで25日の04:30なので、「September 25, 2026」と出力します。
- リストは項目をコンマでつないで出力します（`author: [Ana Gil, Luis Paz]`は「Ana Gil, Luis Paz」と出力）。

書いたとおりに出力したい値は引用符で囲みます。桁を保ちたい数値や、日の書き方を保ちたい日付などです（`publishDate: "15/04/2026"`、`title: "1984"`）。そのテキストが`doc.metadata`、プレースホルダー（`{title}`、`{publishDate}`…）、PDFのタイトルと著者に渡ります。4つのフィールドのうちテキストの形を持たないもの（入れ子のマップや空の`title:`）は、`doc.metadata`から除かれます。`extractFrontmatter`は、それでもYAMLが型付けしたとおりの値を返します。ある値についてPostextが出力するテキストは、`metadataText(value, locale)`で得られます。

## ブロック要素

Postextが認識する本文のブロックは7種類で、ほかにこのページの後半で扱うディレクティブとリソースの埋め込みがあります。ブロックは必ず、空行か別のブロックの開始で終わります。

> **図: 本文のブロック要素の一覧**
> Postextが認識する7種類の本文ブロック（見出し、段落、引用ブロック、箇条書きリスト、番号付きリスト、タスクリスト、別行立て数式）と、それぞれのMarkdown記法。ディレクティブとリソースの埋め込みは別に扱います。
>
> *本文のブロックの種類と、それぞれのMarkdownでの書き方。*

| 要素 | 記法 | 説明 |
| --- | --- | --- |
| 見出し | `# Title` … `###### H6` | 1〜6個の`#`のあとに、スペースと見出しのテキストを書きます。レベル1〜6は`headings.levels`の設定にそのまま対応します。 |
| 段落 | 1行以上のプレーンテキスト | 空行でも特殊な行でもない連続した行は、スペース1つでつないで1つの段落にします。中国語または日本語の2文字（漢字、仮名、全角の約物、およびそれらに隣接する曲がり引用符、ダッシュ、三点リーダー）の間では、CSSと同じく行末を削除するので、中国語の段落は原稿のどこで改行してもかまいません。そうした記号どうしの間（`“你好”⏎“再见”`、`他说……⏎“好”`）では、その外側の文字で決まります。どちらかが中国語または日本語なら行末を削除し、`“hello”⏎“bye”`ではスペースを残します。韓国語ではスペースを残します。段落の中の手動の改行は保持されません。新しい段落を始めるには空行を入れます。 |
| 引用ブロック | `> quoted text` | 引用の各行は`>`で始めます（そのあとのスペース1つは省略可）。連続する引用行は段落の行と同じようにつながり、1つの引用ブロックになります。組み方は`bodyText.blockquote`の指定に従います。変更しなければ、灰色のイタリック体で、本文と同じ1行目の字下げが付きます（[設定 › 引用ブロック](/ja/docs/configuration#引用ブロック)を参照）。 |
| 箇条書きリスト | `- item`, `* item`, `+ item` | 3種類の行頭記号のどれでも使えます。項目の記号を上の項目の記号より2桁以上右に下げると、その項目の下に入れ子になります。`-`の下ならスペース2つ、`1.`の下なら2つか3つ（CommonMarkと同じく、テキストの開始桁）で、深さは最大5までです。 |
| 番号付きリスト | `1. item`, `2) item` | 数字のあとに`.`か`)`を付けます。開始番号は保持されます（リストを5や0から始めることもできます）。出力に描く区切り記号は、原稿ではなく`orderedLists.separator`で決まります。 |
| タスクリスト（GFM） | `- [ ] todo`, `- [x] done` | 角かっこのチェックボックスが付いた箇条書きの項目です。小文字の`x`も大文字の`X`も使えます。`taskCheckboxChar`／`taskCheckedChar`のグリフで描きます。 |
| 別行立て数式 | `$$ … $$` | 独立したブロックとして組むLaTeXの数式です。段の中央に置き、見出しと同じくベースライングリッドに合わせ、PDF出力ではベクターのまま保ちます。1行の形式と、フェンスで囲む複数行の形式については、[数式](https://postext.dev/ja/docs/document-format#数式)で説明します。 |

2つのリスト項目の間に空行が1行あっても、リストは続きます。空行が2行以上あるとリストは終わります。

同じ深さで種類の違うリストを混ぜることもできます（途中で箇条書きから番号付きに切り替えられます）が、エンジンは番号付けの上で、それぞれのひと続きを別のリストとして扱います。実際には、混ぜる理由がない限り、深さごとに1種類にしてください。

> **図: リストの入れ子の深さ**
> リスト項目は、上の項目の記号より右に下げると、その項目の下に入れ子になります。行頭記号の下ならスペース2つで、深さは最大5です。レベルごとに字下げが深くなり、行頭記号のスタイルを変えることもできます。
>
> *行頭記号の下では1レベルにつきスペース2つ。深さは最大5。*

### 見出しの属性

見出しの行の末尾には、波かっこで囲んだ属性ブロックを書けます。ディレクティブと同じ`key="value"`の構文です。

```markdown
# The Long Road {author="I. Zango Martín" year=1998}
```

波かっことその中身は見出しのテキストから取り除かれ（上の例のタイトルは「The Long Road」と描かれます）、`attrs`として見出しに保存されます。これらはデザインのスロットで`{attr.<key>}`プレースホルダーとして使えます。使える場所は、その見出し自身の詳細デザインのスロットと、ページのヘッダーとフッターで、後者では現在の章のH1から値を解決します。認識するのは、行のいちばん末尾にある、波かっこを含まない釣り合ったブロックだけです。その前にはスペースが必要ですが、中国語のタイトルはスペースを入れずに書くので、中国語または日本語の文字の直後でもかまいません（`# 回目{style="x"}`）。ブロックとして取るのは、下の属性の構文で全体を読み取れる場合だけです。`{x, y}`、`{紅樓|hóng lóu}`、単独の`{}`はタイトルに残り、タイトルにくっついたフラグだけのブロック（`# 第一回{draft}`）も同様です。属性はスペースで区切るので、コンマを含むブロック（`{a="1", b="2"}`）やPandocの`{.class}`もタイトルに残ります。Pandocの識別子`{#id}`は読み取ります。これは`id="…"`と同じで、[相互参照](#相互参照とアンカー)のために見出しに名前を付けます。ほかの文字体系で書いたキーは読み取ったうえで警告とともに捨てる（下記参照）ので、`# 回目{style="x" 作者=曹雪芹}`でも`style`は有効です。**設定 → 柱とノンブル**を参照してください。

デザインのテキストが出力する値は、複数行にわたってもかまいません。2文字の`\n`はそこで改行し、要素の`overflow`にかかわらず有効です（`to="Firma X\nStrasse 1\n10115 Berlin"`は3行の住所を出力します）。要素で`inlineMarks`を指定すると、値の中のインラインの書式記号も効きます。`authors="Ana Ruiz^1^, Luis Gil^2^"`では所属の番号が上付きになります。このエスケープは属性の値（およびデザイン自身のテンプレート）に限られます。見出しのテキストの中、たとえばコードスパンの中にある`\n`の2文字は、書いたとおりに出力されます。

独自の意味を持つ属性が2つあります。`style="<id>"`は、名前付きの[見出しスタイル](/ja/docs/configuration#見出しスタイル)を見出しに適用します。独自の扉デザイン、柱、ページの寸法、本文の文字組みを持ち、スタイルが`numbered: false`なら章番号の付かない、序文や著者一覧などに使います。`toc="false"`（または`"true"`）は、その見出しを`:::toc`に載せるかどうかを上書きします。

```markdown
# Preface {style="front-matter"}

# Contents {style="front-matter" toc="false"}
```

ほかの2つは、見出しが出力するものと、その数え方を変えます。`hidden="true"`（または`"false"`）は、見出しのレベルまたはスタイルの`hidden`を上書きします。非表示の見出しは何も出力せず、場所も取りません（本文の流れの中でも`:::callout`の囲みの中でも同じです）が、ページを始め、番号を数え、目次、`{chapterTitle}`の柱、PDFのしおりには載ります。`jidori=N`は、1行の見出しを自身の文字`N`字分に均等に割り付けます（字取り：`# 序章 {jidori=3}`は序　章と出力します）。`jidori=0`は、レベルやスタイルが設定した均等割りを解除します（[設定 › レベルごとの上書き](/ja/docs/configuration#レベルごとの上書き)を参照）。`indent=N`は、レベルやスタイルの`indent`に代えて、1つの見出しを行頭から本文の`N`字分下げます（字下げ：`## 一 {indent=5}`）。数値だけなら本文のem単位で数え、`0`なら行頭に置きます。縦組みでも横組みでも同じように働きます。`startAt=N`（正の整数）は、見出しのレベルのカウンターを進める代わりに`N`にします。以降の見出しは後の章も含めてそこから数え、下のレベルは通常どおりその下で振り直します。付録をアルファベットで番号付けする見出しスタイル（`numberingTemplate: 'Appendix {1:A}'`）では、最初の付録でカウントを振り直すことで、章の続きではなく「Appendix A」となります。

```markdown
# To my mother {hidden="true" toc="false"}

# Survey instrument {style="appendix" startAt=1}

# Raw data {style="appendix"}
```

## ディレクティブ

ディレクティブは、単独の行に`:::name`または`:::name{attrs}`と書く1行の制御タグです。目に見える出力はなく、配置と番号付けの処理を動かします。

| 記法 | 効果 |
| --- | --- |
| `:::pagebreak` | 次のブロックを新しいページから始めます。 |
| `:::pagebreak{parity="odd"}` | 同上。さらに新しいページを奇数ページ（右ページ）にします。必要なら白ページを挿入します。 |
| `:::pagebreak{parity="even"}` | 同上ですが、偶数ページ（左ページ）を対象にします。 |
| `:::pagebreak{parity="always-odd"}` | 奇数ページに入る前に、少なくとも1ページの必須の区切りの白ページを入れます。区切りの白ページは前の内容に属し、それ以上の奇偶合わせの白ページはあとに続く内容に属します。どの章も新しい見開きから始める必要があるときに便利です。 |
| `:::pagebreak{parity="always-even"}` | 同上ですが、偶数ページを対象にします。 |
| `:::numbering{format="decimal" startAt=1}` | 次のページの境目で、ノンブルの番号の系列を切り替えます。属性はどちらも省略できます。書式を変えないなら`format`を、カウンターを続けるなら`startAt`を省略します。 |
| `:::columnbreak` | 現在の段をここで終えます。次のブロックは同じページの次の段から始まります（ディレクティブが最後の段にあるときは新しいページから）。空の段では何もしないので、空の段や白ページを生むことはありません。終えた段の下の空きはそのまま残り、段末そろえで引き伸ばされることはありません。 |
| `:::space` | ここに本文1行分の空きを入れます。2つのブロックの間に少し余白を加える明示的な方法です。`:::space{lines=2}`なら2行分です（`0.5`のような小数も使えます）。ブロック間のマージンに加算され、段やページの先頭では捨てられます。[後述](https://postext.dev/ja/docs/document-format#space)を参照してください。 |
| `:::toc` | ここに目次を出力します。対象レベルの見出し1つにつき1項目（タイトル、番号、ノンブル、必要に応じて章の著者）と、部の区切りごとに1行を、`toc`の設定に従って組みます。項目は文書に従うので、章の名前を変えたり、移動したり、番号を変えたりすると目次も追随します。 |
| `:::index` | ここに索引を出力します。本の中で`:index`で印を付けたすべての語を、並べ替えて頭文字ごとにまとめ、出現するページとともに`index`の設定に従って組みます。`:::index{index="names"}`は名前付きの索引を出力します。[索引](https://postext.dev/ja/docs/document-format#索引)を参照してください。 |
| `:::verse` … `:::` | 古典アラビア語の配置による詩です。1行に1ベイト（bayt）を書き、2つの半句を`\|\|`で区切り、共通の幅で横に並べて組みます。[後述](https://postext.dev/ja/docs/document-format#verse)を参照してください。 |

属性の値は、二重引用符（<code>"…"</code>）や一重引用符（<code>'…'</code>）で囲むか、囲まずに（<code>startAt=17</code>）書きます。`=`のないキーだけを書くと、値が空のフラグとして扱います。

現在、1行のディレクティブとして認識するのは`pagebreak`、`numbering`、`columnbreak`、`space`、`toc`、`index`だけです（フェンスで囲むブロックとしては`references`と`verse`）。それ以外の`:::name`行で、コンテナー（後述）でもないものは段落として解析され、Sandboxに**不明なディレクティブ**の警告が表示されます。エンジンもそれを、文書の`contentWarnings`の`unknownDirective`項目として記録します（[設定 › 文書の中の警告](/ja/docs/configuration#文書の中の警告)を参照）。

### 属性の値

同じ`key="value"`の構文を、見出しの属性、ディレクティブとコンテナーのフェンス（`:::name{…}`）、インラインの参照（`:ref{…}`）、チップ（`:chip[…]{…}`）、色見本（`:swatch{…}`）、索引の印（`:index[…]{…}`）が読み取ります。規則は次のとおりです。

- **キー**はASCIIの英字か`_`で始まり、ASCIIの英字、数字、`_`、`-`が続きます。`=`の前後にスペースがあってもかまいません。中国語の入力メソッドが入力する全角の`＝`も`=`として働きます。同じキーを繰り返すと最後の値が残り、`=`のないキーは値が空のフラグです。ほかの文字体系のキー（`作者=曹雪芹`）は読み取られず、`attributeKeyInvalid`警告が出ます。ブロック内のほかのキーは有効なままです。値はどの文字体系でもかまいません。
- **引用符で囲んだ値**。二重引用符の値には`"`以外の何でも（一重引用符も）入れられ、一重引用符の値には`'`以外の何でも入れられます。したがって、二重引用符を含む値は一重引用符で囲みます（`lead='He said "hi"'`）。エスケープはなく、バックスラッシュは普通の文字です。そのため、ASCIIの引用符を両方とも必要とする値には印刷用の引用符（`“…”`、`’`）を使います。値は、中国語の入力メソッドが入力する曲がり引用符`“`やかぎかっこ`「`で始めることもでき、その場合はスペースも含めて、対応する`”`または`」`までが値になります（`title=“甲戌本 眉批”`、`title=「脂批」`）。
- **囲まない値**（`startAt=17`、`year=1998`）は、次のスペースまでです。`title=Hello world`は`title="Hello"`とフラグ`world`になります。
- **波かっこは使えません**。`{`と`}`は値に入りません。最初の`}`でブロックが終わります。値に閉じ波かっこを含むフェンスはもうディレクティブではなく段落になり、インラインでは値の残りがテキストにはみ出します。見出しでは、値に波かっこがあるとブロック全体がタイトルに残ります。`# Title {note="a {b"}`は書いたとおりに組まれます（postext 1.8までは、スペースのあとの`{`でブロックが始め直され、`b`がフラグとして読まれていました）。
- **ドル記号は普通のテキストです**。属性はインラインの数式より先に読み取られるので、`lead="from $5 to $6"`はただのテキストです。
- **1行に収めます**。属性ブロックが複数行にまたがることはありません。

```markdown
# The Long Road {lead='A "road novel", they said' price="$18"}

:::callout{type="note" title='The "fast" path'}
…
:::
```

`::resource{id="…"}`はもっと厳格で、idは二重引用符で囲み、ほかの属性は付けられません（[リソース](#リソース)を参照）。

### コンテナー

コンテナーは、ひと続きのブロックをフェンスで囲みます。開始行`:::name`または`:::name{attrs}`のあとに通常の内容（段落、見出し、リスト、引用ブロック、数式、さらにはほかのディレクティブ）を書き、`:::`だけの行で閉じます。コンテナーは入れ子にでき、閉じる`:::`はそれぞれ、いちばん内側の開いているコンテナーを閉じます。

```
:::callout{type="note"}
Keep the lantern lit **every** night.

- Check the wick.
- Trim it at dusk.
:::
```

本文の流れの中で認識するコンテナー名は4つです（5つめの`:::columns`は囲みの中でだけ働きます。後述します）。それぞれが何を描くかは、設定のそれぞれの節で決めます。

| 記法 | 効果 |
| --- | --- |
| `:::callout{…}` … `:::` | 囲みの内容。本文から切り離して、枠線か地色のある囲みに入れた注記、ヒント、警告です。 |
| `:::paragraphs{…}` … `:::` | 本文のスタイルではなく、名前付きの段落スタイルで組むひと続きの段落です（リード文、エピグラフ、小さな文字の注記など）。`align`、`indent`、`endIndent`は、スタイルの有無にかかわらず、そろえと字下げを設定します。`:::paragraphs{align=end endIndent=1}`は、日付を行末から1字上げて組みます（地から1字上げ）。 |
| `:::part{…}` … `:::` | 部や大きな区切りの扉です。中の見出しと文章が、大きな区分の扉ページになります。 |
| `:::paper{…}` … `:::` | 別の用紙に印刷するひと続きのページです。マット紙の本の中にあるグロス紙の図版の部分などです。表示するのはFolioビューアーだけです。 |

各コンテナーが受け付ける属性と、そのスタイルの設定は、[設定](/ja/docs/configuration)で説明しています。属性の値は、ディレクティブと同じ文法に従います。`:::callout`のフェンスは、`type`（設定した囲みスタイルのid。未知の場合や指定がない場合は最初のスタイル）、`title`（スタイルの既定のタイトルを上書き）、および`span`／`placement`（`column`、`page`、`side`／`here`、`top`、`bottom`、`fixed`）を受け付けます。後者の2つは、その囲みについてスタイルの範囲と位置を上書きします。

```
:::callout{type="objectives" title="What you will learn" span="page" placement="top"}
- Name the parts of the lantern.
- Trim the wick without touching the glass.
:::
```

囲みは箱としてレイアウトされます。省略可能なタイトルのあとに、スタイル自身の本文とリストの文字組みで内容を組みます。既定では分割せず、収まらなければ全体を次の段かページに移します（ただし段全体より高い囲みは、はみ出す代わりに分割されます）。`keepTogether: false`のスタイルでは、ブロックの間や行の間で分割でき、切れ目の両側に少なくとも`splitMinLines`行のテキスト（または図、表、別行立て数式、入れ子の囲み）を残します（段落やリスト項目の途中で切る場合は、さらにその行の少なくとも`layout.boxChildSplitMinLines`行を両側に残します。既定は2行で、`splitMinLines`のほうが小さければそちらです。章に囲みを含む、1.5より前に保存した本は、1.4の切り方である1で読み込みます）。2つめ以降の部分はアイコンなしで始まります（テキストはアイコンの列の位置を保ちます）。タイトルも、スタイルが繰り返さない限り付きません（`repeatTitle`：「要点（続き）」）。スタイルで、続きがある各部分の下に「続く」の目印を付けることもできます（`continuesMarkerEnabled`）。[設定 › 分割された囲みの目印](/ja/docs/configuration#分割された囲みの目印)を参照してください。全幅の囲み（`span="page"`）は、ページを段の帯に分けます。`span="side"`の囲みは本文の流れを離れて、1段半のレイアウト（`layout.sideColumnRole: 'floats'`）にあるフロート専用のサイド段に入り、中断したテキストの横に積み重なります。そうした段がない場合は、段幅の囲みとして組まれます。`placement="fixed"`の囲みは流れを離れてページ上の座標に固定され（章の最終ページの左下隅に置く自己評価のバッジなど）、重なる段はその領域を譲ります。フロートの囲み（`placement="top"`／`"bottom"`）は、現れた位置で流れを離れ、その位置以降で最初に空いている帯（ページの下端、または次のページの上端か下端）に入り、そのあとのテキストは元のページを埋めます。`floatBarrier: true`のスタイル（典型的には章末の「要点」の囲み）は、その囲みを**フロートの区切り**（float barrier）にします。その前で参照された図や表はすべて、囲みより前（そのページの空き位置、または囲みより先に始まるページ）に置かれるので、章の終わりを越えて流れ出るフロートはありません。未知の`:::name`フェンスはコンテナーではなく、その行は未知のディレクティブとまったく同じく、テキストとして扱います。

`:::part`のフェンスは、`number`（印刷したいとおりに書きます。`"I"`、`"IV"`、`"3"`など。デザインで書式を変えられるよう、解析もされます）と`title`を受け付けます。どちらも省略できます。3つめの属性`palette="band=#hex"`（コンマ区切りの複数の`id=#hex`の組）は、そのパレットidにリンクしたデザインの色（柱、扉の帯、部のデザイン）と、それと同じ基本値を共有する本文の流れの色（見出し、太字、参照、行頭記号、キャプション、表、囲み、チップ）を、その部とそれに続く章について、次の部まで塗り替えます。[設定 › 部](/ja/docs/configuration#部)を参照してください。このコンテナーは必ず独自のページを始めます。前に設定した奇偶の改ページを入れ、`parts.margins`の余白で本文を1段にし、扉デザインをページ全体に描き、閉じるフェンスのあとにもう一度改ページを入れます。本文（通常はその部にまとめる章の一覧で、何もないこともあります）は`parts.bodyStyle`で組みます。

```
:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
:::

# The lantern and its parts
```

見出しの設定が既定のままなら、これで古典的な並びになります。部扉が右ページ、その裏の左ページが白、章が次の右ページです。このページは`role: 'part'`として報告されるので、ヘッダーやフッターはそのページを飛ばすことができます。また、以降のすべてのページで、`{partTitle}`／`{partNumber}`が現在の部に解決されます。設定リファレンスの[部](/ja/docs/configuration#部)を参照してください。

フェンスの前に空行は要りません。段落、リスト、引用ブロックの直下にくっつけて書いた開始や終了のフェンスは、そのブロックを終わらせます。文書の終わりで開いたままのコンテナーはそこで自動的に閉じられ、Sandboxは開始行を指して**閉じられていないコンテナー**の警告を出します。コンテナーが開いていないところにある余分な`:::`は、黙って捨てられることはなく、目に見える段落としてテキストに残ります。

### `:::columns`

`:::callout`の中では、`:::columns{count=2}`…`:::`のグループが、フェンスの間のブロックを同じ幅の`count`段（間隔はスタイルの`columnGap`）に組みます。ひと続きのブロックは、段の高さが最もそろう位置で切られます。切る位置はブロックの間か、段落やリスト項目の行の間で、後者の場合は残りが行頭記号なしで次の段の先頭に続きます。囲みは最も高い段に合わせて伸びます。グループのあとのブロックは、また全幅に戻ります。囲みの外ではフェンスは無視され、ブロックは通常どおり流れます。`breaks`属性は、高さをそろえる代わりに段の開始位置を固定します。`:::columns{count=2 breaks="4"}`はグループの4つめのブロックで2段めを始め（段がもっと多ければコンマ区切りのリストで指定）、段落の途中では切りません。図の段の横にテキストの段を置く場合などです。

```md
:::callout{type="summary"}
:::columns{count=2}
- Every element is one kind of atom.
- Electrons live in orbitals.
- A bond shares or transfers electrons.
:::
:::
```

**`breaks`の数え方**。`breaks`は、グループのブロックを順に数えます。対象は段落、リスト項目（1項目で1ブロック）、別行立て数式、図、表で、入れ子の`:::callout`は中にいくつ含んでいても1ブロックと数えます。ディレクティブはブロックではないので、2つの連の間に`:::space`があっても数はずれません。2未満の数、グループの最後のブロックを越える数、直前の区切りより後ろでない数は無視します。グループの中では、囲みのほかの場所と同じく`:::space`で2つのブロックを離せますが、グループの先頭と、各段の先頭（`breaks`の位置や、高さをそろえるための切れ目）では消えます。グループを下げて始めたいときは、空きを`:::columns`フェンスの前に置きます。したがって、同じ空きを持つ2つの段は、連ごとに高さがそろいます。

```md
:::callout{type="verse"}
:::columns{count=2 breaks="4"}
The lamp is lit at dusk,

and trimmed before the dawn.

:::space

The keeper sleeps by day.

La lámpara se enciende al anochecer,

y se despabila antes del alba.

:::space

El farero duerme de día.
:::
:::
```

この例では、4つめのブロック「La lámpara…」が2段めを始めます。2つの`:::space`行は数えられず、両方の段に同じ空きを残します。

`:::callout`のフェンスは`label="…"`も受け付けます。`label`タブを持つスタイルが、囲みの上の角に出力するテキストです（`:::callout{type="box" label="BOX 1-1" title="The octet rule"}`）。

ほかの囲みの中にある`:::callout`は、それ自体が1つの囲みになります。たとえば解答欄を含む演習カードです。独自のスタイル（背景、枠線、角の丸み、パディング、タイトル、アイコン）を持ち、外側の囲みの内側の幅いっぱいに置かれ、ほかのブロックとともに積み重なります。入れ子の囲みは常に親の中を流れるので、`span`と`placement`は無視します。各フェンスは、まだ開いているいちばん内側の囲みを閉じます。

```md
:::callout{type="card"}
The statement of the exercise.

:::callout{type="answer"}
A white answer box with its own border and padding.
:::

:::callout{type="answer"}
A second answer box.
:::
:::
```

外側の囲みが段やページをまたいで分割されるとき（`keepTogether: false`の場合や、段より高い場合）、入れ子の囲みは、自身のスタイルも分割を許さない限り、全体が次の断片に移ります。どの断片も、含んでいる枠を描き直します。続きの入れ子の囲みはアイコンを省き、スタイルが繰り返さない限り（`repeatTitle`）タイトルも省きます。

### `:::paper`

本では、ひと続きのページで用紙を変えることがあります。非塗工紙に刷った本の中にある、グロスコート紙の図版の部分、厚紙の差し込み、数枚の色紙などです。その内容を`:::paper`コンテナーで囲みます。

```md
:::paper{type=coatedGloss grammage=130}
## Plates
::resource{id="plate-1"}
::resource{id="plate-2"}
:::
```

用紙は紙1枚全体に及ぶので、フェンスの中の内容は新しいページから始まり、閉じる`:::`のあとに続く内容も新しいページから始まります。文書の最後で終わる場合は、そのあとに白ページを残しません。この範囲の中で引用された図や表は、範囲が閉じる前に配置されます。コンテナーの中の内容を組んだすべてのページは、レイアウトに用紙の情報（`VDTPage.paper`。属性はフェンスに書かれたとおり）を持ち、範囲外のページは何も持ちません。Folioビューアーはこれを読み取り、その丁を用紙の色、表面、厚さ、こわさで描きます。Canvas、PDF、HTMLの出力はこれを無視し、ページはほかと同じように組まれ、印刷されます。

属性は`folio.paper`の設定と同じで、すべて省略できます。フェンスで省いた属性は文書の用紙に従い、それもなければ用紙の種類の既定値に従います。

| 属性 | 値 |
| --- | --- |
| `type` | 用紙の種類：`uncoated`、`bookWove`、`coatedMatte`、`coatedSilk`、`coatedGloss`、`bible`、`newsprint`、`cardStock`、`board`。下の属性の既定値を決めます。 |
| `grammage` | 坪量（g/m²）。0より大きい数値です。重い紙ほど厚く、こわく、不透明になります。 |
| `bulk` | 重量あたりの厚さ（cm³/g）。0より大きい数値です（µm単位の紙厚 = 坪量 × bulk）。 |
| `finish` | 表面の仕上げ：`auto`、`uncoated`、`matte`、`silk`、`gloss`。 |
| `texture` | 表面の凹凸：`auto`、`smooth`、`vellum`、`wove`、`laid`、`linen`、`felt`。 |
| `textureStrength` | テクスチャーの見え方の強さ。0から2まで。 |
| `shade` | 用紙の色：`#rgb`、`#rrggbb`、または`colorPalette`の項目のid。 |
| `showThrough` | `true`または`false`：裏のページがかすかに透けて見えるかどうか。値のない`showThrough`は`true`を意味します。 |

別の用紙の範囲の中にある`:::paper`は、自身が設定した属性だけを上書きし、やはり改ページで始まり改ページで終わります。`:::callout`の中ではフェンスは無視します。エンジンが読み取れない値は捨てられ、Sandboxに**用紙の無効な属性**の警告として表示されます（文書の`contentWarnings`の`paperAttributeInvalid`）。

### `:::pagebreak`

このディレクティブは、それだけでは奇偶を強制しません。影響するのは次のブロックのレイアウトだけです。序文を終える、献辞を独立したページに置く、節の終わりを示す、といった用途に使います。同じ位置で改ページとノンブルの振り直しの両方が必要なときは、`:::pagebreak`のあとに`:::numbering`を続けます。番号の切り替えは、`:::pagebreak`が作った新しいページに適用されます。

まだ空のページでの改ページは何もしないので、白ページを加えることはありません。また、直後の見出しの`breakBefore`（レベル1には既定で設定されています）の代わりになるわけでもありません。見出しは自身の奇偶をそのまま適用するので、ディレクティブが始めたページのあとに白ページが加わることがあります。見出しをちょうどその位置から始めるには、見出しの改ページをオフにします（**設定 → 見出しスタイル**を参照）。ページを埋める表紙の見出しのあとでは、改ページは省略できます。表紙は1段でも多段でもすでにそのページの残りを確保しているので、直後に`:::pagebreak`があっても害はありません。改ページが必要なのは、デザインがページの下端まで届かない表紙のあとで、それでも次のページから本文を始めたいときだけです（**設定 → 確保する高さ**を参照）。

```md
The old chapter ends here.

:::pagebreak{parity="odd"}

# A new chapter
```

フラグ`center`（`:::pagebreak{center}`、`center=false`で解除）は、改ページが始めたページのテキストを、版面の天と地の間の中央に置きます。縦組みではページの左右方向の中央で、日本語の部扉や献辞の「ページの左右中央」にあたります。フロート、注、柱はそのまま残り、すでにいっぱいのページは変更しません。このフラグはページを終わらせないので、別の`:::pagebreak`で閉じます。

```md
:::pagebreak{center}

# 上　先生と私

:::pagebreak
```

#### 奇偶の属性

`parity`属性は、`headings.levels[*].breakBefore.parity`と同じ5つの値を受け付けます。

- `'any'`：既定値。奇偶の制約はなく、単に新しいページを始めます。
- `'odd'`／`'even'`：新しいページを見開きの指定した側で始めます。本来の次のページが逆側にあるときにだけ、白ページを1ページ挿入します。
- `'always-odd'`／`'always-even'`：前の内容と新しいページの間に少なくとも1ページの必須の区切りの白ページを入れ、そのうえで奇偶を合わせます。区切りの白ページは**前の**章に属し、それ以上の奇偶合わせの白ページはあとに続くものに属します。

#### 白ページの帰属

`:::pagebreak`（および`breakBefore`）が入れる2種類の白ページは、`VDTPage`モデルで区別されます。

- `blankForParity: true`：奇偶の制約を満たすために挿入した白ページ。`{chapterTitle}`の柱では、このページは**これから始まる**章のタイトルを持ちます。この白ページは、その章を正しい奇偶に送るためだけにあるからです。
- `blankForForce: true`：`'always-*'`モードの必須の先頭の区切り。**前の**章に属します。次の章のための奇偶合わせではなく、意図して設けた章末の間です。

同じ2つの規則により、白ページはスタイル付きの節の柱とパレットを受け継ぎます。[設定 › 見出しスタイル](/ja/docs/configuration#見出しスタイル)を参照してください。

#### 文書冒頭の例外

`:::pagebreak`が文書のいちばん最初の要素である場合（または`breakBefore`を持つ見出しが改ページを引き込む場合）、最初のページがまだ空のうちは奇偶の適用を省きます。次のブロックは、要求された奇偶にかかわらず、書いたとおり1ページめに置かれ、先頭に余計な白ページはできません。

### `:::numbering`

`:::numbering`は、文書の途中でページのカウンターを振り直す方法です。本での典型的な例を示します。

```md
---
title: "A Book With Front Matter"
---

# Preface

…

:::pagebreak{parity="odd"}
:::numbering{format="decimal" startAt=1}

# Chapter 1
```

序文のページには`i`、`ii`、`iii`…とラベルが付き、最初の章はラベル`1`の右ページから始まります。

書式だけの変更（`startAt`なし）では、カウンターは続きます。たとえば`lower-alpha`から`upper-alpha`に、振り直さずに切り替えるときに便利です。

`format`には、番号書式のどの表記でも使えます。`lower-roman`の代わりに`roman-lower`や`i`、`decimal`の代わりに`arabic`、`japanese-informal`や`hiragana`の代わりに`一`や`あ`が使えます（[設定 › 番号書式の表記](/ja/docs/configuration#番号書式の表記)を参照）。どれにも当たらない値では書式は変わらず、Sandboxが警告します。

### `:::space`

`:::space`は、2つのブロックの間に縦の空きを入れます。結びの行を上のテキストから離す、エピグラフや署名を少し下げる、2つのテキストの間に場面転換の空き（space break）を入れる、といった用途です。Markdownの余分な空行ではこうはなりません。どのMarkdownとも同じく、空行がいくつ続いても段落の区切り1つにすぎないからです。そのため、エディターやフォーマッターが空白を足したり削ったりしても、文書のレイアウトは変わりません。

```md
The last paragraph of the scene.

:::space

A new scene begins one line lower.

:::space{lines=2}

Two lines lower still.
```

- **`lines`**：空きの量を本文の行数（ベースライングリッド）で指定します。既定値は`1`です。整数なら本文のどの行もグリッドに乗ったままなので、ページ全体で段どうしの行がそろいます。小数（`lines=0.5`）は正確に守りますが、その代わり、次にグリッドに吸着するブロックまでそのそろいは崩れます。0より大きく20以下の数値でない値は1行として扱い、Sandboxが警告します（**スペースの無効な大きさ**）。
- **加算されます**。空きは、2つのブロックをすでに隔てているマージン（見出しの上マージン、リストの下マージンなど）に加わり、その中に吸収されることはありません。`:::space`を2行続けると2行分になります。
- **区切りでは捨てられます**。LaTeXの`\vspace`と同じく、段やページの先頭では消えるので、ページが空きで始まることはありません。段の下端で収まらないときは、その段を終えるだけで、残りを次に持ち越しません。
- **直後の段落は字下げなしになります**。`bodyText.indentAfterHeading`がオフのとき、`:::space`の直後の段落は、見出しのあとと同じく1行目の字下げを失います。空行のあとに再開するテキストの通例です。
- **囲みの中**（または`:::columns`グループの中）でも同じように囲みの子要素を隔て、囲み自身の本文の行で測ります。囲みの最初のブロックより前では、段の先頭と同じく捨てられます（パディングがすでに内容を枠から離しているため）。ただし次の2つの場合には、その分の空きを作ります。囲みのタイトルの直下と、ほかに何も含まない囲み（解答欄や書き込み用の空きなど、行数で大きさを決めるもの）です。`:::columns`グループの先頭、その各段の先頭、および分割された囲みのうち次の段やページに続く部分の先頭では、常に消えます。`:::paragraphs`コンテナーの中では、本文の段落の間と同じように働きます。
- **次との分離禁止**（keep-with-next）でも数えます。`:::space`が続く見出しは、空きとテキストの最初の数行がその下に収まらなければ次に移ります。

ワークシートの解答欄は、空きだけを内容とする囲みです。タイトルに問題を置き、その下に4行分の空きを取ります。

```md
:::callout{type="answer" title="1. Name the three parts of the lantern."}
:::space{lines=4}
:::
```

空きではなく固定の区切りが必要なら、`:::columnbreak`か`:::pagebreak`を使います。

### `:::verse`

古典アラビア語の配置による詩（カスィーダ（qaṣīda）、キトア（qiṭʿa））です。各詩行、つまりベイト（bayt）を2つの半分に分けて1行に組み、サドル（ṣadr）を開始側（アラビア語では右）に、アジュズ（ʿajuz）を終了側に置き、その間に空きを入れます。1行に1ベイトを書き、半句を`||`で区切ります（Wikisourceのテキストのように、両側にスペースを置いた`\\`も使えます）。区切りのない行は1つの半句で、詩の中央に置きます。

```md
فأنشد يقول:

:::verse
يَا حُرْقَةَ الدَّهْرِ كُفِّي || إِنْ لَمْ تَكُفِّي فَعِفِّي
فَلَا بِحَظِّيَ أُعْطِي || وَلَا بِصَنْعَةِ كَفِّي
:::
```

- **1つの幅**。詩のすべての半句を1つの幅に組むので、どのサドルも同じ縦の線から始まり、どのアジュズも別の縦の線で終わり、韻の文字が詩の下までそろいます。幅は最も広い半句の幅で、行長の半分から空きを引いた値が上限です。`width`で設定できます（`width=55mm`）。各半句はまずカシーダ（kashida）でその幅まで伸ばし（詩は散文より大きく伸ばします。`bodyText.kashidaMaxLength`の2倍）、次に語間で合わせます。1語だけの半句が幅を満たせないときは、残りを空きの側に残します。
- **空き**は既定で2emです。`gap`で設定します（`gap=3em`。数値だけならem単位）。`ornament`は空きの中央に記号を出力します（`ornament="٭"`）。この記号はテキストの一部ではありません。
- **広すぎる場合**。共通の幅より広い半句は、まず語間を`bodyText.minWordSpacing`まで詰めます。それでも収まらなければ、そのベイトを段違いに組みます。サドルを開始側にそろえて1行に置き、アジュズを終了側にそろえて次の行に置きます。
- **配置**。詩は段の中央に置きます。`align=start`で開始側にそろえます。ベイトが段やページの間で分割されることはなく、詩は段落のオーファンとウィドウの規則に従います（3ベイト以下の詩は分割しません）。詩を導く直前の段落（«فأنشد يقول:»）は、最後の行を最初のベイトから切り離しません。
- **書体**。詩は本文の書体、サイズ、行送りを使います。`style`で段落スタイルを指定でき（`style="verse"`）、母音記号付きの詩に、ハラカート（harakat）が必要とする追加の行送りを与えるにはこれを使います。`dir=ltr`や`dir=rtl`で、ほかのブロックと同じく方向を設定します。左から右の本の中のラテン文字の詩では、サドルが左になります。

詩のプレーンテキストでは、半句とベイトが（タブと改行で）区切られたまま残るので、検索やコピーした文章でも書いたとおりに読めます。カシーダと飾り記号は含みません。

### `:::toc`

`:::toc`は、その位置に目次を出力します。通常のブロックに展開され（`toc.levels`に挙げたレベル（既定ではレベル1）の見出し1つにつき1つと、`:::part`1つにつき1つ）、目次はほかのテキストと同じく段やページをまたいで流れます。項目をクリックすると、ディレクティブの行に移動します。項目には、見出しの番号（`numberingTemplate`の出力、なければ章の序数）、タイトル、点線のリーダー、見出しが始まるページのラベルが並びます。`toc.subtitle`を有効にすると、章の`{author="…"}`などの見出しの属性を2行めに表示します。部は`toc.parts.design`でデザインし、部自身の`palette`で色付けした独自の行になります。スタイルに`numbered: false`がある見出しは、番号なしで載ります。見出しに`{toc="false"}`を付けると目次から外れます（通常は目次自身の見出し）。

```md
# Contents {style="front-matter" toc="false"}

:::toc
```

ノンブルは、文書が実際に出力するものです。単独で組む文書は、ラベルが動かなくなるまで、前回のラベルを使ってレイアウトをやり直します。前付けのあとで番号を振り直す場合（上の`:::numbering`の例）は、1回余分に組めば落ち着きます。単独で組む章（Sandboxのプレビュー）は、代わりにホストから本全体のアウトラインを受け取ります。設定リファレンスの[目次](/ja/docs/configuration#目次)を参照してください。

### `:::index`

`:::index`は、その位置に索引を出力します。本全体で`:index[…]`や`:index{term="…"}`で印を付けた語を、テキストの移動に追随するページとともに並べます。印の付け方とあわせて、[索引](#索引)で説明します。

```md
# Index {style="index"}

:::index
```

### タイトル内の改行

見出しの中（または部の`title`属性の中）に`\\`を書くと、タイトルをタイトルとして表示する場所で改行を強制できます。段の中の見出しはそのまま続けてそこにスペースを表示し、扉デザインの`{titleText}`はその位置で行を分けます（テキスト要素の`overflow`のどのモードでも同じです）。柱、`{chapterTitle}`、`{partTitle}`、PDFのアウトラインでは、タイトルは常に1行で描かれます。中国語や日本語では、その文字体系の2文字の間の改行は全角スペースとして読まれます（対句のタイトル）。どちらかが数字やラテン文字に接する場合（`关于举办 \\ 2026年…`）、ページでは漢字とラテン文字の間のアキを入れ、PDFのしおりと文書タイトルでは、中国語の普通の書き方と同じく、2つの半分を何も挟まずにつなぎます。

```md
# Concepts of health and illness. \\ Community health {author="I. Zango Martín"}
```

## インライン書式

インライン書式は、どのテキストブロック（見出し、段落、引用ブロック、リスト項目）の中でも認識されます。見出しでは`headings.inlineMarks`に従い、既定ではオンです。見出しのイタリック、太字、上付き・下付き、スモールキャピタル、リンクは段落と同じように印刷され、イタリックの見出しの中でイタリックにした部分は立体（ローマン体）で組まれます。オフにすると記号は取り除かれ、見出しはその見出し自体のスタイルで印刷されます。postext 1.4以前に保存された設定で、見出しに書式記号を含むものはこの扱いで読み込まれます（[設定 › 見出し](/ja/docs/configuration#見出し)を参照）。見出しデザインの`{titleText}`は、どちらの場合も書式のないテキストとして印刷されます。

> **図: インライン書式の一覧**
> 太字、イタリック、太字イタリック、インラインコード、リンクについて、Markdownと描画結果を比べます。
>
> *左がMarkdown、右が描画結果です。*

| 書式 | 構文 | 説明 |
| --- | --- | --- |
| 太字 | `**bold**`または`__bold__` | `bodyText.boldFontWeight`で描画されます。`bodyText.boldColor`を指定すると、太字部分の色を本文の既定色から変えられます。 |
| イタリック | `*italic*`または`_italic_` | 現在のフォントファミリーのイタリックで描画されます。`bodyText.italicColor`を指定すると、イタリック部分の色を本文の既定色から変えられます。アンダースコアが強調を示すのは、CommonMarkと同じく語の境界にあるときだけです。2つの文字や数字にはさまれたもの（`snake_case_name`、URLの`SR_AIR_EN.pdf`）はテキストのままです（`__bold__`も同様）。語の途中ではアスタリスクを使います（`un*believ*able`）。中国語、日本語、韓国語の文字はここでは文字として数えません。これらの表記体系には語間スペースがないためです。`中文_イタリック_中文`と`中文__粗体__中文`はイタリックと太字になります。太字にならない`__`がイタリックに変わることはなく、`foo__bar__baz`はテキストのままです。 |
| 太字イタリック | `***both***`または`___both___` | 両方の指定が組み合わされます。 |
| 上付き | `^text^` | 文字サイズの58%で組み、文字サイズの3分の1だけ持ち上げます。指数（`10^-8^`）やイオンの電荷（`Na^+^`）に使います。記号で囲む部分は、スペース以外の文字で始まりスペース以外の文字で終わる必要があります。文中に単独で現れるキャレットはそのまま印刷され、顔文字の`^_^`と`^o^`もそのままです（`n.^o^`と`1^o^`は上付きになります）。 |
| 下付き | `~text~` | サイズは同じで、文字サイズの0.15だけ下げるので、ディセンダーの範囲に収まります。化学の添え字（`H~2~O`、`p<em>K</em>~a~`）に使います。両側に数字があるチルダは範囲を表すものとしてそのまま印刷されます（`3~5 days`、`需要3~5天`）。2つの中国語の語のあいだにあるチルダも下付きを開かず、そのまま印刷されます（`周一~周五`、`北京~上海`）。ただし、下付きは中国語の文字の前で閉じることができます（`F~合~等于`）。太字やイタリックと組み合わせられます（`**H~2~O**`）。下付きと上付きをあいだに何もはさまずに続けて書くと、数式のように上下に重ねて組まれます。`*T*~0~^2^`は、どちらを先に書いても2を0の上に置きます。このとき下付きは上付きとぶつからないよう文字サイズの0.25だけ下げられ、組の幅は広いほうの幅になります。あいだにスペースや文字があると、2つは順に並べて組まれます。単語結合子（U+2060）をはさんでも同じで、その場合はあいだに何も見えません。重ねた組が改行で分かれることはありません。行に収まらない語は、その組の前で改行されます。 |
| スモールキャピタル | `:smallcaps[text]` | 小文字を文字サイズの70%の大文字として組みます。戯曲の登場人物名や、本文中の頭字語に使います。中や外側にほかの書式を組み合わせられます。[スモールキャピタル](https://postext.dev/ja/docs/document-format#スモールキャピタル)を参照してください。 |
| 縦組みでの文字の向き | `:tcy[12]`、`:upright[GDP]`、`:sideways[12]` | 縦組みで、1つの正立したマスにまとめる（縦中横）、1文字ずつそれぞれのマスに正立させる、または範囲全体を横倒しにする指定です。横組みでは効果がありません。[縦組みでの文字の向き](https://postext.dev/ja/docs/document-format#縦組みでの文字の向き)を参照してください。 |
| 中国語の記号 | `:dots[不可]`、`:name[賈寶玉]`、`:book[石頭記]` | 圏点（着重号）、固有名詞の傍線（专名号）、書名号（书名号。`cjk.bookTitleMark`に従い《》または波線）です。テキストは書いたとおりに残ります。[中国語の記号、ルビ、割注](https://postext.dev/ja/docs/document-format#中国語の記号ルビ割注)を参照してください。 |
| ルビ | `:ruby[紅樓]{rt="hóng lóu"}`または`{紅樓\|hóng\|lóu}` | 親文字の上（または横）にピンインや注音のよみを付けます。簡易形式は親文字に漢字、仮名、注音字母が含まれる場合だけ有効なので、`{x\|x>0}`はテキストのままです。 |
| 割注 | `:warichu[note]{open="〔" close="〕"}` | 行の中に半分のサイズの2行で組む注（双行夹注）です。行やページをまたいで分割されます。 |
| インラインコード | ```code``` | バッククォートは取り除かれ、その範囲は書いたとおりのプレーンテキストとして描画されます。中にある`:ref{…}`、チップ、数式、リンク、強調記号はそのまま印刷されるので、本文で構文そのものを示すときに使えます。コード専用のスタイルはロードマップにあります。 |
| エスケープ | `\*`、`\_`、`\^`、`\~`、``\```、`\$` | バックスラッシュを付けると、範囲を開く代わりにその記号文字そのものを組みます。表の注のアスタリスク（`\* pOH = −log [OH^−^]`）、文字としてのキャレット、数式を開かないドル記号などです。本文、チップ、キャプション、セル、注で有効です（postext 1.4までは、キャプション、セル、注、チップで`\$`のバックスラッシュも印刷されていました）。 |
| ノーブレークスペース | 文字そのもの：U+00A0、U+202F、U+2007 | 前後の語を結びつけ、そのあいだで改行されないようにします。数値と単位（37 °C）、ページ参照（p. 12）、3桁区切り（225 000）などに使います。ノーブレークスペース（U+00A0）、狭いノーブレークスペース（U+202F）、数字幅スペース（U+2007）はいずれも、本文、キャプション、セル、囲み、柱で語を結びつけ、それぞれ固有の幅を保ちます。両端そろえで伸びるのは語間スペースだけです。多くの書体には狭いノーブレークスペースや数字幅スペースのグリフがありません。その場合はブラウザーと同じく、Canvas、HTML、PDFのいずれでも、語間スペースの半分と数字1つの幅で組まれます。U+00A0はほぼすべての書体にあるので、これが安全な選択です。こうして結びつけたまとまりが行全体より広い場合は、語の途中ではなく最後のノーブレークスペースで改行されます。単語結合子（U+2060）は幅を取らずに結びつけます。文字そのものを入力してください。` `のようなHTMLエンティティは書いたとおりに印刷されます。[改行されない箇所](/ja/docs/justification#行を分割しない箇所)を参照してください。 |
| リンク | `[text](https://…)` | 表示テキストは流れの中に残り、リンクがない場合とまったく同じに組まれます。URLにより、HTMLとPDFの出力ではその語が有効なリンクになります。[リンク](https://postext.dev/ja/docs/document-format#リンク)を参照してください。 |
| 画像 | `![alt](src)` | インラインの画像Markdownはテキストから**取り除かれます**。組版エンジンが`resourcePlacement`の規則に従って配置できるよう、画像は`PostextContent.resources`で宣言する必要があります。 |
| チップ | `:chip[text]` | 1つの単位として折り返される、枠付きのテキストです。語群、キー、タグなどに使います。スタイルは`chipStyles`で指定します。[インラインのチップ](https://postext.dev/ja/docs/document-format#インラインのチップ)を参照してください。 |
| インライン数式 | `$…$` | 前後のテキストとともに流れるLaTeXの数式です。たとえば`$e^{i\pi}+1=0$`。MathJaxで組まれ、どのバックエンドでもベクターパスとして描画されます。ドル記号そのものには`\\$`を使います。拡大縮小、別行立て（`$$ … $$`）の形式、エラーの扱いは[数式](https://postext.dev/ja/docs/document-format#数式)で説明します。 |

### リンク

Markdownのリンク`[text](url)`は、リンクがない場合とまったく同じにテキストを流れの中に組みます。リンクによって改行位置、スペース、色が変わることはありません。URLは、それをたどれる出力のために保持されます。

- **HTML**（`renderToHtml`）：リンクの語は`<a href="…" rel="noopener noreferrer">`で囲まれ、テキストの色を受け継ぎ、下線は付きません。アンカーは、1行の中で連続するリンクの語ごとに1つです。
- **PDF**（`postext-pdf`）：1行の中で連続するリンクの語が、それぞれクリックできるURIリンク注釈になります。タグ付きPDFでは、リンクの語をテキストとする`Link`要素になります。
- **Canvas**：Canvasにはクリックできる面がないので、プレーンテキストとして描画されます。

```markdown
Read the [configuration guide](https://postext.dev/en/docs/configuration "Configuration")
or write to [the team](mailto:team@example.com).
```

- リンク先にはタイトルを付けられますが、無視されます（`[text](https://example.com "Title")`）。リンク先を山かっこで囲むこともでき、その場合スペースは`%20`になります（`[text](<https://example.com/a b>)`）。
- 保持されるのは安全なリンク先だけです。`http:`、`https:`、`mailto:`、`tel:`、`ftp:`と相対URL（`../guide`、`#top`）です。それ以外のスキーム（`javascript:`、`data:`、`file:`…）では、テキストはリンクなしで組まれます。PDFがリンクにするのは絶対URLだけです。
- CommonMarkと同じく、かっこの対応がとれていればリンク先にかっこを含められます。`[photo](https://commons.wikimedia.org/wiki/File:Bike_(Unsplash).jpg)`はURL全体をリンクにします。バックスラッシュは文字をエスケープします（`\(`、`\_`）。かっこの対応がとれていないと、リンク先は最初の`)`で終わり、テキストはリンクなしで組まれます。単独のかっこは`%28`または`%29`にエンコードしてください。山かっこで囲んでいなければ、スペースでもリンク先は終わります。
- リンクのテキストにくっついた語は、そのリンクを共有します。`see [the site](https://example.com).`では、ピリオドもクリックできる範囲に含まれます。
- リンクのテキストには強調を含められ（`[**bold** words](…)`）、リンクを強調の中に置くこともできます（`**[words](…)**`）。
- リンクは段落、リスト項目、引用ブロック、囲み、キャプション、注、表のセルで使え、見出しでも`headings.inlineMarks`がオン（既定）のあいだは使えます。見出しから作られる柱、アウトライン、目次の行はテキストだけを使い、`:chip[…]`のテキストも同様です。
- 参照形式のリンク（`[text][id]`）と自動リンク（`<https://…>`）は認識されません（[対応していない記法](#対応していない記法)を参照）。

VDTでは、リンク先はリンクの付いた各セグメントに`VDTLineSegment.href`として入ります。パーサーはスパンのリンクをテキスト上の範囲として`InlineSpan.links`に保持し、リンクのためにスパンを分割することはありません。そのため、リンクがレイアウトを変えることはありません。

### インラインのチップ

`:chip[text]`は`text`を、行とともに流れる枠（角の丸い、色付きの「チップ」）の中に組みます。語群や分類問題の語、キーボードのキー、タグに使います。`:chip[text]{style="key"}`は`chipStyles`から名前付きのスタイルを選びます（設定リファレンスを参照）。`style`がない場合や、どのスタイルも宣言していないidを指定した場合、チップは最初のスタイルを使います（設定にスタイルがなければ組み込みの`chip`スタイル。不明なidにはSandboxが警告を出します）。

```markdown
Classify: :chip[battery] :chip[cable] :chip[switch] :chip[bulb]

Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"} to copy.
```

- **1つの単位**：チップの内部で改行やハイフネーションが行われることはなく、改行はチップのあいだ、前後の語間スペースで行われます。行全体より広いチップは、分割されずに行からはみ出します。
- **幅**：送り幅は、テキストに左右両側の水平パディングと輪郭線を加えたものです。両端そろえで伸びるのは語間スペースだけで、チップの内部は伸びません。スタイルの`gap`は、スペースをはさんで隣り合う語やチップと枠とのあいだに確保する最小の間隔です。それより狭いスペースは広げられます（行の端や、`:chip[a],`のようにくっついた句読点の前では広げません）。
- **高さ**：枠はベースラインを中心とした帯で、チップのサイズで上に0.8 em、下に0.25 emあり、そこに垂直パディングと輪郭線が加わります。垂直パディングは行ボックスの外側に描かれ、行の高さを変えないので、ベースライングリッドは保たれます。行送りより高い枠は、上下の行のチップと重なることがあります。異なる行の2つのチップが重なると、Sandboxは「チップが隣の行に接触」と警告するので、パディング、輪郭線、サイズを小さくして対処できます。
- **テキスト**：チップのテキストには独自のインライン書式（`:chip[**bold** word]`、`:chip[x^2^]`）と外側の強調（`**:chip[a]**`）が効きます。スタイルではファミリー、サイズ、色、太字、イタリックを指定できます。中で角かっこそのものを書くには`\]`とします。チップの中の参照、色見本（スウォッチ）、数式はそのまま印刷され、`\$`はドル記号を印刷します（postext 1.4まではバックスラッシュも印刷されていました）。
- **空のチップ**：スペースだけのチップ（`:chip[ ]`、ノーブレークスペースを含む）は空の枠になり、解答欄や終了記号に使えます。幅はスタイルの水平パディングと輪郭線の分、高さは語の入ったチップと同じです。空欄の大きさはスタイルの`paddingX`で決めます（`:chip[ ]{style="blank"}`）。角かっこのあいだに何もない`:chip[]`は、テキストのまま残ります。
- **使える場所**：段落、リスト項目、引用ブロック、囲み、表のセル、キャプション、注。見出しでは`:chip[…]`はテキストのまま残ります。
- **出力**：Canvas、HTML、PDFは枠を描き、語を実際のテキストとして組みます。HTMLでは選択でき、PDFでは抽出でき、読み順どおりに並びます（タグ付きPDFでは、枠はレイアウト用のアーティファクトで、語は段落に属します）。

### スモールキャピタル

`:smallcaps[text]`は`text`をスモールキャピタルで組みます。戯曲の登場人物名、本文中の頭字語、章の冒頭の数語などに使います。小文字は文字サイズの70%の大文字として組まれ、大文字、数字、句読点は元のサイズのままです。そのため`:smallcaps[Hamlet]`は、元のサイズのHに続けてスモールキャピタルのAMLETを印刷します。

```markdown
Enter :smallcaps[Hamlet] and :smallcaps[Horatio], reading.

The :smallcaps[unesco] report and the :smallcaps[who] guidelines.
```

- **合成**：スモールキャピタルは書体自身の大文字から作られ、Canvas、HTML、PDFで同じ方法で描かれるので、テキストの計測と改行はどこでも同じになります。書体本来のスモールキャピタル（OpenTypeの`smcp`機能）は使われません。それを使うには、段落スタイルでスモールキャピタルのファミリー（たとえば名前が「SC」で終わるファミリー）を指定してください。
- **書式**：テキストには独自のインライン書式（`:smallcaps[**Ophelia**]`）と外側の強調（`*:smallcaps[Act I]*`）が効きます。中で角かっこそのものを書くには`\]`とします。中の参照やチップもスモールキャピタルで組まれ、参照はHTMLとPDFで1つのリンクのままです。数式はスモールキャピタルになりません。
- **改行**：語は通常どおり折り返され、ハイフネーションされます。ハイフネーションは各語を元の大文字・小文字のまま読みます。
- **使える場所**：段落、リスト項目、引用ブロック、囲み、表のセル、キャプション、注、そして`headings.inlineMarks`がオン（既定）のあいだは見出し。オフにすると見出しからマークアップが取り除かれ、テキストは書いたとおりに印刷されます。
- **段落全体**：`smallCaps: true`を指定した段落スタイルや囲みの本文は、すべてのテキストをこの方法で組みます（[段落スタイル](/ja/docs/configuration#段落スタイル)を参照）。
- **テキスト**：Canvas、HTML、PDFは描いたとおりの文字を保持します。`:smallcaps[Hamlet]`をコピーすると「HAMLET」になります。

### 縦組みでの文字の向き

縦組み（`layout.writingMode: 'vertical-rl'`）では、漢字は正立し、ラテン文字の語や長い数字は横倒しになります。2桁以下の数字は1つのマスに正立しますが、ラテン文字の文の中にあるときはその文の語に従います（[設定 › 縦組みの数字](/ja/docs/configuration#縦組みの数字)を参照）。次の3つの記法で、範囲の向きを個別に指定できます。

```markdown
第:tcy[120]回，:upright[GDP]增長:sideways[12]倍。
```

- `:tcy[…]`（縦中横）は、テキストを1全角の正立したマス1つに横に並べ、幅が広い場合は横方向に詰めます。`:tcy[120]`、`:tcy[3.0]`、`:tcy[A+]`。読みやすいのはおよそ4文字までです。
- `:upright[…]`は各文字をそれぞれ独立したマスに正立させ、ラテン文字はマスの中央に置きます。1文字ずつ読む頭字語を段に沿って並べるときに使います。この中で改行されることはありません。
- `:sideways[…]`は範囲全体を行の向きに合わせて横倒しにします。漢字も横倒しになります。著者が横向きにしたい2桁の数字などに使います。
- テキストはプレーンテキストに残ります。これらの記法の中には、ほかのインライン書式（`:tcy[**12**]`）、リンク（`:sideways[[iPhone](https://…)]`）、互いの記法を入れられ、もっとも内側のものが優先されます（`:tcy[:upright[AB]]`はAとBを正立させます）。角かっこそのものは`\]`と書きます。横組みでは何も変わりません。
- 記法の中の参照、注の合印、数式、チップ、色見本は、それぞれ本来の組み方を保ちます。`:sideways[iPhone[^1]]`はiPhoneを横倒しにし、注番号はほかの注番号と同じように組みます。参照の番号は、ほかの短い数字と同じく`cjk.uprightDigits`に従って1つのマスに正立します。
- `inlineMarks: true`を指定したデザインのテキスト要素も、縦に組まれるときはこれらの記法を受け付けます（[設定 › 縦組みのテキスト要素](/ja/docs/configuration#縦組みのテキスト要素)を参照）。
- 改行と両端そろえでは、`:tcy`のマスと`:upright`の各文字は漢字として数えられ、その隣には漢字とラテン文字のあいだのスペースが入りません。

### 中国語の記号、ルビ、割注

中国語と日本語の版では、イタリックや下線ではなく行間に付ける記号でテキストを示し、文字によみを添え、注釈を行の中に組みます。これを行うのが7つのディレクティブです。その背景にある慣習は[中国語の組版](/ja/docs/chinese-layout)と[日本語の組版](/ja/docs/japanese-layout)で説明しています。ディレクティブはテキストを保持します。角かっこのあいだの文字は段落に残り（検索、目次、索引のアンカー、コピーしたテキストは書いたとおりに読みます）、ディレクティブの中や外側には、入れ子のディレクティブを含め、ほかのインライン書式を入れられます。角かっこそのものは`\]`と書きます。

```markdown
此事:dots[不可]輕忽。:name[賈寶玉]與:name[林黛玉]讀:book[西廂記]。

{滿紙|mǎn|zhǐ}荒唐言，:ruby[一把]{rt="yì bǎ"}辛酸淚！:ruby[都]{rt="ㄉㄡ"}云作者痴。

寶玉:warichu[甲戌側批：此是第一首標題詩。]{open="〔" close="〕"}道：……

{東京|とう|きょう}の:ruby[紫陽花]{rt="あじさい"}は*とんと*:sideline[見事]だ。:book[こころ]を読む。

:kunten[學]{okuri="ビテ"}而:kunten[時]{okuri="ニ"}:kunten[習]{kaeri="二" okuri="フ"}:kunten[之]{kaeri="一" okuri="ヲ"}。
```

- **`:dots[text]`**：横組みでは各文字の下に、縦組みでは右に圏点（着重号）を付けます。句読点やスペースには付けません。`style="dot|circle|sesame"`（既定は`dot`）、輪郭だけにする`fill="open"`、反対側に付ける`pos="over|under"`を指定できます。`cjk.emphasis: 'dots'`のもとでは、中国語や日本語の文字に付けたMarkdownの強調`*…*`も同じ効果になり、これが中国語や日本語の文書の既定です。同じ強調の中のラテン文字はイタリックのままです。省略した属性は`cjk.emphasisMark`に従います。中国語では文字の下の点、日本語では文字の上（縦組みでは右）のゴマ点です。
- **`:name[text]`**：テキストの下（縦組みでは左）に固有名詞の傍線（专名号）を引きます。**`:book[text]`**（书名号）は書名号を付けます。`cjk.bookTitleMark`の指定に従い、書名を《》で囲む（書名の中の書名は〈〉）、古典や台湾の版の波線を引く、何も付けない、のいずれかになります（既定では、中国大陸と日本はかっこ、台湾と香港は波線）。日本語の文書ではかっこは『』で、書名の中の書名は「」です（`cjk.bookTitleBrackets`）。1つの原稿で、大陸の現代の版と古典の版の両方をまかなえます。並んだ2つの名前や書名は、線が離れて引かれます。
- **`:ruby[base]{rt="…"}`**：親文字の上（ピンイン）、または各文字の右（注音。注音字母のよみの既定）によみを付けます。よみが文字と同じ数あり、スペースまたは`|`で区切られている場合は、各文字に固有のよみが付き、そのあいだで改行できます（モノルビ）。`group`を指定した場合や数が合わない場合は、1つのよみを親文字全体の中央に付け、そこでは改行しません。`pos="over|under|right"`で付ける側を選びます。簡易形式の`{紅樓|hóng|lóu}`（`|`ごとに1つのよみ）や`{紅樓|hónglóu}`（親文字全体に1つのよみ）も同じ意味になりますが、有効なのは親文字に漢字、仮名、注音字母が含まれ、数式、コード、属性の外にある場合だけです。そのため、ラテン文字の文中の`{x|x>0}`はテキストのままです。波かっこや縦棒の前にバックスラッシュを置くと、中国語の文字を含むものもテキストとして残ります。`{紅|hóng}`と`{紅\|hóng}`は`{紅|hóng}`と印刷されます。行頭または行末に来る親文字は、よみと一緒にその端にそろえられます。`mode=mono|group|jukugo`はよみを親文字にどう付けるか（`mode=group`は`group`と同じ）、`align=center|jis|start`は親文字より短いよみをどう配置するかを選びます。日本語の文書では、2文字以上の語に文字ごとの形式（`{東京|とう|きょう}`、`rt="とう|きょう"`）を使うと熟語ルビになります。各文字は自分のよみを保ちますが、そのよみは語の次の文字にかかることがあり、文字のあいだで改行でき、よみの配置と仮名へのかかり方は`cjk.ruby.align`と`cjk.ruby.overhang`に従います。親文字全体に1つのよみを付ける形式（`{紫陽花|あじさい}`、青空文庫の`《》`）はグループルビです。`mode=mono`では文字ごとによみを付け、隣の文字にはかけません。
- **`:sideline[text]`**：テキストの横に傍線を引きます。句読点やスペースにも引き、横組みでは下、縦組みでは右に付きます。`style="solid|double|wavy|dotted"`（既定は`solid`）、`pos="over|under"`（縦組みではoverが右、underが左。`position=`も使えます）を指定できます。どの表記体系でも使え、下線を引いた英語の語句にも使えます。
- **`:warichu[note]`**：注（双行夹注）を、行の中に文字サイズの半分で2行に組みます。上の行（縦組みでは右の行）から読みます。長い注は行の残りを埋め、次の行、段、ページへと続きます。`open`と`close`は文字サイズのかっこで注を囲みます。`cjk.warichu`でサイズ、色、既定のかっこ（日本語の文書では「（）」）を設定します。ラテン文字の注は語のあいだで改行されます。
- **`:kunten[字]{kaeri="…" okuri="…" tate}`**：角かっこの中の最後の文字に訓点を付けます。`kaeri`は返り点（レ、一 二 三、上 中 下、甲 乙 丙、天 地 人、および一レ 上レ 甲レ 天レ。符号位置の㆑ ㆒ …も同じに読みます）、`okuri`は送り仮名（青空文庫のかっこ`（ヲ）`は取り除かれます）、フラグの`tate`は次の文字とつなぐ竪点です。テキストの順序は入れ替わりません。記号は半分のサイズで文字の横に組まれ（`cjk.kunten`）、コピーしたテキストは送り仮名を含み返り点を含まない「學ビテ而時ニ習フ之ヲ」になります。二度読む文字には、中にルビを入れられます。`:kunten[:ruby[未]{rt="ザル" pos=under}]{kaeri="レ" okuri="ダ"}`。

行送りは変わりません。記号とよみは行間に置かれ、段落の行間が狭すぎて収まらないときはビルドが警告します（`cjkMarksExceedLeading`、`rubyExceedsLeading`、`kuntenExceedsLeading`）。ある行の下の記号と次の行の上のよみが、共有する行間に収まらないときも、同じ段落の中か2つの段落にまたがるかを問わず警告します。注記を付けた段落には、行送りの大きい段落スタイルを指定してください。記号、よみ、注は、段落、見出し、リスト項目、引用ブロック、囲みに描かれ、キャプション、表のセル、注にも描かれます。これらの行間も同じように検査されます。柱やデザインでは、テキストは記号なしで印刷されます。`cjk.bookTitleMark: 'brackets'`のもとでは、書名の《》はテキストの約物として扱われ、キャプション、セル、注、目次の行、しおり、索引項目に残ります。[設定 › 圏点と傍線、ルビ、割注](/ja/docs/configuration#圏点と傍線ルビ割注)を参照してください。

### マークアップでの文字方向

文書は、その`locale`が示す方向に流れます（設定の`direction`。アラビア語、ペルシア語、ウルドゥー語、ヘブライ語では右から左）。その中で、マークアップを使ってブロックやテキストの範囲の方向を指定できます。アラビア語の本の中の英語の引用や、英語の本の中のアラビア語の引用に使います。

- **見出しやコンテナー**：属性に`{dir=ltr}`または`{dir=rtl}`を書きます。`# Introduction {dir=ltr}`、`:::paragraphs{dir=ltr}`、`:::callout{dir=rtl}`。コンテナーの中のすべてのブロックがその方向をとり、別の方向を指定する入れ子のコンテナーや見出しまで及びます。単純な段落、リスト、引用は自身の属性を持たないので、`:::paragraphs{dir=…}`で囲んでください。ほかの値は無視されます。コンテナーの`lang`（`:::paragraphs{dir=ltr lang=en}`）は、同じように中のブロックの言語を指定し、番号付きリストはその言語の数字で番号が振られます。
- **テキストの範囲**：`:ltr[…]`と`:rtl[…]`はテキストを分離します（Unicode双方向アルゴリズムのLRI…PDIとRLI…PDI）。範囲の中で順序が決まり、周囲の段落からは1つの中立文字として扱われます。`{lang=…}`はHTMLとPDFでその範囲の言語をタグ付けします。中の注の合印、`:ref`、数式は分離範囲の一部になり、分離範囲は入れ子にできます。

```markdown
:::paragraphs{dir=ltr}
The opening of the *Nights* in Lane's translation.
:::

ترجمها :ltr[Edward William Lane]{lang=en} سنة ١٨٣٩.
```

文書の方向と逆の方向にしたブロックは、自身の開始側を保ちます。字下げ、リストの記号、最終行を寄せる側が、テキストの始まる側に移ります。ラテン文字の題名が中立文字（ピリオドやかっこ）で終わり、そのままでは周囲のアラビア語に結びついてしまう場合は、分離範囲を使ってください。Unicodeの制御文字そのもの（U+2066–2069、U+202A–202E、U+200E、U+200F、U+061C）も解釈されます。Sandboxのエディターでは、各行は最初の文字の方向に流れます。[アラビア語の組版](/ja/docs/arabic-layout#書字方向と双方向アルゴリズム)を参照してください。

## 脚注

脚注は2つの部分からなります。注を引用する箇所に置く合印`[^id]`と、定義です。定義は`[^id]:`で始まる独立した段落で、章の中のどこに書いてもかまいません。

```md
The keeper climbed the tower every evening.[^steps] The wind put out his candle,
so he learned to count the steps in the dark.

[^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861.
```

- **合印**：`[^id]`は注の番号を上付きで印刷し、直前の語にくっつけます（上の例のように句読点のあとに書きます）。idには文字、数字、`-`、`_`、`.`、`:`を使えます。合印は段落、リスト項目、引用ブロック、囲みで有効です。見出し、キャプション、表のセルでは書いたとおりに印刷されます。
- **定義**：`[^id]:`で始まる段落です。テキストは次の空行まで続き、通常のインライン書式（太字、イタリック、リンク、`:ref`、数式、チップ）が使えます。定義はどこに書いても本文の流れから外れるので、引用する段落の下に置いても、章末にまとめて置いてもかまいません。同じidの定義が複数あれば最初のものが使われます。
- **番号**：注は最初に引用された順に番号が振られ、章ごと（レベル1の見出し、および本の各文書）に振り直されます。2回引用された注は最初の番号を保ち、1回だけ組まれます。`footnotes.numbering: 'document'`では本全体の通し番号になり、`'page'`では中国の本のようにページごとに振り直します。`footnotes.numberFormat: 'circled-decimal'`は① ② ③をベースライン上に書きます。
- **日本語のテキスト**：合印は文末の。の前に書きます（`先生[^1]。`）。合印は直前の文字とともに残り、。が行頭に来ることはありません。日本語の縦組みの本では、既定で合印（1）を行の右に組み、注を章のあとに置きます。`footnotes.markerPosition: 'side'`は小さな合印を語の横に組み、行の中で場所を取りません。`footnotes.placement: 'spread'`は見開きごとに本文の横に注を組みます（[設定 › 脚注](/ja/docs/configuration#脚注)を参照）。
- **注の置き場所**：既定では、注を引用する行を含む段の下端に、短い罫線をはさんで置きます。行とその注は必ず同じ段に入り、注が収まらない行は注とともに次へ送られます。1段組みのレイアウトでは、それはページの下端です。`footnotes.placement: 'chapterEnd'`を指定すると、章のすべての注を章の最後のブロックのあとに置きます。その場合も既定では、注が締めくくる段の下端に置かれます。サイズ、罫線、間隔については、設定リファレンスの[脚注](/ja/docs/configuration#脚注)を参照してください。
- **検査**：定義のない合印（`undefinedFootnote`）は空の注の上に番号を印刷します。どの合印からも引用されない定義（`unusedFootnote`）は組まれません。Sandboxは両方を**検査**パネルに表示します。

## 相互参照とアンカー

相互参照は本の中の場所を指し、その番号、タイトル、ページを印刷します。「3.2節を参照」「第4章で説明するとおり」「112ページ」のような表現です。語と番号はテキストに従うので、節を移動しても、章の番号を振り直しても、本を組み直しても、すべての参照が更新されます。PDF、HTML、Sandboxのプレビューでは各参照がリンクになり、クリックすると、別の章であっても参照先へ移動します。

**アンカー**：参照には指す対象が必要です。

- **見出し**：識別子を付けた見出し。`## Method {#sec-method}`（Pandocの形式。`id="sec-method"`も使えます）。
- **ボックスやその他のコンテナー**：識別子を付けて開いたもの。`:::callout{#box-safety title="Safety"}`。
- **テキストの中の位置**：`:anchor{#key-idea}`は見えないアンカーを置きます。`[the key idea]{#key-idea}`は語をそのまま残し、その語に名前を付けます。

識別子には文字、数字、`-`、`_`、`.`、`:`を使えます。識別子は本の中で一意でなければなりません。2回設定された識別子は**検査**パネルに表示され（`duplicateAnchor`）、参照は最初に設定された位置を指します。

**参照**：`:ref{id="…"}`は、図や表と同じ方法でアンカーを参照します。

```md
## Method {#sec-method}

The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}.
```

| `style` | 印刷される内容 |
| --- | --- |
| *指定なし* | 番号付きの見出しは語と番号（*3.2節*、*第4章*）、番号のない見出しはタイトル、アンカーはそのテキスト |
| `number` | 番号だけ（*3.2*） |
| `title` | 見出しのタイトル、アンカーのテキスト、またはボックスの`title` |
| `page` | 参照先が置かれたページ（*112ページ*） |
| `pageNumber` | ページ番号だけ（*112*） |

`text="…"`は独自の語を印刷し、リンクも保ちます。`case=capitalize`はラベルを大文字で始めます（文頭の*Section 3.2*）。語は文書の言語に従い（*sección 3.2*、*第3.2节*、*S. 112*）、設定の[相互参照](/ja/docs/configuration#相互参照)で変更できます。見出しのテンプレートが番号をすでに語で書き表している場合（*Chapter 4*、*第四章*）、その番号はそのまま印刷されます。

**ページ参照**は、本を組み終えてはじめて決まります。エンジンは目次と同じく、前回のパスのページを使って文書を組み直し、ページが変わらなくなるまで繰り返します。それまでのあいだ、ページは「?」と印刷されます。

**pandoc-crossref**：pandoc-crossref向けに書いたテキストも同じように読めます。`@sec:method`、`[@fig:map]`、番号だけを出す`[-@tbl:data]`です。接頭辞（`sec`、`fig`、`tbl`、`eq`、`lst`）は識別子に含めても（`{#sec:method}`）、省いても（`{#method}`）かまいません。メールアドレスのように語にくっついた`@`はテキストのままです。

何も設定されていないidへの参照は「?」と印刷され、**検査**パネルに表示されます（`unknownResourceId`）。Sandboxのエディターでは、`@`を入力すると本の図、表、idを持つ見出し、アンカーが候補として表示されます。

## 引用と参考文献

引用はPandocが読む形式で書き、文献データは文書の中に置き、引用スタイルは設定で選びます。APAからIEEEへ、あるいはChicagoの注方式へ切り替えるときに変えるのはスタイルの設定で、テキストではありません。すべての引用は、参考文献の該当する項目にリンクします。

### 引用の書き方

```md
As [@garcia2020, p. 33] shows, reading on paper is faster [see @lopez2019, chap. 2; @bringhurst2004].
@garcia2020 [p. 4] says it plainly; the 2020 study [-@garcia2020] agrees.
```

- **`[@key]`**：かっこ付きで引用します。複数の文献は、1組の角かっこの中に`;`で区切って書きます。
- **ロケーター**：コンマのあとに`p. 33`、`pp. 4–6`、`chap. 2`、`sec. IV`、`fig. 3`、`vol. 2`、`n. 12`、`l. 4`、`§ 4.2`と書きます。数字だけならページです。スペイン語（`pág.`、`cap.`）や中国語（`页`、`章`）の語も使えます。
- **前置きと後置き**：`@`の前のテキスト（`see`）と、ロケーターのあとのテキスト（`, emphasis added`）です。
- **`[-@key]`**：著者名を省きます。すでに著者名を挙げている文に使います。
- **`@key`**：文中で引用します（*García (2020)*）。`@key [p. 4]`でロケーターを加えます。
- 文字や数字にくっついた`@`（メールアドレス）、インラインコードの中の`@`、`\@`はテキストです。本に文献データのない引用は書いたとおりに印刷されるので、文献データのない文書はこれまでどおりに読めます。複数の文献をまとめた引用で、どの文献データにも定義されていないキーがあると、そのキーはほかの文献のあとに太字で印刷されます（`(Glen, 1955) **@nye1953**`）。そのため、欠けている文献は警告の一覧にもページの上にも現れます。引用のあとのコロンはテキストです。`[@french2018]: the land…`。
- 中国語、日本語、韓国語のテキストでは、引用は最後の文字のあとにスペースなしで続き（`周明远@zhou2019认为`）、著者・出版年方式の引用は周囲のテキストに合わせて全角の記号を使います。`（施雅风等，1988；刘时银等，2015）`。

### 文献データ

文献データは、CSL形式（ZoteroとPandocのデータモデル）で文書の中に書きます。

```md
---
references:
  - id: garcia2020
    type: book
    author: [{family: García, given: Ana}]
    title: Tipografía y lectura
    issued: 2020
    publisher: Trea
nocite: "@lopez2019"
---
```

または、`:::references`ブロックの中に、BibTeX（Zotero、JabRef、Google Scholarの書き出し）、CSL-JSON、CSL-YAMLで書きます。

```md
:::references{format=bibtex}
@article{lopez2019, author = {López, Luis and Ruiz, Eva}, title = {Leer en pantalla},
  journal = {Revista de Letras}, year = 2019, volume = 12, pages = {45--67}, doi = {10.1000/xyz}}
:::
```

このブロックは何も印刷しません。`nocite`は引用せずに文献を挙げます（`@*`ですべて）。本では、どの章に書いた文献データも本全体で有効です。

### 参考文献の一覧

`:::bibliography`は、置いた位置に引用文献の一覧を組みます。これがない場合、一覧は最後の章のあとに続き、文書の言語のタイトル（「References」「Referencias」「参考文献」）が付きます。`:::bibliography{title="Works cited"}`でタイトルを変更でき、`title=""`でタイトルを省けます。`scope=chapter`は、その章で引用された文献を挙げます（編著書向け）。各項目はアンカー（`ref-<key>`）なので、`#ref-garcia2020`へのMarkdownリンクで到達でき、PDFでは`BibEntry`としてタグ付けされます。

### スタイル

スタイルは、引用と文献項目に何を書くかを決めます。同梱のスタイルは下の表のとおりです。それ以外のCSLスタイル（Zoteroのスタイルリポジトリには1万以上あります）は、**設定 → 引用**で`.csl`ファイルから読み込めます。

| `citations.style` | 名前 | 方式 |
| --- | --- | --- |
| `apa` | APA 7 | 著者・出版年 |
| `chicago-author-date` | Chicago（著者・出版年） | 著者・出版年 |
| `harvard-cite-them-right` | Harvard | 著者・出版年 |
| `iso690-author-date-en`、`iso690-author-date-es` | ISO 690 | 著者・出版年 |
| `china-national-standard-gb-t-7714-2025-author-date` | GB/T 7714—2025 著者-出版年 | 著者・出版年 |
| `china-national-standard-gb-t-7714-2015-author-date` | GB/T 7714—2015 著者-出版年 | 著者・出版年 |
| `modern-language-association` | MLA 9 | 著者・ページ |
| `ieee` | IEEE | 番号 |
| `elsevier-vancouver` | Vancouver | 番号 |
| `american-medical-association` | AMA | 番号 |
| `nature` | Nature | 番号 |
| `iso690-numeric-en` | ISO 690 | 番号 |
| `china-national-standard-gb-t-7714-2025-numeric` | GB/T 7714—2025 顺序编码 | 番号 |
| `china-national-standard-gb-t-7714-2015-numeric` | GB/T 7714—2015 顺序编码 | 番号 |
| `sist02` | SIST 02 参照文献の書き方 | 番号 |
| `chicago-notes-bibliography` | Chicago（注） | 注 |
| `oscola` | OSCOLA | 注 |
| `china-national-standard-gb-t-7714-2025-note` | GB/T 7714—2025 注释 | 注 |
| `china-national-standard-gb-t-7714-2015-note` | GB/T 7714—2015 注释 | 注 |

**注方式**のスタイルでは、各引用は脚注になり、脚注の設定どおりに配置され、番号が振られます。同じ文献を再び引用すると短縮形になります。中国語のテキストでは、`citations.notes: 'warichu'`で注を行の中の2行の注（夹注）として組みます。中国語の約物（`，`、`。`）が続く注は、自身の句点を省きます。

**中国語**：GB/T 7714-2015のスタイルは文献種別コード（`[M]`、`[J]`、`[D]`、`[EB/OL]`）を書き、中国人の名前は省略せずに書きます。中国語の文献では著者3人のあとに`等`、欧文の文献では`et al.`を書き、どちらにするかは各文献の`language`で決まります。縦組みでは、上付きの番号は文字の右に置かれます。`citations.marker: 'corner'`は`〔1〕`と書き、これは正立します。

**エンジン**：引用は`postext-citeproc`パッケージ（citeproc-jsとCSLスタイル）で整形されます。Sandboxは引用を含む文書でこれを読み込みます。独自のコードでは、レイアウトの前に登録してください。

```ts
import 'postext-citeproc/register';
```

**検査**パネルには、どの文献データにも定義されていないキー（`unknownCitationKey`）と、読み取れない文献ブロック（`referencesUnreadable`）が表示されます。

## 索引

索引は、本の用語とそれが現れるページを挙げるものです。本文で用語を扱う箇所ごとに印を付け、索引を置きたい場所（ふつうは巻末の独立した章）で`:::index`を使って印刷します。エンジンはレイアウトのあとにすべての印のページを調べるので、番号はテキストに従います。段落を加えても、章を移動しても、仕上がりサイズを変えても、索引は新しいページを印刷します。

```md
Iron-deficiency :index[anaemia] is the most common kind.
The pulse is taken at the wrist.:index{term="Pulse!radial" main}

# Index {style="index"}

:::index
```

### 索引マーク

- **`:index[text]`**：`text`を印刷し、その語自体の項目に登録します。中のインライン書式は印刷されますが、項目からは取り除かれます。角かっこのあとの属性で別の項目に登録できます。`:index[iron deficiency]{term="Anaemia!iron-deficiency"}`。
- **`:index{term="…"}`**：何も印刷しません。印は、同じ行で直前に書かれた語のページをとり、行頭にある場合は直後の語のページをとります。印だけの行は取り除かれるので、独立した行に置いた印が段落を分けたりスペースを加えたりすることはありません。
- **使える場所**：段落、見出し、リスト項目、引用ブロック、囲み、脚注の定義。キャプション、表のセル、デザインの要素では、印は書いたとおりに印刷されます。インラインコードの中とバックスラッシュのあと（`\:index`）ではテキストです。

| 属性 | 効果 |
| --- | --- |
| `term` | 項目です。レベルは`!`で区切ります。`term="Heart!valves!mitral"`は、そのページを*Heart*の下位項目*valves*の、さらに下位項目*mitral*に登録します。レベルにはインライン書式を含められ（`term="*Escherichia coli*"`）、並べ替えでは書式を除いて扱います。`term`がない場合、`:index[text]`はそのテキストを使います。 |
| `sub` | `term`のあとに加えるレベルです。`term="Heart" sub="valves"`は`term="Heart!valves"`と同じです。 |
| `sort` | 最後のレベルをほかの文字列で並べたいときの並べ替えキーです。`:index[St Kilda]{sort="Saint Kilda"}`、`term="20th century" sort="twentieth century"`。中国語の索引は、照合規則（collator）が文字に与えるよみで並べ替えとグループ分けをします。複数のよみを持つ文字を別のよみで扱うには、目的のよみしか持たない文字でキーを書きます。`:index[重阳]{sort="崇阳"}`は、重阳をZではなくCの、程と崔のあいだに登録します。ピンインのキー（`sort="chong yang"`）でもCに入りますが、照合規則がラテン文字を漢字のあとに置くため、Cの中国語の項目すべてのあとに並びます（[設定 › 索引](/ja/docs/configuration#索引)の`groupBy`を参照）。 |
| `yomi`、`reading` | 最後のレベルの仮名によるよみです。日本語の索引はこれで並べ替えとグループ分けをします。`:index[夏目漱石]{yomi="なつめそうせき"}`は、な行の「な」に登録されます。これがない場合、仮名のふりがなを含む印はそのふりがなで読まれ（`:index[{東京\|とう\|きょう}]`はとうきょうとして並びます）、次に`sort`、次にテキストが使われます。それでも漢字で始まる項目は`indexReadingMissing`として報告されます。ほかの言語の索引では、`yomi`は`sort`として働きます。印の中のふりがなは簡易形式で書いてください。`:ruby[…]`では角かっこをエスケープする必要があります。postext 1.16から使えます。 |
| `main` | フラグです。用語を主に扱う箇所を示し、そのページ番号は太字で組まれます（`index.main`）。両方の方法で印を付けたページは太字になります。 |
| `range` | 同じ用語に`range="start"`と`range="end"`を付けると、複数ページにわたる記述の範囲を示し、項目は`34–37`と印刷されます。終わりのない始まりや始まりのない終わりは、その1ページを印刷し、`indexRangeUnclosed`を発生させます。 |
| `see` | ページ番号の代わりに置く相互参照です。`:index{term="Cardiac insufficiency" see="Heart failure"}`は*Cardiac insufficiency. See Heart failure*と印刷します。参照先のレベルは`!`で区切り、印刷ではコロンでつながれます（*See Heart: valves*）。索引の項目にない参照先は`indexSeeUnknown`を発生させます。 |
| `seealso` | 項目のページ番号のあとに置く相互参照です。*Heart, 12, 40. See also Circulation*。印自身のページはほかの印と同じく数えられるので、1つの印で箇所を索引に載せ、同時に関連項目を指せます。`see`の印はページを加えません。 |
| `index` | 別の索引の名前です。`index="names"`は、その印をメインの索引ではなく、`:::index{index="names"}`が印刷する索引に登録します。 |

用語のない印（`:index{}`や、`:index{see="…"}`だけのもの）は何も索引に載せず、`indexMarkInvalid`を発生させます。

### 索引の出力

`:::index`は置いた位置にメインの索引を印刷し、`:::index{index="names"}`は名前付きの索引を印刷します。このディレクティブは項目ごとに1つの通常のブロックに展開され、テキストと同じように段やページを流れます。[見出しスタイル](/ja/docs/configuration#見出しスタイル)で2段組みの`layout`を指定した見出しの下に置けば、一般的な2段組みの索引になります。項目をクリックすると、ディレクティブの行に移動します。

```md
# Index of names {style="index"}

:::index{index="names"}

# Index of subjects {style="index"}

:::index
```

- **並び順**：項目は文書の言語（`locale`または`index.locale`）のアルファベット順に並びます。アクセント付きの文字は基本の文字と同じ扱いになり（「Árbol」はAの下）、スペイン語では「ñ」が「n」のあとに独自の見出しで並びます。記号で始まる項目が最初に、次に数字で始まる項目、その後に文字で始まる項目が並びます。下位項目も項目の下で同じように並び、レベルごとに1段ずつ字下げされます。日本語の索引は、JIS X 4061の順序でよみによって並べ替え、五十音の行（あ行、か行…）でグループ分けし、ラテン文字の項目を仮名の項目の前に置きます（[日本語の組版 › 五十音順の索引](/ja/docs/japanese-layout#五十音順の索引)を参照）。
- **グループ**：最初の文字が変わるたびに新しいグループが始まり、文字の見出し（`index.groups`）とその上の1行分のスペースが入ります（最初のグループの上には入りません）。見出しはグループの最初の項目と1つのブロックとして組まれるので、段の終わりに単独で残ることはありません。自身のページを持たない項目（下位項目をまとめるだけの項目）も、同じ理由で最初の下位項目と一緒に組まれます。
- **ページ番号**：各ページが印刷するラベルで、前付けのローマ数字も含みます。項目のページは並べ替えられ、それぞれ1回だけ挙げられます。連続するページは範囲にまとめられ（`12–14`、`index.mergeRanges`）、同じ項目の範囲に含まれるページはその範囲に吸収されます（そこに主要な箇所のページがあれば範囲が太字になります）。`index.rangeFormat: 'chicago'`は2つ目の数字を短縮します（`234–37`）。太字（主要な箇所）のページは範囲にまとめられません。PDFでは、各番号はそのページへのリンクになります。
- **相互参照**は項目の最後に置かれます。ページのない項目では*Term. See Target*、ページのある項目では*Term, 12. See also Target*となります。ラベルは文書の言語に従い（*See*、*Véase*…）、`index.see`で設定できます。
- **本**：章ごとに組まれる本（Sandbox、`buildBundle`）では、索引を印刷する章がすべての章の印とそのページを受け取り、そのいずれかが移動したときだけ組み直されます。印と索引の両方を含む文書は、`:::toc`と同じく、番号が落ち着くまで組み直されます。

索引の文字組み、字下げ、区切り記号については、設定リファレンスの[索引](/ja/docs/configuration#索引)を参照してください。

## 数式

数式のサポートは、文書形式の正式な一部です。Postextはインライン数式の`$…$`と別行立て（ブロック）数式の`$$…$$`を解析し、[MathJax](https://www.mathjax.org/)のSVGモードで描画します。3つのバックエンドすべてで同じベクターパスを使うので、Canvasのプレビュー、HTMLの書き出し、PDFの出力はピクセル単位で一致し、PDFはどの倍率でも完全なベクターのままです。

- **インライン**：`$…$`。どのテキストブロック（段落、見出し、引用ブロック、リスト項目）の中でも認識されます。行には分割できない1つのボックスとして加わり、Knuth-Plassはこれを分割してはならない語として扱います。数式の本来の高さが行ボックスに収まらない場合は、ベースライングリッドを保つために全体が均等に縮小されます。非常に高い式は別行立てにしてください。
- **別行立て**：`$$…$$`。1行に単独で書くか（`$$\int_0^1 x^2\,dx$$`）、`$$`だけの行で囲んで複数行にわたって書きます。段の中央に描画され、上下の余白（`math.marginTop`、`math.marginBottom`）を設定してベースライングリッドにそろえられます。見出しと同じ補正の仕組みなので、数式のあとの段落はグリッド上に戻ります。
- **別行立ての前後のテキスト**：1行に単独で書いた別行立ての数式は、上に空行がなくても段落を中断します。その前のテキストは数式へ導く段落になり、閉じの`$$`のすぐ下に空行なしで書いたテキストは、中断された段落の続きとして1行目の字下げなしで組まれます。TeXが別行立てのあとの「where …」を組むのと同じです。上のテキストと空行で区切った数式（またはリスト、引用、見出しのあとの数式）は何も中断しません。そのあとのテキストは、空行の有無にかかわらず新しい段落になり、通常どおり字下げされます（`math.indentAfterDisplay: false`にすると、これも字下げなしになります）。段落を中断するのは別行立て全体だけで、1行に数式が1つだけある場合か、次の空行より前に閉じられた`$$`の囲みです。`$$a$$ and $$b$$`のような行はテキストのままです。`math.keepWithLeadIn`は、数式を導入する行と同じ段に数式を保ちます（postext 1.4までは、上に空行のない`$$…$$`の行は段落の一部として読まれ、書いたとおりに印刷されていました）。
- **数式番号**：`\tag{…}`は別行立ての数式に番号を付けます。数式は段の幅（または囲みの内側の幅）いっぱいに広がり、式は中央に、番号はその行の右端にそろえられます。`align`では、タグを付けた各行に番号が付きます。`\tag*{…}`はかっこなしでラベルを印刷します。番号が付くのは、明示的にタグを付けた数式だけです。
- **エスケープ**：`\$`はドル記号そのものです。キャプション、表のセル、注、チップは数式として解析されないので、そこでの`$`はそのまま印刷されます。そこでも`\$`はドル記号を印刷するので、エスケープした同じ文字列が本文でも表でも同じに読めます。対応のとれない`$`や`$$`の区切りは、Sandboxの**検査**パネルに`unclosedMath`の項目として表示され、クリックでソースの該当箇所へ移動できます。
- **エラー**：MathJaxが受け付けないTeXソース（未定義のマクロ、構文エラー）は`invalidMath`警告として表示されます。数式は小さな赤いプレースホルダーに置き換えられ、レイアウトの形状は有効なまま保たれます。
- **設定**：設定の`math`セクションには、`enabled`、`fontSizeScale`（周囲のテキストのサイズに対する比率。1.0では数式の1 emがそのサイズになり、別行立ての数式と本文中のインライン数式では本文のサイズです。postext 1.5からは数式が1.4より約13%小さく組まれますが、1.4で保存したバンドルとSandboxの本は元のサイズを保ちます。[数式のサイズ](/ja/docs/configuration#数式)を参照）、`color`（未設定なら本文の色を継承）、別行立ての余白があります。
- **エンジン**：MathJaxは必要になったときに読み込まれます。Sandboxとレイアウトワーカーは自動で起動します。独自のコードでは`buildDocument`の前に`await initMathEngine()`を実行してください。そうしないと、すべての数式が灰色のプレースホルダーのボックスとして組まれます（[数式エンジンの起動](/ja/docs/configuration#数式エンジンの起動)を参照）。

```md
The Euler identity $e^{i\pi}+1=0$ links the five fundamental constants.

$$
\int_0^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$
```

文の途中に数式を置き、そのあとも字下げなしで文を続ける例です。

```md
For a pendulum of length $L$ the period is
$$T_0 = 2\pi\sqrt{L/g}$$
where $g$ is the acceleration of free fall.
```

## リソース

画像、SVG、表、動画は本文中には書きません。これらは**リソース**として一度だけ宣言し（Sandboxの[**リソース**パネル](/ja/docs/sandbox#リソースパネル)で管理します。このパネルでは、画像とSVGのアップロード、対話式の表エディター、YouTube・Vimeo・アップロードした動画、キャプションと配置の編集を扱います）、IDで本文と結び付けます。**リソースは参照するだけで組み込まれます**。インラインの`:ref{id="…"}`で一度言及すれば、エンジンが図や表をその参照の後にある最初の空き位置へフロートとして配置します。言及した段の下端、次の段の上端、次のページの帯など、印刷の組版者と同じやり方です。2度目に配置する必要はありません。

以下の2つの形式はどちらもCommonMarkと衝突しない新しい構文なので、これらを使った文書もほかのMarkdownビューアーではプレーンテキストとして読めます。

### インライン参照（基本の形）

本文中からリソースを参照するには`:ref{id="…"}`を使います。最初の参照はリソースを**組み込み**（ページ上に配置されるようにし）、同時に算出された番号を表示します。番号の前には、既定で種類の短いラベルが付きます。

```md
As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery.
```

表示は「*As shown in Fig. 1.7, the lantern room sits above the gallery.*」となります。図そのものはその文の後にある最も近い空き位置（この段の下端、次の段の上端、または次のページの帯）へフロートとして配置され、この文とそれに続くテキストは途切れずに流れます。

参照の位置で本文が途切れることはありません。リソースが置かれる場所（最初の空き位置か、上端または下端の位置だけか、1段の中か全幅にわたるか）は、その**配置**（後述の[配置](#配置)を参照）と、言及した場所によって決まります。探索は参照の直後から始まります。

### ブロック埋め込み（任意、本文中への明示的な配置）

リソースをフロートさせず、流れの中の決まった位置に置きたい場合もあります。フロートをやめるには、リソースに`placement.position: "here"`を指定し、`::resource{id="…"}`を単独の行に書いて埋め込みます。

```md
Here is the floor plan we discussed.

::resource{id="lighthouse-diagram"}

The keeper's quarters occupy the eastern wing.
```

フロートするリソースには`::resource`ディレクティブは不要です。`:ref`がすでに配置しており、同じIDに対する余分な`::resource`は2つ目の複製ではなく、もう1つの参照として扱われます。`::resource`がリソースを本文中に描画するのは、解決された配置が`"here"`の場合だけです。インラインのリソースは、フロートと同じく上に1行分のアキ（フロートのアキ）を取ります。ただし、直前のブロックがそれより大きなアキを求める場合はそちらに従います。本文中では下にも同じアキを取り、その後のテキストはベースライングリッドに戻ります。このとき、さらに最大1行分のアキが加わることがあります。直後に見出し、リスト、囲み、または別のインラインのリソースが続く場合、そのアキは後続の要素自身の上のアキと共有され、両方ではなく大きいほうが適用されます。（postext 1.4までは、下のアキはグリッドへのスナップで残る分だけで、0から1行まで幅がありました。`layout.inlineResourceGap: 'above'`でその規則を保てます。1.5より前に保存された本はこの設定で読み込まれます。）囲み（`:::callout`）の中でもリソースは同じアキを保ち、上には囲み自体のテキストの1行分、`'around'`の場合は下にも同じだけ取ります。囲みの上端または下端では、代わりにパディングがリソースを離します。（postext 1.4までは、リソースは囲みのテキストに密着していました。`layout.inlineResourceGapInBoxes: false`でその動作を保てます。リソースを埋め込んだ囲みを含む、1.5より前に保存された本はこの設定で読み込まれます。）

`id`は**リソース**パネルで定義したリソースと一致している必要があります。エンジンはリソース（ビットマップ、SVG、表）を描画し、その下に図や表の脚書きとしてキャプションを組みます。キャプションのテキストは、リソースの種類の`captionPrefix`、算出された番号、リソース自身のキャプションから組み立てられます。たとえば「**Figure 1.7. The original lighthouse plan.**」のようになります。キャプションの文字組みは[設定 › キャプションスタイル](/ja/docs/configuration#キャプションスタイル)で決まります。ラベルと説明文は書体とサイズを共有し、ラベルだけは太字・イタリック・色を個別に設定できます。キャプションの上のアキの既定値は`0.75em`、そろえの既定値は左です。キャプションはリソースの上に置くこともでき（`captionStyle.position: 'above'`。全体またはリソースの種類ごとに指定）、色付きの帯の上に組むこともできます。リソースには`note`（注記）を付けることもできます。出典やクレジットを示す短い行で、キャプションと同じインラインの書式と`:ref`の記号が使えます。注記はリソースの下に小さめの文字で組まれ（キャプションが下にあるときはキャプションの下、上にあるときは本体の下）、スタイルは`captionStyle.note`で設定します。

**キャプションと注記の改行**。キャプションや注記はそれぞれ、その位置の行長で組まれる1つの段落で、中で入力した改行はスペースになります。新しい行を始めるには、タイトルで使う強制改行の`\\`を書くか、Markdownのハード改行として行末をバックスラッシュで終えます。`¹ Measured at 20 °C. \\ ² Mean of three runs.`と書けば、幅の広い表の脚注がそれぞれ1行に組まれます。改行の前の行は自然な幅のままで、行長いっぱいに伸ばされることはありません。改行を2つ続けても空行はできません（間にノーブレークスペースを入れると空行になります）。表のセルの中では、`\\`は改行と同じく新しい段落を始めます。その次の行の字下げは保たれるので、先頭の2つのスペースでリスト項目を入れ子にできます。本文中では2つのバックスラッシュは常に改行になり、エスケープの方法はありません。そのまま印字するには、バックスラッシュが書いたとおりに印字されるインラインコードの中に入れます。リンク先の中ではURLの一部、ディレクティブの属性（`:ref`の`text`）の中では値の一部のままです。1行に組まれるチップの中では、改行はスペースになります。（postext 1.4までは、バックスラッシュがそのまま印字され、キャプションや注記は行長が尽きたところでしか改行されませんでした。）

表のリソースは独自の罫線を描画し、そのスタイルは[設定 › 表スタイル](/ja/docs/configuration#表スタイル)で設定します。本文セルとヘッダーセルの文字組みは完全に独立しています。ヘッダーの背景の既定値は`#f0f0f0`、罫線は`0.75pt`、`cellPadding`は`0.375em`で、未設定の項目は本文テキストから継承されます。列幅は表そのものに含まれます。`TableModel.columnWidths`は列ごとに1つの相対的な比率を持ち（`[2, 1, 1]`なら第1列が幅の半分を占めます）、未設定なら列は幅を均等に分けます。表は名前付きのバリエーションで組むこともできます。`table.styleId`は文書の`tableStyles`の1つを選び（[設定 › 名前付きの表スタイル](/ja/docs/configuration#名前付きの表スタイル)を参照）、その未設定の項目は`tableStyle`を継承します。不明なIDやIDがない場合は`tableStyle`のままです。

セルの内容の置き方は、`TableCell.align`（`left`、`center`、`right`。リスト項目は左そろえのまま）と`TableCell.verticalAlign`（既定値の`top`、`middle`、`bottom`）で決めます。縦方向のそろえは、内容より背の高いセル、つまり隣の長いセルに引き伸ばされた行や、`rowSpan`がまたがる行の中で、セルの内容全体（画像とその下のテキストを1つのまとまりとして）を動かします。これはすべての出力（canvas、HTML、PDF）、回転した表、ページをまたいで分割された表の各部分に適用されます。どちらもSandboxの表エディターのツールバーにあるそろえのボタンでセルごとに設定します。

表のセルには画像を入れることもできます。`TableCell.image`はビットマップまたはSVGのリソースをIDで指定します（`{ "resourceId": "fig-arm", "width": 0.7 }`）。画像はセルの中に描画され（番号、フロート、キャプションは付きません）、縦横比を保ったままセルの内側の幅（または`width`で指定したその割合。既定値は`1`）に合わせられ、セルのテキストと同じようにそろえられます。セルのテキストはその下に続きます。行は画像が収まるように高くなります。Sandboxの表エディターでは、ツールバーの画像ボタンで選択中のセルのリソースを選び、幅の欄で割合を設定します。どの画像リソースとも一致しないIDの場合、セルはテキストだけになります。

セルには独自の塗りを持たせることもできます。`TableCell.background`は色の値（`{ "hex": "#c1dfd6", "model": "hex" }`。`paletteId`で文書のパレットの項目にリンクすることもできます）で、スタイルのヘッダーや本文の背景の代わりに塗られます。互換性の一覧表では、この方法でセルを緑、赤、黄色に塗り分けます。Sandboxの表エディターでは、ツールバーの塗りのコントロールで設定します。こうした塗りの凡例のために、キャプション、注記、あらゆるテキストブロックでインラインの**カラースウォッチ**が使えます。`:swatch{color="#c1dfd6"}`（hex値、またはパレット項目のID。`:swatch{color="table-compatible"}`）は、ベースライン上にフォントサイズの4分の3の小さな正方形を置き、その色で塗ってテキストの色で輪郭を描きます。これで注記を`:swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible`のように書けます。何にも解決されない色の場合は、空の輪郭だけが描かれます。hex値にはアルファチャンネル（`#rrggbbaa`、`#rgba`）も使え、`rgb()` / `rgba()`の色も使えるので、半透明のセルの塗りには半透明の凡例を合わせられます（[設定 › 透明度](/ja/docs/configuration#透明度)を参照）。

SVGのリソースは、さらに`diagramStyle.singleInk`（既定値は`false`）で、1色の特色印刷向けに色を変えられます。有効にすると、SVGのダイアグラムのすべての色が、輝度に応じた`diagramStyle.inkColor`（既定値はパレットのメインカラー`#295AA3`）の濃淡に置き換えられます。白は紙の色に、黒はインキのベタになるので、文書を1色の特色で印刷しても図が忠実に再現されます。[設定 › ダイアグラムスタイル](/ja/docs/configuration#ダイアグラムスタイル)を参照してください。

不正な埋め込み（`id`がない、または空、`id`が引用符で囲まれていないか一重引用符で囲まれている、余分な属性がある）はリソースのブロックとして扱われず、通常の段落として解析されて出力にそのまま表示されます。正しい形式の埋め込み行でも、段落の行の直下に空行なしで続けて書くと同じで、その段落の一部として読まれます。どちらも`malformedEmbed`警告となり、Sandboxの**検査**パネルに**テキストとして組まれた埋め込み**の項目として表示されます。

インライン参照は、段落、見出し、引用ブロック、リスト項目など、あらゆるテキストブロックの中で認識され、太字、イタリック、インラインコード、インライン数式と並べて使えます。

#### 参照のオプション

`:ref`ディレクティブは3つの省略可能な属性を任意の順序で受け付けます。`style`は算出されたラベルの表示方法を選びます。`style="number"`は番号だけ（`1.7`）、`style="full"`は種類の正式名と番号（`Figure 1.7`）を表示し、`style`が未設定のときは種類の`shortLabel`と番号（`Fig. 1.7`）を使います。`case`はラベル部分の大文字・小文字だけを変え（`lower`、`upper`、`capitalize`）、番号には触れません。`text`は書いたとおりに使われる上書きで、算出されたラベルを置き換え、`style`と`case`の両方より優先されます。表示のオプションを並べると次のとおりです。

| 構文 | 表示 | 備考 |
| --- | --- | --- |
| `:ref{id="…"}` | `Fig. 1.7` | 既定のスタイル：種類の`shortLabel`に続けて番号を表示します。両者はノーブレークスペースでつながれ、別々の行に分かれることはありません。 |
| `:ref{id="…" style="number"}` | `1.7` | 算出された番号だけで、ラベルは付きません。 |
| `:ref{id="…" style="full"}` | `Figure 1.7` | 種類の正式な`name`に続けて番号を表示します。文頭や、略記では読みにくい箇所で使います。 |
| `:ref{id="…" case="lower"}` | `fig. 1.7` | ラベルだけの大文字・小文字を変えます：`lower`（`fig. 1.7`）、`upper`（`FIG. 1.7`）、`capitalize`（先頭の文字を大文字に）。`style="full"`と組み合わせられます（`figure 1.7`）。番号は変わらず、認識されない値は無視されます。 |
| `:ref{id="…" text="see the plan"}` | `see the plan` | 明示的な上書きです。算出されたラベルの代わりに、指定したテキストがそのまま使われます。「先に見たように」のような本文中のリンクに便利です。指定した場合、`text`は`style`と`case`より優先されます。 |

`:ref`（または`::resource`）が一致するリソースのないIDを指定すると、ラベルは`?`になり（`text=`のラベルがある場合はそれが表示されますが、番号もリンクも付きません）、Sandboxは**不明なリソース**の警告を出します。エンジンはこれを文書の`contentWarnings`に`unknownResourceId`の項目として、参照のソース範囲とページとともに記録します。本文が使うリソースのキャプション、注記、表のセルの中にある`:ref`も同様です。

### 初出順の番号付け

リソースの番号は、**読む順序で最初に言及されたとき**に割り当てられます。最初の言及が`::resource`のブロック埋め込みでもインラインの`:ref`でも同じです。以降、同じIDへの参照はすべて同じ番号を表示します。

つまり番号は、パネルでリソースを作成した順ではなく、読者が出会う順に付きます。

- 序論で図を`:ref`で参照し、2ページ後で初めて（`::resource`で）埋め込んだ場合も、その図には序論の時点の番号が付きます。参照のほうが先だからです。
- 文書の*前のほう*に新しい参照を挿入すると、それ以降はすべて自動的に番号が振り直されます。手作業で番号を合わせる必要はありません。

番号はリソースの種類ごとに付けられ、種類ごとのリセット範囲とカウンターの書式に従います。テンプレートのトークン（`{h1}`、`{n}`）、`resetOn`、`counterFormat`については[設定 › リソースの種類](/ja/docs/configuration#リソースの種類)を参照してください。

数えられるのは本文が参照するものだけです。デザインだけが描くリソース（たとえば章扉の画像要素）には番号が付かず、カウンターも変わりません。また`{h1}`は、スタイルが`numbered: false`でないすべてのレベル1見出しを数えます。`numberingTemplate`が空の見出しも含むため、唯一のH1がタイトルである記事では、図の番号は既定で1.1、1.2…となります。[設定 › 番号が付くもの](/ja/docs/configuration#番号が付くもの)に、この2つの規則と、図1、図2…と番号を付けるための設定があります。

### 配置

各リソースには、フロートの置き場所を決める**配置**があります。配置はリソースごとに、まずリソース自身の`placement`、次にその種類の`defaultPlacement`、最後に組み込みの既定値`auto` / `column`の順に解決されます。

| 項目 | 値 | 意味 |
| --- | --- | --- |
| `position` | `"auto"` · `"top"` · `"bottom"` · `"here"` | `"auto"`（既定値）は、上端・下端を問わず参照の後にある最初の空き位置を取ります。`"top"` / `"bottom"`はその種類の位置だけを受け入れます。`"here"`はフロートをやめ、`::resource`ディレクティブの位置で本文中に埋め込みます。 |
| `width`, `align` | `0 < width < 1`; `"left"` · `"center"` · `"right"` | 位置より幅の狭いリソースに使います。`width`は段（またはページ）の幅に対して占める割合、`align`は位置の中での置き場所です（段の中央に置く小さな表、1段分の幅の写真を載せるページ幅の帯など）。位置より幅の狭い画像（段より小さいビットマップや、`layout.fitFiguresToPage`で縮小されたもの）も`align`に従って置かれ、その下のキャプションは位置の行長を保ちます。フロートにもインラインの`::resource`埋め込みにも適用されます。 |
| `captionSide` | `true` · `false` | サイド段をフロート専用にした1段半レイアウト（`layout.sideColumnRole: 'floats'`）では、`captionSide`を指定した`"column"`フロートは本体を主段に置き、キャプション（と注記）をサイド段に、図の上端（下端のフロートでは下端）の高さにそろえて組みます。サイド段はその帯を明け渡します。そのような段のないページでは、キャプションは図の下に置かれます。 |
| `span` | `"column"` · `"page"` | 1つの段を占めるか、段の流れを断ち切ってすべての段にわたる版面の全幅を占めるかを選びます。1段組みのレイアウトでは両者は同じです。 |
| `rotate` | `"ccw"` · `"cw"` | リソースを90度回転して組みます。縦長の本に入れる横長の表などに使います。`"ccw"`は反時計回りに回転し、上端がページの左端を向きます（読者は本を時計回りに回して読みます）。これが一般的な慣習です。`"cw"`はその逆です。回転したリソースは常に、専用のページに置かれるページ幅のフロートになります。版面の高さに沿ってレイアウトされ、その長さはベースライングリッドの行単位に切り下げたうえで、本文1行分（すべてのフロートの帯が保つフロートのアキ）を差し引いたものです（14ptのグリッドで237mmの版面には47行、232.1mmが入るので、リソースはそのうち46行、227.2mmを使います）。余白を左右対称にしている場合は背の側に寄せ（それ以外は左そろえ）、1ページに収まらないほど幅の広い表は行の間で切られ、ヘッダーを繰り返しながら、回転したまま次のページ以降に続きます。これは1ページより背の高い通常の向きの表とまったく同じです。回転した図はページに収まるように縮小されます。インライン（`"here"`）の埋め込みでは無視されます。 |

フロートは、読む順序で**最初の参照の後にある最初の空き位置**に置かれます。順に、参照がある段の下端、同じページで次に空いている段の上端と下端、そして流れが開く次のページの帯です（ページ幅のフロートは、すべての段にまだ収まる余地があればページの下端を取り、そうでなければ次のページの帯を取ります）。インラインの図や表が開くページも対象になります。そのページを待っているフロートは、両方が収まる場合、図や表の上にあるページの先頭を取ります。収まらない場合は図や表がそのページを使い、フロートは次のページを待ちます。postext 1.4までは、そのようなページは飛ばされ、両方が収まる場合でもフロートはその次のページを待っていました。フロートが縮小されることはなく、参照より前に置かれることもありません。同じ番号の系列のフロートは参照の順に現れます。あるページのどこにも収まらない図は、後ろの図を待たせます（待っている表が図を待たせることも、その逆もありません）。そのため図12が図11より前に現れることはありません。待つことになる表は、代わりに分割されます。空いた段の先頭が提供されると、収まる行だけを取り、ヘッダー行を繰り返して次の位置（隣の段か次のページ）に続きます（`tableStyle.overflow`を参照）。

フロートが章の外に出ることはありません。章扉（`breakBefore`または`span: 'page'`を持つ見出しレベル）、`:::part`、`floatBarrier: true`を指定した囲みスタイル（章末の「要点」の囲み）、文書の末尾では、保留中のフロートがすべて先に配置されます。置かれるのは、そのページの空き位置か、境界より前に開いたページです。章扉自体が最初に参照するフロート（自分の図を挙げる章タイトル）や、`:::part`の後の最初のブロックが最初に参照するフロートは新しい章に属し、ほかのフロートと同じくその行の後に置かれます。ページの先頭を求めた図や表は、専用のページではなく、章の最後のページの、段末をそろえた段の下にある下端を取ることがあります。`:::pagebreak`は、保留中のフロートをその後のページに送るだけです。

フロートの帯はベースライングリッドに合わせて補正され、周囲のテキストはページ全体の縦のリズムを保ちます。**上端**の帯は下側の余白を次のグリッド線まで広げるので、フロートの下のテキストは隣の段や向かいのページとそろったままになります。**下端**のフロートは、キャプションの最終行がほかの段の最終行とベースラインを共有するように固定されます（キャプションのない内容は下端を最後のグリッド位置にそろえます）。そのため満杯のページは、段をまたいでも見開きをまたいでも同じ高さで終わります。

章の最後のページ（および文書の最後のページ）では、テキストの最後の帯の下に組まれたページ幅の図や表の後には何も続きません。そのため、それらはテキストの下にフロートのアキ1つ分だけ空けて、順に積み重ねて上に移動し、テキストとページ下端の図の間に空白を残しません。`position: 'bottom'`のフロートも同じです。ほかのページと同じく下端に置いたままにするには、`layout.hugClosingFloats: false`を設定します（[設定 › レイアウト](/ja/docs/configuration#レイアウト)を参照）。サイド段のあるページでは移動しません。

canvasのプレビュー、HTMLビューアー、PDF出力の3つのバックエンドすべてがリソースを描画します。HTMLバックエンドでは画像データが本体とは別に保持されるため、ホストが`resourceImageUrl(fileId)`リゾルバーオプションで渡します。リゾルバーがない場合（またはファイルに対して何も返さない場合）、リソースは中立的なプレースホルダーの枠として描画され、レイアウトは崩れません。動画のファイル自体も、同じように`resourceVideoUrl(fileId)`で渡します（[動画](#動画)を参照）。

#### フロートが置かれる場所

「参照より前には置かない」は、フロートを参照する行から数えます。フロートはその行が組まれるまで待ち、読む順序でその後にある最初の空き位置を取ります。その行が組まれるページの先頭は、行より前にあたります。サイドフロート（`span: 'side'`。1段半レイアウトのフロート専用のサイド段に置くもの）は例外で、参照するテキストの横のサイド段に積み重ねられ、参照行よりページの上のほうに置かれることもあります。5ページで参照される図の場合は次のとおりです。

| 配置 | 5ページでは | それ以外 |
| --- | --- | --- |
| `top`, `span: 'page'` | 置かれません。ページ先頭の帯は参照行より上にあります。 | 6ページの上端の帯。 |
| `top`, `span: 'column'` | まだ空いている後続の段の先頭。2段組みの1段目で参照された場合、2段目の先頭に置けます。 | 6ページのいずれかの段の先頭。 |
| `auto`または`bottom`, `span: 'page'` | すべての段にまだ余地があれば、5ページの下端の帯。 | 6ページの帯。 |
| `auto`または`bottom`, `span: 'column'` | 参照する段の下端。次に、後続の空いた段の下端（どちらの値でも）または先頭（`auto`のみ）。 | 6ページ。 |

- 章扉のページにも同じ規則が適用されます。章扉の最初の段落で参照されたページ幅の`auto`または`bottom`のフロートは、そのページの下端の帯（テキストの下）を取れます。`top`のフロートは次のページの先頭に置かれます。参照するページに画像を置くには、`auto`か`bottom`を使うか、章扉のデザインの画像要素として描きます。
- 同じ段落で参照された2つの段のフロートは、続く2つの位置を取ります。通常、1つ目は参照する段の下端、2つ目は次の空いた段の先頭に置かれ、ページ上で横に並びます。
- 1段組みのレイアウトではページ幅のフロートは段のフロートと同じで、同じ規則が適用されます。あるページで参照された`top`のフロートは、次のページの先頭に置かれます。
- ページをまたぐ段落も、参照行から数えます。段落が5ページの下端で始まり、参照が6ページにある場合（あるいは、5ページの下端に収まる行が足りず段落全体が6ページに移る場合）、参照は6ページにあることになります。`top`のフロートは7ページの先頭に置かれ、`auto`のフロートは余地があれば6ページの下端を取ります。同じページの段の間や、ページをまたいで分割された囲みでも同様で、囲みの2つ目の部分が参照する図はその部分を待ちます。
- **postext 1.5での変更**。postext 1.4までは、フロートを参照する段落にレイアウトが達した時点でフロートが待ち行列に入っていたため、そのような段落が続く（または移る）ページの先頭、参照を含む行より上にフロートが置かれることがありました。現在そのような図は1ページ後に置かれるか、`auto`を求める場合はそのページの下端に置かれます。その結果、ページ数が変わることがあります。

### セーフエリア

ビットマップやSVGのリソースには**セーフエリア**を指定できます。画像の中で重要なもの（人物とその背後の風景の一部、グラフのプロット部分など）を含み、常に表示される長方形です。これはリソースの`safeArea`で、画像の固有サイズに対する4つの割合（0〜1）を左上の角から測ります。`x`と`width`は幅に対する割合、`y`と`height`は高さに対する割合です。この名前は残すべきものを表します。トリミングの枠なら、どこを切るかを表すことになります。

```ts
const harbour: Resource = {
  id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.',
  createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 },
  // the boats and the quay: 18–68 % of the width, 25–85 % of the height
  safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 },
};
```

トリミングされるのはセーフエリアのある画像だけです。その場合エンジンは、画像全体からセーフエリアまでの間の任意の縦横比で画像を表示できます。左右を切り落として画像本来の比率より縦長にする場合はセーフエリアの幅まで、天地を切り落として横長にする場合はセーフエリアの高さまでです。図の幅は変わらず、変わるのは高さだけです。セーフエリアの外側は、その両側の余白に比例して切り落とされるので、中央より左にある被写体は中央より左に残ります。上の港の画像を幅60mmで組むと、全体を表示したときの高さは40mmで、24mm（天地を高さの60%まで切り落とす）から80mm（左右を幅の半分まで切り落とす）までの任意の高さで表示できます。画像の端を超える値は端に収められます。数値でない値を含む範囲、辺が画像の2%未満の範囲、画像全体を覆う範囲は無視され、表に指定した場合も無視されます。セーフエリアがなければ、画像はこれまでどおり常に全体が表示されます。

エンジンはこの余裕を3つの場面で使います。

- **段に残った余地**。インラインの画像（`position: 'here'`）が段に残った余地に対して少し高すぎる場合（キャプションがページの下端を超えてしまう場合も含む）、次の段やページに移ってこの段を短く残す代わりに、セーフエリアの範囲でトリミングしてその段にとどまります。
- **図より短いページ**。`layout.fitFiguresToPage`を指定すると、ページに対して高すぎる画像はまず幅を保ったままセーフエリアの範囲でトリミングされ、それでも高すぎる場合にだけ縮小されます（[設定 › レイアウト](/ja/docs/configuration#レイアウト)を参照）。
- **段末そろえ**。短い段にインラインで組まれた画像や、その段だけにかかるように段の先頭か下端にフロートとして置かれた画像のうち、セーフエリアのあるものは、段の空いた行を埋めるようにベースライングリッドの行単位で高くなります。画像が高くなっても目に見える穴は残らないので、この調整手段`flexFigure`は、段を閉じる囲みの調整の直後、見出しの上やリストの後にアキを加えるより前に試されます。章の最後のページや閉じの帯で段の先頭に置かれたフロートは高くなりません。それらの段の先頭は高さをそろえたままにするためです（[設定 › 段末そろえ](/ja/docs/configuration#段末そろえ)を参照）。

VDTはトリミングをリソースのブロックに記録します。`bodySource`は`bodyRect`に表示される画像の部分で、同じ割合で表します（画像全体が収まる場合はありません）。`bodyFlex`は、本体がまだ縮められる量と伸ばせる量、および調整手段がすでに変えた量をpxで示します（`{ shrink, grow, delta }`）。canvasのプレビューとPDFは本体でクリップし、トリミングしない大きさで画像全体を描きます。HTMLビューアーと固定レイアウトのEPUBは、`object-fit: cover`とそれに合わせた`object-position`で画像を組みます。埋めるべきページのないリフロー型のEPUBでは、画像全体を表示します。画像を自前で描くホストは、`postext`がエクスポートするヘルパーを使えます。`resourceSafeArea`と`normalizeSafeArea`（エンジンが読み取るセーフエリア、または`undefined`）、`safeAreaHeightRange`（ある幅での本体の最小と最大の高さ）、`safeAreaSource`（ある高さで表示される部分）、`uncroppedPictureBox`（クリップの前に画像全体を描く位置）、そして型`ResourceSafeArea`です。Sandboxでは、[**リソース**パネル](/ja/docs/sandbox#リソースパネル)の画像にある**セーフエリア**の項目で設定します。

レシピ集のNo. 116「[短い段を埋めるように伸びる写真](/ja/cookbook/photos-fill-short-columns)」は、2段組みの雑誌特集をセーフエリアなしとセーフエリアありの2回組むので、ページを並べて比べられます。

### 動画

**動画**リソース（`kind: 'video'`）は、YouTubeまたはVimeoの動画、あるいは自分の動画ファイル（MP4、WebM）です。画像と同じように配置、キャプション付け、フロート、参照ができ、独自の系列で番号が付きます。組み込みの`video`の種類は、*Figure 1.1*や*Table 1.1*と並んで*Video 1.1*、*Video 1.2*…と表示します（[設定 › リソースの種類](/ja/docs/configuration#リソースの種類)を参照）。各出力は、それぞれ可能な形で動画を表示します。

| 出力 | 表示されるもの |
| --- | --- |
| Canvas、PDF、Folio | 動画の1フレームである**ポスター画像**に、再生マークと動画を開くQRコードを重ねて表示します（[設定 › 動画スタイル](/ja/docs/configuration#動画スタイル)）。PDFでは、ポスター画像は動画へのリンクにもなります。 |
| HTMLビューアー | 動画の**プレーヤー**を表示します。YouTubeやVimeoのプレーヤー、ファイルの場合はブラウザーのHTML5プレーヤーです。`videoStyle.html: 'poster'`を指定すると、代わりに印刷用のポスター画像を表示します。 |
| EPUB | ファイルは本に同梱されるか公開先のアドレスから読み込まれ、リーディングシステム自身のプレーヤーで再生されます。YouTubeやVimeoの動画は、動画にリンクしたポスター画像になります。EPUBにはWebページのプレーヤーを埋め込めないためです。 |

```ts
const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'The keeper explains the lamp.',
  altText: 'A lighthouse keeper beside the lamp',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // plays from 0:30; the printed link starts there too
  },
};
```

本文は図と同じように動画を参照します。`:ref{id="keeper-talk"}`は*Video 1.1*と表示し、参照の後にある最初の空き位置へポスター画像をフロートとして配置します。`placement.position: 'here'`を指定して`::resource{id="keeper-talk"}`を書くと、本文中に組まれます。`Resource.video`（`ResourceVideo`）の項目は次のとおりです。

| 項目 | 型 | 意味 |
| --- | --- | --- |
| `source` | `'youtube'` · `'vimeo'` · `'file'` | 動画の再生元。 |
| `url` | `string` | YouTubeまたはVimeo：動画のアドレス。形式は問いません（視聴ページ、`youtu.be`、ショート、埋め込みリンク、`youtube-nocookie.com`。Vimeoのページ、チャンネルのページ、ハッシュ付きの限定公開リンク）。ファイル：その**公開先のアドレス**、つまり公開された本がファイルを見つける場所。 |
| `fileId`, `format` | `string` | ファイル：アップロードした動画（ビットマップと同じく本体とは別に保存されます）とその形式（既定値の`'mp4'`、`'webm'`、`'ogv'`、`'mov'`）。 |
| `poster` | `{ fileId, format, width, height }` | ポスター画像のフレーム（ビットマップ）。 |
| `width`, `height`, `duration` | `number` | 動画のフレームサイズ（px。ポスター画像がない場合は縦横比として使います）と長さ（秒）。 |
| `posterTime` | `number` | ファイルのどの秒のフレームをポスター画像にしたか。選び直せるように保存されます。 |
| `start`, `end` | `number` | `start`秒から`end`秒まで再生します。QRコードとPDFのリンクも`start`から始まります。 |
| `player` | `VideoPlayerOptions` | この動画のプレーヤーオプション。`videoStyle.player`の上に重ねて適用されます。 |

**ポスター画像**。その位置の行長（またはその`placement.width`の割合）で、ピクセルサイズにかかわらず自身の縦横比で組まれます。画面サイズのフレームは、小さく印刷されるのではなく拡大されます。ビットマップと同じく[セーフエリア](#セーフエリア)を持つことができ、`placement.align`に従います。ポスター画像のない動画は、動画の縦横比（指定がなければ16:9）の暗い枠をオーバーレイ付きで印刷し、`videoWithoutPoster`の内容の警告を出します。Sandboxでは、YouTubeやVimeoの動画のポスター画像はアドレスを入力したときにプラットフォームから取得され、ファイルの場合は動画の中から選んだフレームになります。

**アドレス**。QRコードとPDFのリンクは、動画のページ`https://youtu.be/<id>`または`https://vimeo.com/<id>`を`start`の位置から開きます。ファイルにはページがないので、公開先のアドレスを開きます。それがない場合、印刷物にはQRコードもリンクも付かず（`videoWithoutUrl`）、ファイルを含まないHTMLやEPUBの出力はポスター画像を表示します。YouTubeやVimeoのアドレスがそのプラットフォームの動画を指していない場合は`videoUrlInvalid`が出て、プレーヤーの代わりにポスター画像が表示されます。

**プレーヤー**。プレーヤーのオプション（コントロール、ダウンロードボタン、全画面表示、速度メニュー、ピクチャーインピクチャー、キャスト、自動再生、ミュートでの開始、ループ、プリロード、プライバシー強化モードの埋め込み）は、本全体には`videoStyle.player`で、1つの動画には`video.player`で設定します。各プレーヤーは対応できる範囲でこれに従います（[設定 › 動画スタイル](/ja/docs/configuration#動画スタイル)を参照）。HTMLバックエンドは、画像を`resourceImageUrl`で受け取るのと同じように、ファイルの再生可能なURLを`resourceVideoUrl(fileId)`オプションで受け取り、なければ公開先のアドレスを使います。その`videos: { files, streams }`オプションは、`videoStyle.html`に優先して、再生元ごとにプレーヤーかポスター画像かを選びます。EPUBライターもこれを使います。右から左の本では、QRコードが読めるように、プレーヤーとポスター画像のオーバーレイは画像と同じく向きが元に戻されます。

**VDTでの表現**。動画のリソースのブロックは`kind: 'video'`、ポスター画像としての`fileId` / `format`（ビットマップと同じように描画されます）、そして`video`（`VDTResourceVideo`）を持ちます。その中身は、読者を送る`link`、プレーヤーオプションを適用したYouTubeまたはVimeoの`embedUrl`、ファイルの`fileId`と`mimeType`、`start` / `end`の範囲、解決済みの`player`、`linkPoster`、`html`、そしてオーバーレイの`playMark`と`qr`（QRのモジュールを`'0'` / `'1'`の行として表したもの）で、矩形は本体の左上の角からの相対位置です。動画を自前で描くホストは、`postext`がエクスポートするヘルパー`parseVideoUrl`、`videoWatchUrl`、`resourceVideoLink`、`videoEmbedUrl`、`videoEmbedAllow`、`videoElementAttributes`、`mediaFragment`、`videoMimeType`、`youtubePosterUrls`、`encodeQr`、`layoutVideo`、`playMarkTriangle`、`qrModuleRuns`を使えます。

**バンドルでの表現**。`.postext`は動画ファイル（`resources/<id>.mp4`）とポスター画像（`resources/<id>.poster.jpg`）を含みます。マニフェストの項目は`file`と`poster`でそれらを指定し、`width` / `height`でポスター画像のサイズを示し、残りはファイルIDを除いて`video`に保持します。`bundleVideoUrl(bundle)`は、バンドルのファイルを対象とする`resourceVideoUrl`リゾルバーです。

レシピ集の2つのレシピが動画を組んでいます。No. 131「[ポスター画像にQRコードを刷った映画クラブのプログラム](/ja/cookbook/film-club-video-qr)」は、映画ごとに再生マークとQRコードの付いたタイトルカードを刷ります。No. 132「[画面とEPUBで動画が再生される実験シート](/ja/cookbook/pendulum-lab-video-players)」は、HTML版のプレーヤーオプションを設定し、自前の動画を固定レイアウトのEPUBに同梱します。

## 対応していない記法

Postextは次のCommonMarkの機能を認識しません。これらはプレーンテキストとして扱われる（したがって出力にそのまま表示される）か、何も言わずに破棄されます。

- **Setext形式の見出し**：`===` / `---`の下線の形式。ATX（`#`）の見出しを使ってください。
- **フェンスまたはインデントによるコードブロック**：` ``` `や`~~~`のフェンスと4スペースのインデント。中の行はプログラムリストとして保持されず、通常のMarkdownとして読まれます。空行を挟まない行は1つの段落に結合されて先頭のスペースを失い、`#`とスペースで始まる行は見出しに（`#!/usr/bin/env`はテキストのまま）、`-`や`1.`とスペースで始まる行はリスト項目になり、`$`記号の対は数式になり、フェンスの行はテキストとして印字されます。` ``` `のフェンスは1つのバッククォートとして（開始側はその後に情報文字列が続きます。`` `bash``）、`~~~`のフェンスは下付きの小さな`~`1つとして印字されます。プログラムリストを組むには、各行をそれぞれ独立した段落として（行の間に空行を入れて）、段落スタイルで等幅の`fontFamily`を指定した`:::paragraphs`ブロックの中に書き、各行をバッククォートで囲みます。バッククォートの中では`#`、`$`、`*`などが書いたとおりに保たれます。行頭の通常のスペースは削除され、行中の連続したスペースは1つに縮められます。これはバッククォートの中でも同じなので、字下げや位置合わせにはノーブレークスペース（U+00A0）を使い、バッククォートの内側に入れます。開始のバッククォートの前に置いたものも削除されます。インラインコードは認識されますが、コード用の書体はありません。[インライン書式](#インライン書式)を参照してください。
- **HTMLのパススルー**：生の`<tags>`は解釈されません。MDX形式のタグにも対応していません。Postextのソースは純粋なMarkdownです。
- **水平線**：`---`、`***`、`___`。
- **表**：パイプ形式の表は解析されません。表は`PostextContent.resources`上の構造化されたリソースとしてモデル化されます。
- **参照形式のリンク**：`[text][id]`と定義ブロックの組み合わせ。
- **自動リンク**：`<https://example.com>`。
- **取り消し線**：`~~text~~`。取り消し線のレンダラーは現在、完了したタスク項目のために予約されています。
- **傍注**：実装されていません。型としては受け付ける`PostextContent.notes`も、エンジンは無視します。脚注と章末の注は`[^id]`で書きます（[脚注](#脚注)を参照）。postext 1.5までは、テキストとして組む必要がありました。

この一覧は今後短くなっていきます。それまでは、上の対応している記法のセクションに明記されていないものは、すべてそのままのテキストとして扱われると考えてください。

記法以外では、アラビア語などの右から左に書く文字は、双方向アルゴリズムと右綴じによって右から左に組まれます（[アラビア語の組版](/ja/docs/arabic-layout)を参照）。中国語は横組みでも縦組みでも組め、その地域が求める改行規則、約物の幅、文字間の両端そろえ、圏点などの記号、ルビ、割注に対応します（[中国語の組版](/ja/docs/chinese-layout)を参照）。日本語は独自の規則、つまり禁則処理、約物のアキ、ルビ、圏点、漢文の訓点、注で組まれます（[日本語の組版](/ja/docs/japanese-layout)を参照）。韓国語は同じコンポーザーを通り、中国大陸の規則で組まれます。ハイフネーションのパターンは8言語分が同梱され、組み込みのラベルはその8言語と中国語、日本語、アラビア語の分があります。[言語と文字体系](/ja/docs/configuration#言語と文字体系)を参照してください。

## 記述の決まりごと

いくつかの決まりごとを守るかどうかで、文書がきれいに解析されるか、思わぬ結果になるかが分かれます。

- **ブロックの間には空行を入れます**。空行で区切った2つの段落は2つの段落になります。連続した行に書いた2つの段落は1つになり、各行は前の段落にまとめられます。
- **余分な空行はアキを増やしません**。3つの空行は、1つの空行とまったく同じように2つのブロックを区切ります。間を広げたいときは[`:::space`](#space)の行を書きます。
- **入れ子の項目は上の項目のテキストの位置まで字下げします**。CommonMarkのリストの入れ子と同じく、箇条書き（`- `）の下では2スペース、`1. `の下では3スペース、`10. `の下では4スペースです。`1.`の下の2スペースでも入れ子になります。項目は、マーカーが2文字分以上左にある最も近い開いた項目の下に入れ子になるので、1スペースでは何も入れ子にならず、字下げの幅にかかわらずレベルが飛ぶことはありません（postext 1.15までは深さが`floor(spaces / 2) + 1`で、`   1.`の下の`      1.`はレベル4になっていました）。タブは次の4の倍数の文字位置まで進みます。深さの上限は5です。
- **リストの最初の項目は字下げしません**。レベル1の項目は行頭から始まります。リストの最初の項目は、どれだけ字下げしてもレベル1になります（postext 1.15までは先頭のスペースで深さが上がっていました）。そのため入れ子にするには、その上に入れ子の親となる項目が必要です。
- **タスクマーカーは角かっこと1つのスペースで書きます**。`[ ]`、`[x]`、`[X]`のみで、ほかの書き方は使えません。`[*]`や`[-]`はタスクマーカーではなく、そのままのテキストとして表示されます。
- **リストの中の引用ブロックには対応していません**。引用ブロックはリストの外、行頭から始めてください。
- **画像と表は`resources`に置きます**。インラインの`![alt](src)`は削除されます。インラインの画像は段を考慮した配置を壊すからです。各画像をリソースとして宣言し、IDで参照してください。そうすれば、フロートにするか、段を断ち切るか、次のページの先頭に移すかをエンジンが決めます。
- **数式のつもりでないドル記号は`\$`でエスケープします**。Postextは`$…$`をインラインのLaTeXとして解釈するので、本文中の生の`$`は数式を始めてしまいます。価格やシェルのプロンプトなど、ドル記号を単独で使うものは`\$`と書いてください。
- **中国語や日本語のテキストでも、マークアップはASCIIで入力します**。中国語や日本語の入力メソッドでは全角の形が入力されます。フェンスの`：：：`、見出しの`＃`、脚注マーカーの`［＾1］`、属性の`｛…｝`、太字の`＊＊`などです。これらはテキストとして印字され、ビルドはその行を`fullwidthMarkup`警告として報告し、入力すべきASCIIの形を示します。属性値はどの文字体系でもよく、`“…”`や`「…」`で囲めます。キーはASCIIのままです。

## 作例

サポートしているすべての構文を使った短い文書です。

```md
---
title: The Typesetter's Craft
author: Anon
---

# Opening

A good book reads itself. The **reader** should never notice the
typesetter's work — only the author's voice.

## What makes text readable

Three properties matter most:

1. Line measure — 40 to 75 characters per line.
2. Leading — 1.3 to 1.5 times the font size.
   a. Tighter at short measures.
   b. Looser at long measures.
3. Contrast between body and headings.

Common failure modes include:

- Lines that stretch across the whole page.
- Headings that float without a following paragraph.
- Orphans and widows at column boundaries.

> Typography is the craft of endowing human language with a durable
> visual form.
> — Robert Bringhurst

### Review checklist

- [x] Column width under 75 characters
- [x] Leading set to 1.5
- [ ] Orphan and widow pass
- [ ] Final proofread

### A note on formulas

Inline math such as $a^2 + b^2 = c^2$ flows with the surrounding text, and
display math sits centred on the baseline grid:

$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$
```

同じ文書を組版エンジンに通すと、構造化された`VDTDocument`が生成され、そのページはこれらの各ブロックを型付きの項目として持ちます。ブロックがどのように幾何情報になるかは、[アーキテクチャー](/ja/docs/architecture)のページを参照してください。