# 設定：注と参照

> 脚注、行番号、相互参照と引用、目次、巻末の索引

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

## かんたんな説明

このページでは、本の中でほかの場所を指し示す部分の設定を説明します。脚注はページの下に、行番号は余白に入ります。相互参照は図や節やページを指し、引用はあなたが挙げる文献を指します。目次は章を並べ、巻末の索引は用語とそのページを並べます。各節で、これらの見た目と番号の付け方を説明します。

## 脚注

`footnotes`プロパティは、`[^id]`で引用した注をどこに置き、どのように番号を付け、どのような見た目にするかを設定します。記法は[文書形式](https://postext.dev/ja/docs/document-format.md#脚注)で説明しています。

```ts
interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // Foot of the citing column, after the chapter, or beside the text of a spread.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Start again at each chapter, run on, or start again on each page / column / spread.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // numberFormat: 'symbols' で使う参照記号。
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Raised, on the baseline, beside the word, or right of a vertical line.
  markerSize?: Dimension;     // Inline, side or right marker size; em is the text around it.
  numberGap?: 'en' | 'em';    // Space after the note's own number.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notes at the column foot, or under the text.
  fontSize?: Dimension;       // Note size; em is the body size.
  lineHeight?: Dimension;     // Note leading; em is the note size.
  color?: ColorValue;         // Note colour; the body colour when unset.
  textAlign?: TextAlign;      // The body alignment when unset.
  hangingIndent?: Dimension;  // Indent of a note's turnover lines.
  spaceBetween?: Dimension;   // Space between two notes.
  spaceAbove?: Dimension;     // Space between the text and the rule; em is the body size.
  spaceBelowRule?: Dimension; // Space between the rule and the first note.
  separator?: {
    enabled?: boolean;        // Draw the rule.
    width?: number;           // Rule length, a fraction of the column width.
    lineWidth?: Dimension;    // Rule thickness.
    color?: ColorValue;       // The note colour when unset.
  };
}
```

| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `placement` | `'column' \| 'chapterEnd' \| 'spread'` | `'column'`（日本語の縦組みの本：`'chapterEnd'`） | `'column'`は、各注を、それを引用する行がある段の下端に、短い罫線の下に組みます。1段組みのレイアウトではページの下端になります。`'chapterEnd'`は、章のすべての注を、その章の最後のブロックの後に引用順に組みます。`'spread'`（傍注、縦組みのみ）は、見開きの両ページで引用された注を、奇数ページ（右綴じの本では左ページ）の末尾に罫線の下に組みます。偶数ページで引用された注は奇数ページまで待ちます。奇数ページに残る本文が1行未満になってしまう注は、それ以降の注とともに偶数ページの下端にとどまり、偶数ページで終わる章は、待っている注をそこに組みます。横組みでは`unknownConfigValue`の警告を出して`'column'`にフォールバックします。postext 1.16以降。 |
| `numbering` | `'chapter' \| 'document' \| 'page' \| 'column' \| 'spread'` | `'chapter'`（日本語の横組みの本：`'page'`、`placement: 'spread'`の場合：`'spread'`、段の下端の注で`numberFormat: 'symbols'`の場合：`'page'`） | `'chapter'`は、レベル1の見出しのたびと文書の始まりで、1から番号を振り直します。`'document'`は文書全体を通して番号を続け、章ごとにレイアウトする本では章から章へと続けます（`continuationAfter`が最後の番号を`continuation.footnoteNumber`として引き継ぎます）。`'page'`はページごとに、`'column'`は段ごとに1から振り直し、レイアウトが注を組んだ位置で（ページ内の段は読む順に）注を数えます。中国語の本で一般的な页下注です。文書はいったんレイアウトされ、注が置かれた位置で番号が付けられ、番号が安定するまで再びレイアウトされます（追加のビルドは最大3回）。どちらも段の下端の注に適用され、`placement: 'chapterEnd'`では注は章ごとに番号が付きます。`'spread'`は、`placement: 'spread'`用に、見開き（2–3ページ、4–5ページ…）ごとに引用順で振り直します。 |
| `numberFormat` | `string` | `'decimal'` | 番号の書き方です。番号付けの設定が受け付けるどの表記でも指定できます（`'decimal'`、`'lower-roman'`、`'lower-alpha'`、`'circled-decimal'`（または`'①'`）、`'cjk-decimal'`、`'一'`…）。本文中の合印と、注の冒頭の番号の両方に使われます。`circled-decimal`は50を超える番号を10進数で書きます。未知の名前は、`unknownNumberFormat`の警告とともに10進数で番号を付けます。`'symbols'`（または`'*'`）は、`symbols`の参照記号を順に使って注を示します（* † ‡ § ‖ ¶、使い切ると二つ重ね（** †† ‡‡…）、さらに三つ重ね）。このとき注は、`numbering`を指定しない限りページごとに数え直されます。postext 1.19から。 |
| `symbols` | `string[]` | `['*', '†', '‡', '§', '‖', '¶']` | `numberFormat: 'symbols'`が書く記号の並びです。使い切ると二つ重ね、さらに三つ重ねになります。Google FontsとFontsourceのラテン文字ファイルには * † § ¶ があります（ダガーは`latin-ext`）が、‡ と ‖ はなく、PDFではフォントの`.notdef`グリフで描かれ、`missingGlyph`の警告が出ます。そのようなフォントでは、この二つを外す（`['*', '†', '§', '¶']`）か、それらを持つフォントで注を組んでください。空の文字列は無視され、空のリストは既定の並びのままです。postext 1.19から。 |
| `markerPosition` | `'auto' \| 'superscript' \| 'inline' \| 'side' \| 'right'` | `'auto'` | `'superscript'`は、本文中の合印と注の冒頭の番号を、縮小したサイズで上付きにします。`'inline'`はそれらをベースライン上に組みます。合印は`markerSize`、注の番号は注のサイズです。縦組みでは、行内の丸数字の合印は専用のセルの中で正立します。`'right'`は、日本語の縦組みの本が（1）を組むように、縮小した合印を縦の行の右側にそろえて組みます。横組みでは上付きになります。`'side'`（合印）は、印を付けた語の脇、ルビの側に小さな合印を組み、語の最後の文字が終わる位置で終わらせます。行の中で場所を取らないため、行はそれがないものとして改行・両端そろえされます。それを収めるには狭すぎる行間は`rubyExceedsLeading`として報告されます。`'auto'`は、`circled-decimal`ではinline、日本語の縦組みの本では`'right'`、それ以外では上付きになります。どの場合も、合印は直前の文字から離れず、行頭に来ることはありません。 |
| `markerSize` | `Dimension` | `1em`。`'side'`では`0.6em`、`'right'`では`0.7em` | インライン、脇、右の合印のサイズです。`em`は周囲のテキストのサイズです（`0.75em`がよく使われる縮小率です）。上付きの合印には影響しません。 |
| `numberGap` | `'en' \| 'em'` | `'en'`（日本語の後注：`'em'`） | 注の冒頭の番号の後のアキです。二分アキ、または注の全角アキ（番号か注にCJKのテキストが含まれる場合は和文の全角スペース）で、伸縮も改行もしません。postext 1.16以降。 |
| `markerTemplate` | `string` | `'{n}'`（日本語の縦組みの本：`'（{n}）'`） | 注の番号の書き方です。`{n}`が、番号の書式と文書の数字で書いた番号を表します。`'({n})'`とすると、アラビア語の本の括弧付きの合印«(١)»になります。本文中の合印と注の冒頭の番号の両方を、この形で書きます。`{n}`を含まないテンプレートは既定値として扱われます。 |
| `noteNumberPosition` | `'auto' \| 'superscript' \| 'inline'` | `'auto'` | 注の冒頭の番号の位置で、上付きにするか、注のサイズでベースライン上に置くかを決めます。`'auto'`は`markerPosition`に従います。アラビア語の本では、本文中の合印を上付きにし、注自身の番号はベースライン上に組みます。 |
| `chapterEndAlign` | `'foot' \| 'text'` | `'foot'` | `placement: 'chapterEnd'`の場合の配置です。`'foot'`は、段を閉じる注を段の下端に組み、余った行は本文と注のあいだに残ります。段の下端の注と同じ配置です。`'text'`は本文の直下に組みます。 |
| `fontSize` | `Dimension` | `0.8em` | 注の文字のサイズです。`em`と`rem`は本文のサイズです。注には本文のファミリーとウェイトが使われます。 |
| `lineHeight` | `Dimension` | `1.25em` | 注の文字の行送りです。`em`は注のサイズです。注はベースライングリッドから外れます。段の下端から積み上がり、その上の本文はグリッドに乗ったままです。 |
| `color` | `ColorValue` | 本文の色 | 注の文字の色です。 |
| `textAlign` | `TextAlign` | 本文の行そろえ | 注の文字の行そろえです。 |
| `hangingIndent` | `Dimension` | `0` | 注の2行目以降のインデントで、番号より後ろにそろえるためのものです。 |
| `spaceBetween` | `Dimension` | `0` | 2つの注のあいだのアキです。 |
| `spaceAbove` | `Dimension` | `0.5em` | 本文の最終行と罫線のあいだのアキです。`em`は本文のサイズです。`'chapterEnd'`と`chapterEndAlign: 'text'`の場合は、`spaceAbove`＋`spaceBelowRule`が本文と最初の注のあいだのアキになります。 |
| `spaceBelowRule` | `Dimension` | `0.4em` | 罫線と最初の注のあいだのアキです。 |
| `separator.enabled` | `boolean` | `true` | 各段の注の上に罫線を引きます。`false`の場合も、上のアキは残ります。 |
| `separator.width` | `number` | `0.3` | 段の幅に対する比率（0–1）で表した罫線の長さで、段の左端から引きます。 |
| `separator.lineWidth` | `Dimension` | `0.5pt` | 罫線の太さです。 |
| `separator.color` | `ColorValue` | 注の色 | 罫線の色です。 |

```ts
footnotes: {
  fontSize: { value: 7.5, unit: 'pt' },
  lineHeight: { value: 9.5, unit: 'pt' },
  hangingIndent: { value: 0.8, unit: 'em' },
  separator: { width: 0.25, lineWidth: { value: 0.4, unit: 'pt' } },
}
```

**日本語の本**。日本語の文書（`locale: 'ja'`、postext 1.16以降）では、未設定のフィールドにJLReq §4.2の値が使われます。縦組みの本は注を章の後に組み（`placement: 'chapterEnd'`、後注）、章ごとに番号を付け、合印`（{n}）`を行の右に置きます（`markerPosition: 'right'`、数字は`cjk.uprightDigits`により正立）。横組みの本は注をページの下端に組み、ページごとに番号を付け、合印を上付きにします。どちらも罫線を組幅の3分の1の長さで引き（`separator.width: 1/3`）、章の後に置く注には`numberGap: 'em'`と2字分のぶら下げインデントを使います。明示した値が優先され、保存時にも保持されます（`stripFootnotesDefaults`は文書自身の既定値と比較します）。中国語、アラビア語、ラテン文字の文書の解決結果は従来どおりです。`footnoteDocumentDefaults(locale, writingMode, placement?)`はこれらの値を返します。合印は文末の。の前に書いてください（`先生[^1]。`）。合印は直前の文字から離れず、。が行頭に来ることはありません。[日本語の組版 › 注](https://postext.dev/ja/docs/japanese-layout.md#注)を参照してください。

段の下端での注の組み方は次のとおりです。

- **注と引用箇所は同じ段に置かれます**。行を置く前に、レイアウトはその行が初めて引用する注の高さ（その段の最初の注の場合は罫線も）を加えます。その下に注が収まらない行は、オーファンとウィドウの規則に従い、段落の残りとともに次の段へ移ります。段の本文領域は注の高さの分だけ縮むため、段末そろえと章の最後の帯では本文だけが数えられます。
- **複数の注**が1つの段にある場合は、1本の罫線の下に引用順に積み重なります。あとで再び引用された注は番号を保ち、二度は組まれません。
- **下側のフロート**。注を組んだ後に段の下端を占める図は、注の上に入ります。図の後に組まれた注は図の上に入ります。
- **囲み**。囲み（インライン、フロート、固定）の中で引用された注は、囲みの後の本文が続く段の下端に置かれます。通常は同じ段です。文書を閉じる囲みは、本文が終わった段の下端に注を残します。
- **制限**。注は分割されません。段より高い注は段からはみ出します。キャプション、表のセル、見出しの中の合印は読み取られません（書いたとおりに印字されます）。
- **出力**。Canvas、HTML、PDFは注、合印（上付きの番号）、罫線を描画します。PDFでは各合印がその注にリンクし、タグ付きPDFでは各注を一意の`/ID`を持つ`Note`要素とし、構造ツリーの`/IDTree`に列挙します（PDF/UA-1）。注は`footnoteNote`が設定された`VDTBlock`として`page.floats`に、罫線は`page.footnoteAreas`に入ります。
- **警告**。`undefinedFootnote`（定義のない合印。番号は空の注の上に印字されます）と`unusedFootnote`（どの合印からも引用されない定義。組まれません）があります。

解決関数と除去関数は、ほかのセクションと同じ形です。

```ts
import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';

resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // unset fields take the Japanese vertical defaults
```

## 行番号

`lineNumbers`プロパティは、5行ごと（またはN行ごと）の行の番号を、その行の横の余白に印字します。校訂版、詩のアンソロジー、法令の本文、学校向けの版がこうして行番号を付けます。数えるのは`:::verse`の詩の行か、本文のすべての行です。既定では無効です。各番号は自分の行のベースライン上に独自のサイズで描かれ、行を動かすことはありません。ページは番号がない場合とまったく同じにレイアウトされます。postext 1.23から使えます。

```ts
interface LineNumbersConfig {
  enabled?: boolean;        // 既定では無効。
  count?: 'verse' | 'all';  // 詩の行か、本文のすべての行。
  interval?: number;        // Nの倍数を印字する。
  numberFirst?: boolean;    // 数え直しの後の最初の行も印字する。
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // 数え直す位置。
  startAt?: number;         // 数え直しの後の最初の行の番号。
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // 2段以上のページ。
  gap?: Dimension;          // 本文から番号までの距離。emは番号のサイズ。
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // 未設定なら本文のファミリー。
  fontSize?: Dimension;     // emは本文のサイズ。
  fontWeight?: number;      // 未設定なら本文のウェイト。
  italic?: boolean;
  color?: ColorValue;       // 未設定なら本文の色。
  format?: string;          // decimal、lower-roman、arabic-indic、一…
}
```

| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `false` | 行番号を印字します。縦組みの文書（`layout.writingMode: 'vertical-rl'`）には付かず、そこで`true`にすると`lineNumbersUnsupported`として報告されます。 |
| `count` | `'verse' \| 'all'` | `'verse'` | `'verse'`は`:::verse`の詩の行を、1行につき1回数えます。行長に収まらない詩の行が次の行に折り返した部分には番号が付かず、連と連のあきも数えません。古典アラビア語の配置で組んだ詩は、1ベイトを1行と数えます。段違いに組んだベイトの2行目は数えません。`'all'`は本文の段落、リストの項目、引用、詩のすべての行を、読む順に数えます。ページごと、段ごと、上から下へです。 |
| `interval` | `number` | `5` | この数の倍数にあたる行（5、10、15…）の番号を印字します。最初の行が37の詩では40、45…が印字されます。詩の開始行で独自の値を指定できます（`interval=N`）。 |
| `numberFirst` | `boolean` | `false` | 数え直しのたびに、最初に数える行の番号も印字します。 |
| `restart` | `'document' \| 'chapter' \| 'section' \| 'page' \| 'poem'` | `count: 'verse'`では`'poem'`、`count: 'all'`では`'page'` | 数え直す位置です。数え直さない（`'document'`。本の章をまたいで続きます）、レベル1の見出しごと（`'chapter'`）、レベル1か2の見出しごと（`'section'`）、ページごと（`'page'`）、`:::verse`の詩ごと（`'poem'`）のいずれかです。詩の`lineStart=N`と、`:::numbering`ディレクティブの`lines=N`は、どのモードでも任意の位置で数え直します。 |
| `startAt` | `number` | `1` | 数え直しの後の最初の行の番号です。 |
| `position` | `'outer' \| 'inner' \| 'left' \| 'right' \| 'start' \| 'end' \| 'side'` | `'outer'` | 番号を置く側です。`'outer'`は小口側で、奇数ページでは右、偶数ページでは左、右綴じの本では逆になります。`'inner'`はのど側です。`'left'`と`'right'`はどのページでも同じ側です。`'start'`と`'end'`は文書の方向に従い、右から左へ書く本では`'start'`が右になります。`'side'`は、`layout.sideColumnRole: 'floats'`の`'oneAndHalf'`レイアウトのサイド段に、本文側の辺にそろえて置きます（`gap`は使いません）。サイド段のないページでは`'outer'`になります。 |
| `multiColumn` | `'each' \| 'gutter' \| 'outer-edges'` | `'outer-edges'` | 本文の段が2つ以上並ぶページの場合です。`'outer-edges'`は最初の段の番号をその左に、最後の段の番号をその右に置き、間の段は`'each'`に従います。`'gutter'`は段間に置きます。最初の段の番号はその右、ほかの段の番号はその左です。`'each'`は各段の番号を`position`の側に置きます。 |
| `gap` | `Dimension` | `1em` | 段の端から番号までの距離です。`em`は番号自身のサイズです。 |
| `align` | `'auto' \| 'left' \| 'right'` | `'auto'` | `'auto'`は各番号を本文側にそろえます。左の余白では右そろえ、右の余白では左そろえです。`'left'`と`'right'`は、そのページでいちばん幅の広い番号の幅の中でそろえます。 |
| `fontFamily` | `string` | 本文のファミリー | 番号の書体です。ほかのファミリーと同じく読み込まれ、埋め込まれます。 |
| `fontSize` | `Dimension` | `0.8em` | 番号のサイズです。`em`は本文のサイズです。 |
| `fontWeight` | `number` | 本文のウェイト | 番号のウェイトです。 |
| `italic` | `boolean` | `false` | 番号をイタリックで組みます。 |
| `color` | `ColorValue` | 本文の色 | 番号の色です。パレットにリンクした色は、部やセクションのパレットに従います。 |
| `format` | `string` | 十進数 | 番号の書き方で、[番号書式の表記](https://postext.dev/ja/docs/configuration-page-layout.md#番号書式の表記)のどれでも使えます（`'lower-roman'`、`'arabic-indic'`、`'一'`…）。十進数の番号は文書の数字（`numerals`）で書かれます。不明な名前では十進数になり、`unknownNumberFormat`の警告が出ます。 |

```ts
lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // 本全体で1つの通し番号
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}
```

数える行と数えない行：

- **数えないもの**：見出し、キャプション、表と画像、別行立て数式、デザインのテキスト（扉、柱）、脚注と章末の注、目次、索引と参考文献の項目、白ページ。
- **囲みと散文。** 囲みの中のテキストは数えません。`count: 'verse'`では散文も数えません。ただし、そのテキストを組む段落スタイルが`lineNumbers: true`を指定していれば数えます。`lineNumbers: false`のスタイルは決して数えません（[段落スタイル](https://postext.dev/ja/docs/configuration-styles.md#段落スタイル)を参照）。
- **1つの詩。** 詩の開始行には`numbered=false`（その詩の行を数えない）、`lineStart=N`（最初の行をNとし、そこから数え直す）、`interval=N`を書けます。`:::numbering{lines=N}`は、どこにあっても、次に数える行をNにします。[文書の書式 › `:::verse`](https://postext.dev/ja/docs/document-format.md#verse)と[`:::numbering`](https://postext.dev/ja/docs/document-format.md#numbering)を参照してください。

章ごとにレイアウトする本では、`restart: 'document'`は`continuation.lineNumber`で章から次の章へ数を引き継ぎます。`continuationAfter`は詩の行をテキストから数えます。`count: 'all'`では数がレイアウトによって決まるので、ホストは前の章の文書の`lastLineNumber`を渡します。Sandboxはそうしています。

`position: 'side'`では、番号はサイドの囲み、キャプション、図とサイド段を共有します。そのどれかに重なる番号もそのまま描かれ、どちらも動きません。レイアウトは、番号を付けた行を指す内容の警告`lineNumberOverlap`を出します。

**出力。** Canvas、PDF、HTMLビューアー、固定レイアウトのEPUBが番号を描画します。タグ付きPDFでは番号はレイアウトのアーティファクトで、それぞれに空の`/ActualText`が付くので、コピーや抽出したテキストは番号を含まずに行から行へ続きます。HTML出力は番号を支援技術（`aria-hidden`）、選択、コピーするテキストから隠します。行を閲覧システムが組むリフロー型のEPUBでは、詩の行の番号だけが残ります。印刷版で番号の付く行の横、連の行頭側の余白に置く`pt-line-number`のspan（これも`aria-hidden`）です。VDTでは、番号は各ページのデザインスロット（`page.lineNumbers`。そのテキストブロックには`artifact`の印が付きます）と、マークのリスト（`page.lineNumberMarks`：`number`、`label`、`columnIndex`、`blockId`、`lineIndex`）です。文書は`lastLineNumber`を記録します。

**対応していないもの**：縦組みの行番号、行の番号を印字する相互参照、行番号に結び付けた注、表のセル、キャプション、コードリストの行の番号。

Sandboxでは、これらの設定はデザインパネルの**行番号**セクションです。解決関数と除去関数は、ほかのセクションと同じ形です。書体、ウェイト、色は本文から取ります。

```ts
import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';

resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // 未設定の書体、ウェイト、色は本文に従う
```

## 相互参照

`crossRefs`プロパティは、[相互参照](https://postext.dev/ja/docs/document-format.md#相互参照とアンカー)が番号やページの前後に印字する語と、スタイルを指定しない`:ref`に使うスタイルを設定します。各テンプレートには、番号が入る位置に`{n}`を書きます。これを含まないテンプレートでは、ノーブレークスペースの後に番号が入ります（`"§"`は「*§ 3.2*」と印字されます）。未設定のテンプレートは文書の言語に従い、英語では*chapter / section / p.*、スペイン語では*capítulo / sección / pág.*、中国語では`第{n}章` / `第{n}节` / `第{n}页`となります。フランス語、ドイツ語、イタリア語、ポルトガル語、カタルーニャ語、オランダ語も同様です。

```ts
interface CrossRefsConfig {
  chapter?: string;  // Words around a level-1 heading's number: "chapter {n}".
  section?: string;  // Around any other heading's number: "section {n}".
  page?: string;     // Around a page number: "p. {n}".
  defaultStyle?: 'default' | 'number' | 'title' | 'page'; // A :ref without style=.
}
```

| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `chapter` | `string` | 言語による | レベル1の見出しへの参照に使います（`"chapter {n}"`）。テンプレートがすでにその語を含む見出し番号（`Chapter {1}`、`第{1:一}章`）は、そのまま印字されます。 |
| `section` | `string` | 言語による | レベル2–6の見出しへの参照に使います（`"section {n}"`、`"§ {n}"`）。 |
| `page` | `string` | 言語による | ページ参照（`style=page`）に使います（`"p. {n}"`、`"page {n}"`）。 |
| `defaultStyle` | `'default' \| 'number' \| 'title' \| 'page'` | `'default'` | `style=`を指定しない、見出しまたはアンカーへの`:ref`が印字する内容です。`'default'`：番号付きの見出しはその語と番号、番号のない見出しはタイトル、アンカーはそのテキストを印字します。`style`を指定した参照はその指定を保ち、図と表への参照には影響しません。 |

参照には、すべての参照に共通する色、ウェイト、傾き（`bodyText.referenceColor`、`referenceBold`、`referenceItalic`）が使われます。

## 引用

`citations`プロパティでは、引用スタイルと、引用と参考文献の見た目を選びます。記法は[引用と参考文献](https://postext.dev/ja/docs/document-format.md#引用と参考文献)で説明しています。スタイルは`postext-citeproc`パッケージが適用します。

```ts
interface CitationsConfig {
  style?: string;          // 'apa', 'ieee', 'chicago-notes-bibliography'… or 'custom'
  customStyle?: string;    // a whole CSL style (.csl XML), used with style: 'custom'
  locale?: string;         // CSL locale; the document language when unset
  link?: boolean;          // citations link to their entries
  marker?: 'style' | 'brackets' | 'parentheses' | 'superscript' | 'corner';
  collapseRanges?: boolean;
  notes?: 'footnote' | 'warichu';
  numbering?: 'book' | 'chapter';
  bibliography?: {
    title?: string;        // unset: the document language's word; '' or ' ': none
    scope?: 'book' | 'chapter';
    auto?: boolean;
    fontSize?: Dimension;
    lineHeight?: Dimension;
    hangingIndent?: Dimension;
    entrySpacing?: Dimension;
    labelWidth?: Dimension;
    labelAlign?: 'left' | 'right';
    doi?: 'link' | 'text' | 'hide';
    includeUncited?: boolean;
    groupByLanguage?: boolean;
  };
}
```

| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `style` | `string` | `'apa'` | 同梱のスタイルのID（[スタイル](https://postext.dev/ja/docs/document-format.md#スタイル)を参照）または`'custom'`です。スタイルは、引用と文献項目の内容（名前、日付、順序、句読点、引用を注にするかどうか）を決めます。 |
| `customStyle` | `string` | — | `style`が`'custom'`のときに使う、CSLスタイル全体（`.csl`ファイルのXML）です。Sandboxではファイルから読み込みます。 |
| `locale` | `string` | 文書の言語 | スタイルが語句を書くときのCSLロケールです（`en-US`、`es-ES`、`zh-CN`、`zh-TW`、`ja-JP`…）。日本語の文書は`ja-JP`として扱われ、叙述的な引用では2人の著者を「と」でつなぎ、それより多い場合は「ほか」で省略します。 |
| `link` | `boolean` | `true` | 引用を参考文献の項目にリンクします（PDFのリンク、HTMLのアンカー、Sandboxでのクリック）。 |
| `marker` | `'style' \| 'brackets' \| 'parentheses' \| 'superscript' \| 'corner'` | `'style'` | 番号方式のスタイルで、引用をどう示すかです。スタイルの表記どおり、`[1]`、`(1)`、上付き、`〔1〕`（縦組みでは正立）から選びます。番号の後にロケーターが続きます。 |
| `collapseRanges` | `boolean` | `true` | 連続する番号を範囲にまとめます。独立した1つの合印の場合は`1–3`、IEEEの場合は`[2]–[4]`です。`false`では別々のままにします。 |
| `notes` | `'footnote' \| 'warichu'` | `'footnote'` | 注方式のスタイルで引用を組む場所です。脚注（`footnotes`の設定どおりに配置・番号付け）か、行の中に2行で組む割注（夹注）かを選びます。 |
| `numbering` | `'book' \| 'chapter'` | `'book'` | 引用を本全体で通して扱うか、章ごとに扱うか（各文書、および引用のあとの各レベル1見出し）。章ごとでは、番号方式のスタイルは各章を 1 から数え、二つの章で引用された文献はそれぞれの章の番号を取ります。注のスタイルは各章の最初の引用で文献を完全な形で書きます。`bibliography.scope: 'chapter'`と組み合わせて使い、章の一覧はその章の番号になります。 |
| `bibliography.title` | `string` | 言語による | 一覧の上に置くタイトルで、太字の段落になります。空白にするとタイトルは付きません。独自の見出しは`:::bibliography`の上に置きます。 |
| `bibliography.scope` | `'book' \| 'chapter'` | `'book'` | 本が引用するすべての文献を1つの一覧にするか、章ごとにその章が引用する文献の一覧を作るかです。複数の章からなる文書では、各H1が新しい章の一覧を始めます。`auto`では、`:::bibliography`を置かない章の末尾に一覧が入ります。 |
| `bibliography.auto` | `boolean` | `true` | `:::bibliography`で位置を指定しない場合、一覧を本文の後（本全体の一覧なら最終章の後）に組みます。 |
| `bibliography.fontSize` | `Dimension` | `0.9em` | 項目のサイズです。emは本文のサイズです。 |
| `bibliography.lineHeight` | `Dimension` | 本文の行送り | 項目の行送りです。 |
| `bibliography.hangingIndent` | `Dimension` | `2em` | 番号のない項目の2行目以降のインデントです。 |
| `bibliography.entrySpacing` | `Dimension` | `0.3em` | 2つの項目のあいだのアキです。 |
| `bibliography.labelWidth` | `Dimension` | もっとも長いラベル | 番号付きの一覧で番号を置く欄の幅です。どの項目の文字も、1行目も2行目以降も、この幅だけ内側から始まるため、`9.`と`10.`が同じ欄に収まります。ラベルは引き続き項目のテキストの一部です。 |
| `bibliography.labelAlign` | `'left' \| 'right'` | `'left'` | ラベルを欄のどこに置くかです。欄の左端に寄せるか、文字の側に寄せるか（`9.`と`10.`の末尾がそろいます）を選びます。 |
| `bibliography.doi` | `'link' \| 'text' \| 'hide'` | `'link'` | DOIとURLを、リンクにするか、プレーンテキストにするか、省略するかです。 |
| `bibliography.includeUncited` | `boolean` | `false` | 引用の有無にかかわらず、すべての文献を一覧にします（`nocite: "@*"`と同様）。 |
| `bibliography.groupByLanguage` | `boolean` | `false` | 中国語、日本語、韓国語の文献を先に、その他を後に並べます。著者・年方式と著者・ページ方式のスタイルのみが対象で、番号付きの一覧は番号の順序を保ちます。 |

## 目次

`toc`プロパティは、`:::toc`ディレクティブが印刷する内容を設定します（[文書形式](https://postext.dev/ja/docs/document-format.md#toc)を参照）。目次は文書の**アウトライン**、つまり番号とページラベルの付いたすべての見出しと、すべての`:::part`から組み立てられるため、章に追従します。章の名前を変える、別の部へ移す、著者を変えると、項目もそれに合わせて変わります。項目は、独立した欄に置く見出しの番号、タイトル、リーダー、右端のページラベル、そして任意のサブタイトル行からなります。部は`parts.design`でデザインする行になります。

```ts
const config: PostextConfig = {
  toc: {
    levels: [{ level: 1, fontWeight: 700, color: { hex: '#00507b', model: 'hex' }, numberWidth: { value: 7.4, unit: 'mm' } }],
    unnumbered: { color: { hex: '#000000', model: 'hex' } },
    pageNumber: { fontWeight: 400, width: { value: 8, unit: 'mm' } },
    leader: { char: '.', gap: { value: 1, unit: 'mm' } },
    subtitle: { enabled: true, attr: 'author', italic: true, fontSize: { value: 8.5, unit: 'pt' } },
    parts: {
      height: { value: 23, unit: 'pt' },
      marginTop: { value: 11.5, unit: 'pt' },
      design: { elements: [/* a band box, 'SECTION {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};
```

| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `levels` | `TocLevelConfig[]` | レベル1 | 目次に載せる見出しレベルと、レベルごとの項目の文字組みです。`fontFamily`、`fontSize`、`lineHeight`（既定値は本文の行送りで、目次がグリッドに乗ります）、`fontWeight`、`italic`、`color`、`indent`（項目全体のインデント）、`numberWidth` / `numberGap`（タイトルの前に置く番号欄。番号は欄の中で右そろえになり、`الفصل الحادي عشر`や`Chapter 12`のように`numberWidth`より幅の広い番号があると、そのレベルの欄は最も広い番号に合わせて広がります）、`numberFontFamily`、`numberFontSize`、`numberFontWeight`、`numberColor`、`marginTop`、`marginBottom`を指定できます。未設定のフィールドは本文の値を引き継ぎます。番号は書体やサイズにかかわらずタイトルの1行目のベースラインに乗り、canvas、HTML、PDFのいずれでも同じです（postext 1.4までは箇条書きの記号と同じくxハイトの中央にそろえていたため、ディスプレイ書体や大きなサイズの番号はタイトルより上に浮いていました）。独自のレンダラーは、このベースラインを項目ブロックの`bulletBaselineY`から得られます。`bulletY`は1.4と同じく番号のem枠の中点のままなので、この新しいフィールドより前に書かれたレンダラーは、これまでどおりの位置に番号を描きます。 |
| `unnumbered` | `TocEntryStyleConfig` | — | スタイルが`numbered: false`の見出し（序文など）に対する上書きです。番号を印刷せず、レベルの`indent`の位置から字下げなしで始まります。 |
| `pageNumber` | object | レベル1の書体、本文のウェイト | ページラベルの`fontFamily`、`fontSize`、`fontWeight`、`italic`、`color`と、`width`（既定値`2em`）です。後者は右端にページラベル用に確保する欄の幅で、ラベルはその中で右そろえになります。 |
| `leader` | object | `{ enabled: true, char: '.', gap: 0.5em }` | `char`をタイトルとページ番号のあいだに繰り返して並べます。続く項目の点が縦にそろうよう右そろえで並べます（`'. '`とすると点の間隔が空きます）。`gap`はタイトルとリーダーのあいだに最低限残す間隔です。リーダーの文字数は、その書体でひと続きの文字列として測り、入るだけの数になります。そのため、連続するピリオドをカーニングで離す書体では、点がページ番号まで届くことはなく、点の数が少なくなります（postext 1.4までは点1つの幅から数を求めていたため、そうした書体ではリーダーがタイトルから番号に食い込んでいました）。ラベルの入る余地がなくなるタイトルは、少し手前で折り返します。リーダーは3文字以上で組みます。1文字か2文字しか入らない行にはリーダーを入れません。ページ番号の前に点が1つだけあると、ピリオドに見えるからです。タグ付きPDFでは点はアーティファクトになり、抽出したテキストには含まれません。本文も[タブ位置](https://postext.dev/ja/docs/configuration-text.md#タブ位置)で同じリーダーを組みます。 |
| `subtitle` | object | `{ enabled: false, attr: 'author' }` | 見出しの属性（`attr`）から取る、項目の下の2行目です（章の著者など）。独自の`fontFamily`、`fontSize`、`fontWeight`、`italic`（既定値`true`）、`color`と、追加の`indent`を持ちます。この行は項目と同じ行送りで組まれ、タイトルから離れることはありません。 |
| `parts.enabled` | `boolean` | `true` | 部の区切りに行を設けるかどうかです。 |
| `parts.breakBefore` | `boolean` | `false` | 最初の部を除くすべての部の行の前で新しいページを始めます。各部の章がそれぞれ独立したページに並びます。 |
| `parts.design` | `DesignSlot` | 空 | 行のデザインです。コンテナーは行そのもの（段の幅 × `height`）です。プレースホルダーは`{number}`、`{numberDecimal}`、`{numberRoman}`…、`{titleText}`、`{pageNumber}`です（最後のものは部扉のページラベルです。部扉を作らない`parts.page: false`のときは、部の内容が始まるページ、つまり柱がその部に切り替わるページのラベルになります。章ごとにレイアウトする本では、章を閉じるフェンスは次の章の最初の内容ページを指します）。パレットに連動した色は部自身の`palette`を使うため、各部の行はその部の色で表示されます。空のときは、`{number} {titleText}`（あいだにH1の`numberSeparator`）とページ番号を、レベル1の項目の文字組みで組みます。 |
| `parts.height`, `marginTop`, `marginBottom` | `Dimension` | `2em`, `0`, `0` | 行の高さと、その上下のアキです。`em`は本文の文字サイズなので、既定の行の高さは本文2行分ではなく、本文サイズの2倍です。本文が9.5/13.5 ptなら19 ptになります。本文2行分の行にするには、高さを`pt`で指定します（この例では`27pt`）。 |

ページラベルは文書が印刷するものと同じです。`buildDocument()`は、`:::toc`を含む文書を前のパスのラベルで組み直し、ラベルが確定するまで繰り返します（追加のパスは最大3回）。本を章ごとにレイアウトするホストは、代わりに本全体のアウトラインを`PostextContent.outline`として渡します。このアウトラインは`contentOutline()`（テキストだけから得る見出しと部）と`outlineFromDoc()`（同じ項目に、あるレイアウトのページラベルを付けたもの）から組み立て、そのアウトラインの`outlineKey()`が変わるたびに目次の章を組み直します。各見出しの項目は目次が印刷する`number`を持ち、番号付きの見出しであれば`counter`も持ちます。これは、テンプレートが何を印刷するかにかかわらず、`startAt`を適用したあとのそのレベルの通し番号です。ホストが自分の一覧で章の横に表示するのに使えます。

## 索引

`index`プロパティは、`:::index`ディレクティブが印刷する内容を設定します（[文書形式](https://postext.dev/ja/docs/document-format.md#索引)を参照）。索引は、本文中で`:index[…]`と`:index{term="…"}`で印を付けた語を並べ替え、先頭の文字でグループにまとめ（中国語ではピンインの頭文字または画数、日本語では五十音の行。`groupBy`を参照）、それぞれに出現するページを添えたものです。項目は見出し語、区切り、ページ番号からなります。副項目はそのあとに続き、レベルごとに1段階ずつ字下げされます。折り返した行は`turnoverIndent`の分だけ下げるため、副項目と位置がそろうことはありません。

```ts
const config: PostextConfig = {
  headingStyles: [
    // The index in two columns, under its own heading.
    { id: 'index', numbered: false, layout: { layoutType: 'double', gutterWidth: { value: 6, unit: 'mm' } } },
  ],
  index: {
    fontSize: { value: 8.5, unit: 'pt' },
    lineHeight: { value: 11, unit: 'pt' },
    rangeFormat: 'chicago',
    groups: { fontFamily: 'Source Sans 3', fontWeight: 700, color: { hex: '#8a1c1c', model: 'hex' } },
  },
};
```

| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `color` | — | 本文 | 項目の文字組みです。グループ見出しを含め、索引のすべての行は`lineHeight`で組まれます。索引は独自のリズムを保ち、ベースライングリッドには吸着しません。 |
| `indent` | `Dimension` | `1em` | 副項目のレベルごとのインデントです。 |
| `turnoverIndent` | `Dimension` | `2em` | 項目の折り返し行に、そのレベルのインデントに加えて付ける追加のインデントです。 |
| `entrySpacing` | `Dimension` | `0` | 各主項目の上のアキです。 |
| `separator`, `locatorSeparator`, `rangeSeparator` | `string` | `', '`、`', '`、`'–'`。アラビア文字では最初の2つが`'، '` | 見出し語と最初のページのあいだ、2つのページのあいだ、範囲の両端のあいだに印刷する文字列です。 |
| `mergeRanges` | `boolean` | `true` | 同じ番号書式の連続するページを範囲にまとめます。`12, 13, 14`は`12–14`と印刷されます。主要ページはまとめません。 |
| `rangeFormat` | `'full' \| 'chicago'` | `'full'` | 範囲の2つ目の数の書き方です。省略せずに書く（`234–237`）か、*The Chicago Manual of Style*（9.64）の求めるとおり1つ目と共通する桁を省いて書きます（`71–72`、`100–104`、`101–8`、`321–28`、`1496–500`）。ローマ数字のラベルは常に省略せずに書きます。 |
| `main` | `{ bold?, italic? }` | 太字 | 主要ページ（印に`main`を付けたページ）の組み方です。 |
| `see` | `{ label?, alsoLabel?, italic? }` | 言語による。イタリック（アラビア文字では正体） | 相互参照の前に置く語です。未設定のときは文書の言語に従います。*See* / *See also*、*Véase* / *Véase también*、*Voir* / *Voir aussi*、见 / 另见（繁体字中国語では見 / 另見）…。中国語の索引では、参照を句点のあとに空白なしで置きます：`贾琏 12。见贾政`。 |
| `locale` | `string` | 文書の言語 | 項目の並べ替えに使うアルファベット順の言語です（BCP 47タグで、`Intl.Collator`が読み取ります）。スペイン語では*ñ*は*n*のあとに並び、独立したグループの見出しになります。アクセント記号で順序が変わることはありません。 |
| `groupBy` | `'auto' \| 'letter' \| 'pinyin' \| 'stroke' \| 'gojuon' \| 'kana' \| 'none'` | `'auto'` | グループ見出しの種類です。`'letter'`：並べ替えキーの最初の文字。`'pinyin'`：漢字で始まる項目はピンイン読みのラテン文字の頭文字の下に入り（贾宝玉は`J`の下）、ラテン文字の並べ替えキーはその文字の下で、その文字の中国語の項目のあとに入ります（照合器はラテン文字を漢字のあとに並べます）。`sort="jia mu"`は`J`の末尾に来ます。`'stroke'`：最初の文字の画数の下に入ります（`一畫`、`二畫`…。簡体字中国語では`一画`…）。`'gojuon'`：かなの項目は五十音の行（あ行、か行 … わ行）の下に入ります。`'kana'`では最初のかなの下に入ります（カタカナとひらがなは見出しを共有します）。並びは日本語の索引のJIS X 4061の順です。読み（印の`yomi`、なければルビのかな読み、なければ`sort`、なければテキスト）で並べ、カタカナはひらがなとして、小書きのかなは大きいかなとして、ーは直前の母音として扱い、清音、濁音、半濁音の順に並べます。全体は記号、値の順の数字、文字ごとのラテン文字の語、かなの順になります。漢字の見出しのままの項目は`indexReadingMissing`として報告され、かなのあとに見出しなしで置かれます。`'none'`：見出しを付けません。記号、数字、語は`groups.marginTop`のアキだけで区切ります。`'auto'`は、日本語の索引（`ja`、`ja-*`）を五十音の行で、簡体字中国語の索引（`zh`、`zh-Hans`、`zh-CN`）をピンインで、繁体字中国語の索引（`zh-Hant`、`zh-TW`、`zh-HK`）を画数で、それ以外の言語を文字でグループにまとめます。項目は見出しの元になる照合で並べます。ピンインでグループにまとめた`zh-Hant`の索引は、ピンインで並びます。読みと画数は照合器（CLDR）のものです。照合器が文字を誤って読む場合（重阳の重を*zhòng*、行业の行を*xíng*と読むなど）は、望む読みしか持たない文字で書いた`sort`キーを印に与えると、正しい位置に並びます。重阳には`sort="崇阳"`、行业には`sort="航业"`とします。中国語の照合データを持たないブラウザーでは、ピンインと画数の索引は見出しなしで印刷されます。 |
| `ignoreArticle` | `boolean` | アラビア語では`true` | アラビア語の項目を、先頭の冠詞`ال`（`ٱل`）がないものとして並べ替え、グループにまとめます。البصرةはبの下、بدرとبغدادのあいだに入り、表記は書かれたままです。`الله`は冠詞を保ち、独自の`sort`キーを持つ項目はそのキーのとおりに並びます。この設定にかかわらず、アラビア語の索引は母音記号とタトウィールを無視し、أ إ آ ٱをاの下に入れ、ؤをو、ئとىをي、ةをهとして並べます。 |
| `groups.enabled` | `boolean` | `true` | 各グループの上に見出しを印刷します（`A`、`B`…または画数。数字には`0–9`、それ以外には`Symbols`。中国語では`数字` / `數字`と`符号` / `符號`）。 |
| `groups.fontFamily`, `fontSize`, `fontWeight`, `italic`, `color` | — | 項目と同じ、ウェイト`700` | グループ見出しの書体です。項目と同じ行送りで組まれます。 |
| `groups.marginTop` | `Dimension` | 索引の1行分 | 各グループの上のアキです。見出しの有無にかかわらず適用します。最初のグループの上には付かず（見出しからの距離は見出し側のアキで決まります）、段の先頭にも付きません。 |
| `groups.symbolsLabel`, `numbersLabel` | `string` | 言語による。`'0–9'`、中国語では`'数字'` / `'數字'` | 記号で始まる項目と、数字で始まる項目の見出しです。 |

ページ番号は、目次と同じく本のアウトラインから得ます。`computeOutline()`と`contentOutline()`は、テキストの索引の印を種類`'indexMark'`の項目として一覧にし（`indexMark.path`、`sort`、`see`、`seeAlso`、`main`、`range`、`index`を持ちます）、`outlineFromDoc()`がそれぞれに配置されたページを与えます。このページは、ビルドが`doc.indexMarks`（印ごとに`{ sourceStart, pageIndex }`）に記録します。`buildDocument()`は、自身の索引を印刷する文書を、番号が確定するまで組み直します。本を章ごとにレイアウトするホストは、`:::index`を含む章に、本全体のアウトラインを`PostextContent.outline`として渡します。`tocOutline()`と`indexOutline()`はアウトラインを目次が読む部分と索引が読む部分に分けるため、ホストは各章を、その章が印刷する部分だけに結び付けられます。Sandboxは、索引の章を印が動いたときだけ、目次の章を見出しが動いたときだけ組み直します。`contentOutline()`は、テキストが索引を印刷するかどうか（`hasIndex`）も示します。