>` | 落ち着いた配色 | 字句の種類ごとの見た目で、種類ごとに既定値に重ねます（後述）。パレットに結びつけた色は、`colorPalette`と部のパレットに従います。 |
| `inline` | `InlineCodeStyleConfig` | 未設定 | インラインコードをコードの書体で組みます（後述）。未設定なら、1.23より前と同じく、インラインコードは本文の書体で組みます。 |
### 構文の色分け
エンジンに組み込まれた小さな字句解析器が、`js`と`ts`（`javascript`、`jsx`、`typescript`、`tsx`）、`json`、`python`、`bash`（`sh`、`zsh`、`shell`）、`console`（シェルのセッション）、`css`、`html`と`xml`（`svg`）、`markdown`、`sql`の字句を見分けます。そのほかの言語のコードリストと、言語のないコードリストは`color`で組まれます。字句解析器はコードリスト全体を読むので、複数の行にわたるコメントや文字列も1つの字句のままです。`console`のコードリストでは、プロンプト（`$ `、`% `、`# `、`> `、`>>> `、`PS …> `）で始まる行はユーザーが入力したもの（`prompt`）で、それ以外の行はプログラムが出力したもの（`output`）です。
| 種類 | 既定値 | 対象 |
| --- | --- | --- |
| `keyword` | `#8b2c8f` | 予約語：`const`、`def`、`if`、`SELECT`、HTMLのタグ名、CSSのアットルール。 |
| `string` | `#3d7a2a` | 文字列、テンプレートリテラル、属性値。 |
| `number` | `#985f00` | 数値と定数（`true`、`None`、`null`）、色、文字参照。 |
| `comment` | `#7a7f87`、イタリック | コメント。 |
| `function` | `#2b5fb4` | 括弧が後に続く名前、シェルの組み込みコマンド。 |
| `type` | `#99540a` | 型と大文字で始まるクラス名、CSSのセレクター。 |
| `operator` | コードの色 | 演算子、シェルのパイプとリダイレクト。 |
| `punctuation` | コードの色 | 括弧、区切り記号。 |
| `variable` | `#b23b2e` | シェルの変数、JSONのキー、CSSのプロパティ、HTMLの属性、`self`。 |
| `meta` | `#985f00` | デコレーター、コマンドラインのオプション（`-l`、`--all`）、doctype。 |
| `prompt` | コードの色、太字 | シェルのセッションで入力した行。 |
| `output` | `#5c6168` | プログラムが出力したもの。 |
ホストは`registerCodeHighlighter`で独自のハイライタ（Shiki、Prism、highlight.js）を組み込めます。設定はシリアライズできるデータなので、関数は`codeStyle`に書かず、エンジンに登録します。
```ts
import { registerCodeHighlighter } from 'postext';
// fn(code, lang) returns the listing's lines, each as runs whose texts join into the line.
registerCodeHighlighter('rust', (code) => code.split('\n').map((line) => [
{ text: line, token: line.trimStart().startsWith('//') ? 'comment' : undefined },
]));
registerCodeHighlighter('*', null); // remove the one registered for every language
```
ある言語に登録したハイライタは`'*'`に登録したものより優先され、`'*'`に登録したものは組み込みの字句解析器より優先されます。ランは`token`の種類（`tokens`で色が付きます）か、独自の`color`（CSSの16進数）を指定します。`undefined`を返すハイライタ、例外を投げるハイライタ、つなげてもコードリスト自身の行にならない行を返すハイライタは使われません。レイアウトはコードリストを組むときに登録簿を読みます。ビルドの前に登録し、Web Workerの中で組むとき（Sandboxはそうしています）はWorkerの中で登録してください。
### インラインコード
`codeStyle.inline`は、バッククォートで囲んだテキストをコードの書体で組みます。チップと同じく1つのまとまりとして組み、行がその途中で分かれることはありません。未設定なら、インラインコードは本文の書体のままです。
| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `fontFamily` | `string` | `codeStyle.fontFamily` | 書体です。 |
| `fontSize` | `Dimension` | `0.9em` | `em`は周囲のテキストのサイズです。 |
| `color` | `ColorValue` | 周囲のテキストの色 | |
| `bold` / `italic` | `boolean` | `false` | テキスト自身の書式に重ねます（太字の中のコードは太字になります）。 |
| `background` | `ColorValue` | なし | 範囲の背後に敷く塗りです。 |
| `borderColor` / `borderWidth` | `ColorValue` / `Dimension` | なし / `0.5pt` | 枠線です。 |
| `borderRadius` | `Dimension` | `0.2em` | `em`は範囲のサイズです。 |
| `paddingX` / `paddingY` | `Dimension` | 塗りか枠線があれば`0.2em`、なければ`0` / `0.1em` | 塗りの内側のアキです。上下のアキは行のボックスの外側に描かれます。 |
### コードリストの組み方
- **元の1行を1行に**：行は段落の改行処理ではなく、コードの書体自身の送り幅から組み立てます。スペースは幅を保ち、連続したスペースもそのまま残り、行頭のスペースは字下げになります。右から左の本のコードリストは左から右に読み、左から右の引用と同じく行を枠の終端の側から組み、番号は行の左の余白に置きます。縦組みの本では、コードリストは縦の流れに従い（ラテン文字は縦組みのテキストと同じく横倒しになります）、行番号は付きません。
- **分割**：残りの高さより長いコードリストは、行と行の間で分かれて段やページをまたぎ、各部分がそれぞれの枠に収まります。どちらの側にも`splitMinLines`行未満を残すことはありません。折り返した行の続きは、ほかの切れ目が収まるなら元の行と離れません。
- **出力**：キャンバス、HTMLビューアー、PDFは、組んだとおりに行と枠を描きます。HTMLビューアーはスペースを保つ（`white-space: pre`）ので、選択するとコードリストが字下げごと、元の各行の後に改行を入れてコピーされ、番号と折り返しの記号は含まれません。タグ付きPDFは各コードリストを`Code`要素を含む段落とし、本物のスペースのグリフを置き、番号と折り返しの記号はアーティファクトにします。リフロー型のEPUBは、字句の色を付けた``と、`codeStyle`から作ったスタイルシートを書き出します。固定レイアウトのEPUBは印刷版のとおりです。
- **フォント**：Sandboxと`configFontFamilies`は、テキストにフェンスがあるとき（または設定に`codeStyle`の項目があるとき）、コードの書体をレギュラーとボールド、正体とイタリックで読み込みます。PDFは行が使う書体を埋め込みます。
## 囲みスタイル
`calloutStyles`プロパティは、文書が`:::callout{type="…"}`コンテナーで適用する名前付きの囲みスタイルを宣言します。注記、ヒント、警告、学習目標など、色付きの背景や枠線で本文から切り離して組む内容に使います。既定では中立的なスタイル`note`が1つ用意されています（薄いグレーの背景、枠線・帯・アイコン・タイトルなし）。そのため`:::callout`は何も設定しなくても使えます。`calloutStyles`を宣言すると、この既定のリストは置き換えられます。
```ts
const config: PostextConfig = {
calloutStyles: [
{ id: 'note', name: 'Note' },
{
id: 'objectives',
name: 'Learning objectives',
title: 'Objectives',
stripe: { enabled: true, side: 'left' },
icon: { kind: 'glyph', glyph: '✓' },
titleStyle: { textTransform: 'uppercase' },
lists: { bulletChar: '–' },
},
{
id: 'warning',
title: 'Warning',
backgroundEnabled: false,
border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
borderRadius: { value: 1, unit: 'mm' },
titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
},
],
};
```
```md
:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::
```
| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `id` | `string` | — | `:::callout{type="…"}`で選ぶ識別子です。`type`が未知または欠けているフェンスには、設定した最初のスタイルが適用されます（未知のtypeはSandboxが警告します）。 |
| `name` | `string` | `id` | 人が読むための名前です（エディターのUIでのみ使います）。 |
| `title` | `string` | `''` | 既定のタイトルの文字列です。空ならタイトルはありません。フェンスの`title`属性で個別に上書きできます。 |
| `span` | `'column' \| 'page' \| 'side'` | `'column'` | 横方向の広がりです。段、版面の全幅、または1段半レイアウトのフロート専用のサイド段（`layout.sideColumnRole: 'floats'`）のいずれかです。サイド段のとき、囲みは流れから外れ、割り込んだ位置のテキストの横にあるその段に積まれます。`span`属性で個別に上書きできます。段組みのレイアウトでは`'page'`の囲みは*ページ幅のブロック*（span block）になります。ページを段の帯に分け、全幅の独自の段に収まります（後述のコンテナーの節を参照）。そのページのサイド段に収まらないサイド段の囲みは、次のページのサイド段に置かれます。その前に章（または文書）が終わると、待っている囲みはそれぞれ、フェンスの順に本文の後のページのサイド段に置かれ、ビルドがそれを知らせます（`afterText`。postext 1.24までは、そうした最初のページより後の囲みは失われていました）。 |
| `columns` | `number` | `1` | フロートする囲み（`placement`が`'auto'`、`'top'`、`'bottom'`のいずれかで、`span: 'column'`）がまたがる隣り合う段の数です。図の`placement.columns`と同じ働きで、新聞の5段のうち3段にまたがる記事の囲みなどに使います。ページの段数以上を指定すると、ページ幅の囲みになります。流れの中に組む囲み（`'here'`）は自分の段に収まります。インスタンスごとに`columns`属性で上書きできます。postext 1.18以降。 |
| `placement` | `'here' \| 'auto' \| 'top' \| 'bottom' \| 'fixed'` | `'here'` | 囲みを置く場所です。`'here'`は流れの中にそのまま組みます。`'top'`/`'bottom'`はリソースと同じように**フロート**として配置します（`'auto'`はページの上と下のうち先に空いた帯を使います）。囲みは現れた位置で流れから外れ、その位置以降で最初に空いている帯（現在のページの下、または流れが次に開くページの上か下）に入り、後に続くテキストがその周りのページを埋めます。`'fixed'`は後述の`fixed`でページ座標に固定し、段の流れから外します。詳しくはコンテナーの節を参照してください。`placement`属性で個別に上書きできます。 |
| `sideAtColumnEnd` | `'before' \| 'after'` | `'before'` | フェンスの後のテキストが同じ段で続かないときに、サイドの囲み（`span: 'side'`）を置く位置です。続かないのは、段にそのテキストの入る余地がないときや、改段・改ページの規則がテキストを先へ送るとき（ウィドウとオーファンの規則で段落ごと送られる場合、見出しが本文と一緒に送られる場合）です。`'before'`は囲みをフェンスの位置、つまりそのページで前のテキストの横に置きます。フェンスの下に収まらないときは段の下端からせり上げます。説明する箇所の後に書いた注釈に向いています。`'after'`はフェンスの後のテキストの最初の行と高さをそろえ、そのテキストが続くページのサイド段に置きます。行の前に書いた行番号や欄外見出しに向いています。テキストが同じ段で続くときは、どちらもフェンスの位置に置きます。章の中で後に何も続かない囲みは、どちらの場合も前のテキストとともに残り、続けて書いたサイドの囲みは順序を保ちます。postext 1.4まではすべてのサイドの囲みが`'before'`として動作しており、これが既定のままです。注釈用のスタイルでは、囲みは説明する箇所のページにとどまります。 |
| `fixed` | `{ anchor?, offset? }` | `{ anchor: { to: 'container', edge: 'bottom-left' } }` | `'fixed'`の囲みの位置です。`ElementAnchor`（`to`：`'container'`＝版面、偶数ページでは左右反転、`'page'`＝仕上がり枠、`'bleed'`＝裁ち落とし枠。`edge`：コンテナーの9つの基準位置のいずれか）と、省略できる`offset`（`x`/`y`の寸法）で指定します。 |
| `floatBarrier` | `boolean` | `false` | 囲みをフロートの区切りにします。囲みより前で参照された図や表は、すべて囲みより前に配置されます（ページの空き位置、なければ囲みより先に開くページ）。こうして、章を締めくくる囲み（典型的には「要点」のまとめ）を越えてフロートが流れ出ることはありません。章扉、`:::part`、文書の末尾は常に区切りになります。 |
| 段組みのページにある`span: 'page'`の囲みは、直前のテキストの下で帯を切ります。囲みより前で参照された全幅の図は、先にその切れ目を使います。テキストの段の高さをそろえ、テキストが終わった位置に図を置き、囲みはその下に続きます（収まらなくなったときは次のページへ送ります）。高さをそろえたテキストの後に収まらないほど高い図は次のページの先頭に置き、囲みはその後に続きます。図が抜けた帯も高さをそろえて終わります。分割できる囲み（`keepTogether: false`）は、テキストと図の下で、入るだけの項目を収めて始まり、残りは次のページに続きます。 | | | |
| `width` | `'fill' \| 'auto'` | `'fill'` | `'fill'`は使える幅いっぱいに広がります。`'auto'`はタイトルに合わせて縮み（バッジ用）、子要素は無視します。 |
| `backgroundEnabled` / `background` | `boolean` / `ColorValue` | `true` / `#f4f4f4` | 囲みの塗りです。 |
| `border` | `{ enabled, color, width }` | `false`, `#cccccc`, `0.5pt` | 囲みの枠線です。ボックス要素の枠線と同じく、囲みの縁の内側に引きます（[ボックス要素](https://postext.dev/ja/docs/configuration-page-layout.md#ボックス要素)を参照）。 |
| `borderRadius` | `Dimension` | `0` | 背景と枠線の角の半径です（囲みの幅と高さの半分までに制限されます）。帯もこれに従います。角の丸い囲みでは、CSSが`border-left`を`border-radius`で切り抜くのと同じように、帯を丸い枠で切り抜きます。`label`のタブは角を四角いまま保ちます。 |
| `padding` | `{ top, right, bottom, left }` | 各`0.75em` | 囲みの縁と内容の間の内側余白です。`em`の値は囲みの本文のサイズが基準です。 |
| `stripe` | `{ enabled, side, width, color }` | `false`、`'left'`、`1.5em`、メインカラー | 1辺に沿った塗りの帯です。`'left'`/`'right'`の帯は内容の幅を狭め、`'top'`の帯は内容を下へ押し下げます。`'left'`と`'right'`は本文の流れから見た側です（右から左の本では`'left'`は紙面の右になります）。`'start'`と`'end'`は囲み自身の方向に従うので、アラビア語の本の中の`:::callout{dir=ltr}`では`'start'`の帯は左に付きます。`borderRadius`のある囲みでは、帯の外側の角は枠と同じく丸くなります（postext 1.4までは四角いままで、丸みからはみ出していました）。 |
| `icon` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, width, color, align, position, cornerSide }` | `'none'`、見出しのフォント、`400`、`1.5em`、メインカラー、`'top'`、`'inline'`、`'right'` | 内容の横に置く、文字のグリフ（`kind: 'glyph'`）またはビットマップやSVGのリソース（`kind: 'resource'`＋`resourceId`）です。側辺に帯があるときアイコンは帯の上の中央に置き、帯がなければ専用の列（`size`＋`titleStyle.gap`）を確保します。`align: 'center'`は内容に対して縦方向の中央に置きます。リソースの画像は縦横比を保って正方形の中に収めます。`width`を設定すると`width`×`size`の枠の中に収めます（横長のアイコンの列など）。内容より高いアイコンは、囲みをその高さまで広げます（`align: 'center'`のときは内容をアイコンの中央にそろえます）。`position: 'corner'`はアイコンをバッジとして上の角に掛け、半分を枠の外に出し、内容の場所は取りません。横長のアイコン（`width`）は描画される幅を基準に角の中央に置き、左の角ではタイトルをアイコンの内側の半分より先から始めます（postext 1.4までは高さを基準に置いていたため、横長の列が囲みからはみ出してタイトルに重なっていました）。`cornerSide`は角を選びます。`'right'`/`'left'`、または左右対称の余白のページの奇偶に従う`'outer'`/`'inner'`です（outerは奇数ページでは右、偶数ページでは左）。 |
| `marker` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, color, align, gap, rule }` | `'none'`、見出しのフォント、`400`、`1.5em`、メインカラー、`'center'`、`0.5em`、罫線なし（`0.5pt`、メインカラー、長さ`0`） | 囲みの*外*、左側の列に描く2つ目のアイコンです。囲みとの間に縦の`rule`を引くこともできます。自己評価のバッジの横に置く「ここをタップ」の手のマークなどに使います。全体の枠は`[marker][rule][gap][box]`となり、高さは3つのうち最も高いものに合わせます。`align`はそれらを互いの中央にそろえるか、上端にそろえます。`rule.length`は最小値で、罫線は常に少なくとも囲みの高さ分の長さになります。 |
| `titleStyle` | `{ fontFamily, fontSize, fontWeight, italic, color, textTransform, gap, letterSpacing, indent, lineHeight }` | 見出しのフォント、本文のサイズ、`700`、`false`、メインカラー、`'none'`、`0.5em`、`0`、`0`、`1.2em` | タイトルの文字組みです。`gap`はタイトルと最初の子要素の間のアキです（アイコンの列とのアキにもなります）。`lineHeight`はタイトルの行送りで、`em`はタイトル自身のサイズが基準です。本文と同じく、ベースラインは各行の上から行送りの0.8の位置に来ます。そのため本文の行送りに合わせたタイトル（12 ptのグリッドで`lineHeight: 12pt`）なら、囲みの高さは行の整数倍のままで、タイトルもグリッドに乗ります。既定の1.2 emでは、囲みごとに1行の端数が加わります。`textTransform: 'uppercase'`は文字数を変えません。`letterSpacing`はタイトルにトラッキングをかけます（canvasの`letterSpacing`、PDFの`Tc`）。`indent`はタイトルを囲みの内側の縁から右へ押し出します。タイトル側（左の角）に掛かる角のバッジは、先に自分の場所（バッジの内側の半分＋`gap`）を確保するので、どのページに来てもタイトルはバッジにかかりません。`indent`はそれに上乗せされるだけです。 |
| `body` | `{ fontFamily, fontSize, lineHeight, color, boldColor, italicColor, fontWeight, boldFontWeight, italic, smallCaps, textAlign, hyphenation, paragraphSpacing, firstLineIndent, tabStops, tabInterval }` | `bodyText`を継承。`italic`/`smallCaps`は`false` | 囲みの中の段落とリスト項目の文字組みです。未設定のフィールドはすべて本文テキストを継承します。`italicColor`はイタリックの部分の色を設定します（囲みの色でイタリックにした引用文など）。`fontWeight`/`boldFontWeight`は通常と太字の部分のウェイトを設定します。`italic`は囲み全体をイタリックにし、`*…*`の部分は立体に戻ります。`smallCaps`は囲み全体をスモールキャピタルにします。`tabStops`と`tabInterval`は囲みの中で本文のものを置き換えます（[タブ位置](https://postext.dev/ja/docs/configuration-text.md#タブ位置)を参照）。囲みのテキストがほかに何を引き継ぐかは[囲みの中の文字組み](https://postext.dev/ja/docs/configuration-styles.md#囲みの中の文字組み)を参照してください。 |
| `lists` | `{ bulletChar, color, indent, gap, itemSpacing, bulletFontSize, bulletFontWeight }` | `unorderedLists`を継承 | 囲みの中のリストの文字組みです（`color`、`indent`、`gap`、`itemSpacing`は番号付きリストにも適用されます）。`bulletFontSize`/`bulletFontWeight`は、行頭記号のグリフを囲みの本文の書体でそのサイズとウェイトにします（太い色付きの行頭記号など）。 |
| `label` | `{ fontFamily, fontSize, fontWeight, color, background, position, height, paddingX, offset, inset, icon, rule }` | 未設定（タブなし） | 囲みの上辺に付け、フェンスの`label`属性を印字するタブです。番号付きの囲みの番号（「BOX 1-1」）に使います。`position`の角（`'top-right'`/`'top-left'`）に寄せて`inset`だけ内側に置き、囲みの上端から`offset`だけ突き出します（この分はブロックの一部として`marginTop`に上乗せされるので、段の先頭でもタブの場所が確保されます）。高さは`height`で、テキストの左右に`paddingX`を取ります。横に`icon`リソース（`{ resourceId, width, gap }`、角と反対側）を付けることも、上辺に沿って反対側の角からタブまで`rule`（`{ enabled, color, width }`）を引くこともできます。既定値は見出しのフォント、本文のサイズ、`700`、メインカラーの地に白、高さ`1.4em`、内側余白`0.6em`です。タブは枠の上に立つ独立した形なので、囲みの`borderRadius`にかかわらず角は四角いままです。 |
| `columnGap` | `Dimension` | `1.5em` | 囲みの中の`:::columns`グループの段間です（後述のコンテナーの節を参照）。 |
| `marginTop` / `marginBottom` | `Dimension` | `0.75em` / `0.75em` | 囲みの上のアキ（前のブロックのマージンと相殺されます）と、下の最小のアキ（`snapToGrid: false`のときは正確なアキ）です。フロートとして配置した囲み（`placement: 'top'`、`'bottom'`、`'auto'`）は、帯とテキストの間にフロートのアキ（本文1行分）を保ちます。それより広い`marginBottom`は上の帯にある囲みの下のアキを、それより広い`marginTop`は下の帯にある囲みの上のアキを決め、帯とともにグリッドに切り上げられます。postext 1.4までは、フロートとして配置した囲みはマージンを無視していました。 |
| `snapToGrid` | `boolean` | `true` | `true`のとき、囲みの後の流れはベースライングリッドに戻るので、下のアキは`marginBottom`をグリッドの行単位に切り上げた値になります。`false`のとき、囲みは正確な`marginBottom`を保ち、それが次のブロックの上マージンと相殺されます。このスタイルの囲みが2つ続けば、間隔はちょうど`max(marginBottom, marginTop)`です。囲みの後のテキストは、次にグリッドに戻る位置（見出し、リストの終わり）までグリッドから外れることがあり、`headings.snapToGrid: false`の見出しの後と同じ動作になります。囲みを積み重ねて作る文書（ワークシート、書式）向けです。これが効くのは流れの中の囲みです。段組みのレイアウトのページ全幅の囲み、フロートとして配置した囲み、固定の囲み、サイドの囲みはグリッドを保ちます。段の帯とフロートの領域はグリッドに沿って組まれるためです。段末そろえの手段は変わりません。段を締めくくる囲みは、引き続き段の最後のグリッド位置まで押し下げられます。 |
| `keepTogether` | `boolean` | `true` | `true`のとき、囲みは分割しません。残りの場所に収まらない囲みは、まるごと次の段かページに送ります。分割せずに保てないのは、何も入っていない1段分（`span: 'page'`の囲みでは1ページ分）より高い囲みだけです。そうした囲みは、はみ出す代わりに後述の`false`の規則で分割し、現れた位置から始めます。1段に収まる続きは、そこからまるごと送ります。それほど高いフロートの囲み（`placement: 'top' \| 'bottom' \| 'auto'`）はフロートにならず、現れた位置で流れの中にとどまります。`false`のとき、どの囲みも子ブロックの間、または段落やリスト項目の行の間で分割できます。収まる最も深い切れ目で現在の段（`span: 'page'`の囲みではページ。段の下端にそろえます）を閉じ、残りは次の段の先頭で独立した囲みとして続きます。枠と帯は同じで、アイコンはなく、`repeatTitle`で繰り返さない限りタイトルもありません。それでも高すぎれば、さらに分割します。インラインのアイコンが先頭の部分で占める列は、どの断片でも空けたまま残すので、囲みはどのページでも同じ行長になります。リスト項目の中で切るときは、行頭記号を先頭の部分に残します。どの断片の枠もフェンスの`contentIndex`/`containerId`を共有し、`callout.part`/`callout.continued`を記録します。章を締めくくる長い「要点」の囲みには`headings.balancing.beforeSpan`と組み合わせて、また囲みが図をページから押し出してはならない注記のスタイルに使います。入れ子の囲み（別の囲みの中の`:::callout`）は親の子要素の1つとして扱います。切れ目はその前後に入り、入れ子の囲みの中で切るのは、そのスタイルが分割を許すとき（`keepTogether: false`、または1段より高いとき）だけで、そのスタイル自身の`splitMinLines`に従います。 |
| `splitMinLines` | `number` | `2` | 分割された囲み（`keepTogether: false`、または1段より高い分割しない囲み）の断片が、切れ目の前後それぞれに残すテキストの最小行数です。対象はテキストだけです。図、表、別行立ての数式、入れ子の囲みを1つ以上含む側は、行数にかかわらず認められるので、図版の囲みは1点だけをページに残すことがあります。段落やリスト項目の中で切るときも、前後それぞれのすべての行を数えます（そこにある図や数式は1行と数えます）。加えて、その段落や項目の行を前後それぞれに少なくとも`layout.boxChildSplitMinLines`行残します（既定は2行。この最小値のほうが小さければその値なので、1にすれば1行を許します）。既定値では、2行や3行の項目は分割されず、4行の項目は2行ずつにだけ分割されます。既定値では、段の下端や次の段の先頭にテキストが1行だけ残るような分割はしません。最小値を満たす切れ目がないときは、囲みをまるごと送ります。（postext 1.5より前は、段落の中で切るときに側全体の行数しか確かめなかったため、囲みのほかの行で最小値に達すれば、2行の項目が1行ずつに分割されることがありました。） |
| `repeatTitle` | `boolean` | `false` | 分割された囲みの続きの先頭ごとに、タイトルの後に`continuedSuffix`を付けて繰り返します（「Key points (cont.)」）。繰り返したタイトルにはタイトルのスタイルが適用されます。タイトルのない囲みは何も繰り返しません。[分割された囲みの目印](https://postext.dev/ja/docs/configuration-styles.md#分割された囲みの目印)を参照してください。 |
| `continuedSuffix` | `string` | `'(cont.)'` | 繰り返したタイトルの後に付ける文字列です。分割された表と同じく文書の言語（`locale`、なければハイフネーションのロケール）に従い、表と同じ方法でタイトルにつなげます。 |
| `continuesMarkerEnabled` | `boolean` | `false` | 分割された囲みのうち、続きのある各部分の最終行の下、囲みの中に`continuesMarker`を置きます。 |
| `continuesMarker` | `string` | `'Continued'` / `'Continúa'` | そのマーカーの文字列です（脚本の「(MORE)」など）。囲みの本文の書体とサイズで組み、文書の言語ごとに既定値があります。 |
| `continuesMarkerAlign` | `'left' \| 'center' \| 'right'` | `'right'` | 囲みの内側の幅の中でマーカーを置く位置です。 |
| `continuesMarkerItalic` | `boolean` | `true` | マーカーをイタリックで組みます。 |
| `numbering` | `{ label, counter, numberingTemplate, resetOn, counterFormat, placement, bold, italic, suffix }` | 未設定 | このスタイルの囲みを、定理、補題、定義のような番号付きの命題として数えます。[番号付きの定理と証明](https://postext.dev/ja/docs/configuration-styles.md#番号付きの定理と証明)を参照してください。 |
| `endMark` | `string` | `''` | 囲みの最終行の末尾に右端そろえで置く記号です。証明を`'∎'`や`'□'`で終えるときに使います。スペースを空けて収まれば最終行に、収まらなければ独立した行に置きます。番号のない別行立て数式で終わる囲みでは、その数式のタグとして置きます。数式が有効なときは、四角（∎ □ ■ ▪ ◻ ▫）をTeXのグリフで描くため、書体にその字形がなくても（Fontsourceのlatinファイルなど）印字されます。数式が無効なときは囲みの本文の書体で組まれます。 |
### `:::callout`コンテナー
`:::callout{type=""}`の行で囲みを開き、`:::`だけの行で閉じます。フェンスは5つの属性を受け付けます。`type`（スタイルのid）、`title`（スタイルのタイトルを上書き）、`span`、`placement`、`columns`（スタイルの値を上書き）です。間の内容は囲みの中に組まれます。省略できるタイトルの後に段落、リスト、引用、数式、リソースの埋め込みが続き、それぞれスタイルの`body`/`lists`の文字組みで組まれます（見出しは通常のスタイルのままです）。子要素の間のマージンは本文と同じく相殺されます。囲みの内部はベースライングリッドから外れ、囲みの後で流れはグリッドに戻り、下に少なくとも`marginBottom`のアキを取ります（グリッドが優先され、マージンは最小値です。リソースと同じ約束です）。`snapToGrid: false`のスタイルでは代わりに正確な`marginBottom`を保ち、囲みの後のテキストは次の見出しかリストの終わりまでグリッドから外れます。囲みの直前の見出しは囲みと一緒に送られます。
このバージョンでの制約は次のとおりです。
- 囲みは、スタイルで`keepTogether: false`を設定しない限り分割しません。段の残りの場所に収まらないときは、まるごと次の段かページに送ります。フロートの帯や帯の上限で短くなった空の段からも、1段分あれば収まる限り送ります。1段より高い囲みは、分割できる囲みと同じように分割します。どの切れ目でも分割できない囲み（段より高い図、表、`:::columns`グループを含むもの、またはどの切れ目でも`splitMinLines`を満たせないもの）だけは、そのまま配置してはみ出させます。このときレイアウトは`calloutOverflow`警告（`VDTDocument.warnings`）を記録し、Sandboxはそれを一覧に表示します。分割できる囲みは、収まる部分（子要素まるごと、または前後それぞれに`splitMinLines`行まで残した段落の行。図、表、別行立ての数式は1つで1つの側として足ります）を残し、次の段かページでアイコンのない囲みとして続きます。スタイルで繰り返さない限りタイトルはなく、残した部分の下にマーカーを付けることもできます（[分割された囲みの目印](https://postext.dev/ja/docs/configuration-styles.md#分割された囲みの目印)を参照）。
- フロートは分割できない囲みに譲ります。図の参照の直後のブロックが`keepTogether`の囲みのとき、その囲みが現在の帯の中で入る段（フロートの前に囲みを収めていた参照元の段、またはその後の空の段）をなくしてしまう位置は使いません。図は次の候補の位置（たいていは次のページ）に移り、囲みは流れの中にとどまります。囲みをページから押し出して段に図だけを残すのではなく、組版者が組むとおりに組みます。
- 段組みのレイアウトで`span: 'page'`を指定すると、囲みは**ページ幅のブロック**になります。版面の全幅で組まれ、ページを段の帯に分けます。囲みの上の段は切れ目の線で閉じ、囲みは全幅の独自の段に入り、その下で新しい段の帯が始まるので、流れはすべての段で囲みの下に続きます。段の高さが*そろっている*位置（ページの先頭、`span: 'page'`の章扉の見出しの直下、別のページ幅のブロックの直下、上のフロートの帯の直下）では、囲みはそこでそのまま切ります。段の高さがそろわないページの途中に来たときは、組版者が組むとおりに組みます。囲みの上のテキストをすべての段で同じ高さに切り（エンジンは帯の段を同じグリッド行数に縮めて配置をやり直すので、テキストは段から段へ自然にあふれ、オーファン、ウィドウ、次と分離しない規則もすべて適用されます）、囲みはページ全幅に広がり、その下で段が再開します。切るには配置を何回か余分にやり直します。切れ目の線で、囲みと、その下にウィドウの最小行数分の本文行を入れる余地がなくなるとき、または数回試しても収まる配置がないときは、囲みを次のページの先頭へ送ります。囲みの上のテキストは切れ目に従います。図の下で段が上に残す数行に入りきらない段落は次の段に送り（その図は段の中で単独になります）、それでもあるブロックが切れ目を越えるときは、そのブロックの終わる位置ではなく、切れ目を1行下げます。帯を開く分割された囲みもそこで切るので、残りが切れ目を越えることはありません。`headings.balancing.beforeSpan`（既定）のときは、囲みが抜けた帯は章の最後の帯と同じように後ろで高さをそろえて切ります。スタイルが分割を許す（`keepTogether: false`）ときは、高さをそろえた段の下に収まる囲みの部分がページを締めくくり、残りが次のページの先頭に来ます。`beforeSpan: false`のときは、抜けたページは通常どおり段末をそろえるだけで、改ページは強制しません。ページ幅のブロックの直前の見出しは、囲みと一緒には送られません。1段のレイアウトでは、`span: 'page'`はただのインラインです。
- `placement: 'fixed'`は囲みを流れから外します。囲みは組まれた後（`width: 'auto'`はタイトルに合わせて縮み、`'fill'`はアンカーの点の下にあるテキストの段の幅を取ります）、流れの中で現れたページの、`fixed.anchor`/`fixed.offset`が示す位置に固定されます。既定は版面の左下の角です。囲みが覆うテキストの段は、フロートの帯とまったく同じようにその領域を明け渡します（下から削り、段がまだ空なら上から削ります）。その領域にすでにテキスト、フロート、ページ幅のブロックがあるときは、囲みを次のページへ送ります。章を締めくくる固定の囲み（次のブロックが章扉、`:::part`、フロートの区切りの囲み、または文書の末尾のもの）は、まず上の段の高さをそろえる（`headings.balancing.trailing`）ので、短い最終ページは下のバッジとそろって終わります。枠と子要素は`page.floats`に入り、どのバックエンドでも段のクリップの外に描画されます。
- `placement: 'top' | 'bottom'`は囲みをリソースと同じように**フロート**として配置します。囲みは現れた位置で流れから外れ、その位置以降で最初に空いている帯（現在のページの下（`'bottom'`）、または流れが次に開くページの上か下）に、段の幅（`span: 'column'`）または版面の全幅（`span: 'page'`）で入ります。後に続くテキストが、囲みの抜けたページを埋めます。枠と子要素は、固定の囲みと同じく`page.floats`に入ります。新しいページの先頭に来るフロートの囲みは、そのページを待っている図より先に組まれます。前のページで引用され、その下に収まる図は、テキストが3行未満しか残らないときでも、そのページの残りを使います（図版のページ：囲みと図だけで、間にテキストはありません）。`span: 'side'`の囲みはフロートになりません。placementにかかわらず、テキストの横に積まれます。`columns`が1より大きいとき（スタイルでもフェンスの属性でも指定でき、postext 1.18以降）、`span: 'column'`の囲みはその数の隣り合う段を使います。上端のそろった空の段の並びの頭か、現在の段とその後の空の段の足です。例：`:::callout{placement="top" columns="2"}`。
- `width: 'auto'`はタイトルにだけ合わせて縮み、子要素は無視します。
- ほかの囲みの中に入れ子にした`:::callout`は、独立した囲みです。自分のスタイル（背景、枠線、角の半径、内側余白、帯、タイトル、アイコン、マーカー、ラベル、文字組み）で、親の内側の全幅に組まれ、親の子要素の1つとして積まれます。`marginTop`/`marginBottom`は隣の要素と相殺されます。`span`と`placement`（フェンスまたはスタイル）は無視され、入れ子の囲みは常に親の中を流れます。`floatBarrier`と`snapToGrid`も無視されます。囲みは何重にでも入れ子にでき、`:::columns`グループの中にも置けます（それぞれ1つの段にまるごと入ります）。親が分割されるとき、切れ目は入れ子の囲みの前後に入り、入れ子のスタイルが分割を許すときはその中にも入ります。どの断片も、切れ目が通る枠を描き直します。前の断片から続く入れ子の囲みは、トップレベルの続きと同じく、タイトルとアイコンを省きます。
- 子要素の中の`:::columns{count=N}`…`:::`グループは、囲みの中で、その子要素を等幅の`N`段に`columnGap`の間隔で組みます。段の高さが最もそろうブロックや行の境界で切り（途中で切れた段落やリスト項目は、次の段の先頭で行頭記号なしに続きます）、どの段もグループの上端から始まり、グループの高さは最も高い段に合わせます。グループの後の子要素は全幅に戻ります。分割される囲み（`keepTogether: false`、または段より高い囲み）は、グループの中でも段と段の間で切ります。snake のグループは段を順に埋めて次の断片に続き、parallel のグループ（`breaks`）は流れごとに続きます（postext 1.25から。[ドキュメント形式 › `:::columns`](https://postext.dev/ja/docs/document-format.md#columns)を参照）。フェンスの`gap`はそのグループについて`columnGap`の代わりになり、`rule`は各段間に罫線を引きます。要点を2段にまとめたり、幅の広い囲みで表を横に並べたりするのに使います。
- フェンスの6つ目の属性`label`は、スタイルのラベルタブに印字されます（前述の`label`を参照）。例：`:::callout{type="box" label="BOX 1-1" title="The octet rule"}`。`label`スタイルがなければこの属性は無視されます。
VDTでは、囲みは`type: 'callout'`の枠ブロックになり、その装飾（背景、帯、アイコン、タイトル）は`designOverlay`に入ります。その後に、同じ段の中で子ブロックが続きます。枠とすべての子要素はフェンスの`containerId`を持ちます。入れ子の囲みは、子要素の中の独立した`type: 'callout'`の枠で、その後に自分のブロックが続きます。それらはトップレベルのフェンスの`containerId`を保ち（配置と段末そろえからは1つの単位に見えます）、`calloutPath`を加えます。これは周りの入れ子のフェンスのコンテナーidを外側から順に並べたものです（入れ子の枠自身のidが最後の要素です）。タグ付きPDFは、入れ子の囲みごとに、親の囲みの中に`Div`を作ります。アイコンの画像はリソースの画像と同じ方法で解決されます。canvasの画像レジストリー、HTMLの`resourceImageUrl`オプション、PDFの`resourceBytes`プロバイダーです。
```ts
const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
// locale picks the language of the continuation strings
const minimal = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped
```
### 番号付きの定理と証明
`numbering`を持つスタイルは、LaTeXの`amsthm`が定理環境を数えるように、その囲みを数えます（postext 1.19以降）。各囲みはラベルと番号を印字し（最初の段落の先頭に「**定理2.**」）、フェンスの`title`は番号の後に括弧に入れて続きます。`:::callout{type="theorem" title="Bradley–Terry"}`は「**定理2**（Bradley–Terry）**.**」で始まります。識別子を付けて開いた囲み（`{#thm:main}`）は相互参照の対象になり、参照は「定理2」と印字し（`:ref{id="thm:main"}`）、`\ref{thm:main}`や`style=number`は2を印字します。
| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `label` | `string` | — | 番号の前に置く語です。`'定理'`、`'Lemma'`、`'Definición'`など。 |
| `counter` | `string \| false` | スタイルの`id` | 囲みが進めるカウンターです。同じカウンターを指定したスタイルは、`\newtheorem{lemma}[theorem]`と同じようにそれを共有します（定理1、補題2、定理3）。`'equation'`は、ラベルを付けた数式と一緒に数えます。`false`は番号なしでラベルを印字します（証明の「*証明.*」）。 |
| `numberingTemplate` / `resetOn` / `counterFormat` | `string` / `ResourceCounterReset` / `ResourceCounterFormat` | `'{n}'` / `'never'` / `'decimal'` | リソースの種類のものと同じです。`'{h1}.{n}'`と`resetOn: 'h1'`で章ごとに定理2.1、2.2…と、`'{h1}.{h2}.{n}'`と`'h2'`で節ごとに番号を付けます。複数のスタイルが共有するカウンターは、それぞれのテンプレートが何を印字するかにかかわらず数え続けます。 |
| `placement` | `'runIn' \| 'title'` | `'runIn'` | `'runIn'`は囲みの最初の段落をラベルで始めます（リスト、数式、別の囲みで始まる囲みには、そのための段落を加えます）。`'title'`はラベルを囲みのタイトルにして、その`titleStyle`で組みます。「定理2（Bradley–Terry）」のようになります。 |
| `bold` / `italic` | `boolean` | `true` / `false` | 段落頭のラベルとその後に付く文字の書体で、囲みの本文にかかわりません。本文がイタリック（`body.italic`）でも、立体のラベルは立体のままです。括弧内のタイトルは、通常のウェイトの立体で組みます。 |
| `suffix` | `string` | `'.'` | 段落頭のラベルとそのタイトルの後に置く文字です。 |
証明は、番号のないラベルと終わりの記号を持つスタイルです。
```ts
calloutStyles: [
{ id: 'theorem', numbering: { label: '定理' }, body: { italic: true } },
{ id: 'lemma', numbering: { label: '補題', counter: 'theorem' }, body: { italic: true } },
{ id: 'definition', numbering: { label: '定義' } },
{ id: 'proof', backgroundEnabled: false, endMark: '□',
numbering: { label: '証明', counter: false, bold: false, italic: true } },
]
```
章ごとに組む本では、カウンターは前の章から続きます（`LayoutContinuation.statementCounters`。`continuationAfter`が埋めます）。本のアウトラインは番号付きの囲みのアンカーごとにそのラベルを与える（`OutlineEntry.numberLabel`）ので、別の章からの参照もそれを印字します。
### 囲みの中の文字組み
囲みは内容を自分の`body`と`lists`の文字組みで組みます。それ以外はすべて文書のスタイルのままです。
- **段落**は囲みの`body`に従います。書体、サイズ、行送り、色、強調の色、ウェイト、`italic`、`smallCaps`、行そろえ、ハイフネーション、字下げ、段落間隔です。未設定のフィールドは`bodyText`を継承します。継承した強調の色はパレットとのリンクを保つので、囲みの中の太字、イタリック、`:ref`のラベルは、囲みの外と同じく`colorPalette`に合わせて変わります。（postext 1.4までは、囲みの中の太字はメインカラーにかかわらず`#295AA3`のままでした。）
- **箇条書きリスト**は`unorderedLists`より囲みの`lists`（行頭記号の文字、色、グリフのサイズとウェイト、字下げ、アキ、項目の間隔）を優先し、テキストは囲みの本文テキストになります。`lists.bulletChar`や`lists.color`が文書の値（`unorderedLists`）と異なるときは、すべてのレベルの行頭記号や色を置き換えます。同じ値を繰り返すとき、または未設定のときは、各レベルの値（`unorderedLists.levels`）をそのまま残すので、入れ子のダッシュも囲みの中で保たれます。
- **番号付きリスト**は`lists.indent`、`gap`、`itemSpacing`に従い、スタイルが`lists.color`を設定していれば、文書の行頭記号の色と同じ値でもそれに従います。設定していないスタイルでは、番号は`orderedLists.color`のままです。（postext 1.4までは、色が`unorderedLists.color`と異なるときにしか番号に反映されなかったため、まさにその色に設定しても何も変わりませんでした。）番号そのもの（書体、サイズ、区切り）は全体の`orderedLists`から取ります。`lists`には行頭記号のフィールドしかないので、囲みの番号はそちらで設定してください。
- **囲みの中の`:::paragraphs`コンテナー**は、入れ子の囲みの中でも、その段落スタイルに従います。スタイルが設定しないフィールドは、囲みの`body`ではなく文書の`bodyText`を継承します（囲みのイタリックやスモールキャピタルも継承しません）。
- **`:::columns`グループ**には独自のスタイルはありません。どの段も囲みの本文とリストの文字組みを共有し、`columnGap`が段間を決めます。
- **引用**は、囲みの本文の書体、サイズ、ウェイト（本文と同じくイタリックでグレー）と、スモールキャピタルに従います。**見出し**は見出しのスタイルのまま、**別行立ての数式**は数式の設定のままです。
- **図と表**は文書のキャプションと表のスタイルのまま、囲みの内側の幅で組まれます。通常と太字のウェイトは囲みの`body`のウェイトに従います。
- **チップ**はチップのスタイルのままです。`em`のサイズは囲みの本文のサイズを基準に読みます。
- **`:::space`の空き**は囲みの本文の行で測ります（どこで省かれるかは[`:::space`](https://postext.dev/ja/docs/document-format.md#space)を参照）。
- **入れ子の囲み**は自分のスタイルにすべて従います。`span`、`placement`、`floatBarrier`、`snapToGrid`は無視されます。
### 分割された囲みの目印
囲みが段やページをまたいで分割されるとき（`keepTogether: false`、または段より高い囲み）、最初の部分の後の各部分はタイトルとアイコンなしで始まり、既定では囲みが続いていることを読者に示すものは何もありません。2つのオプションで、本や脚本で使う目印を加えられます。
- **`repeatTitle: true`にすると**、続きの先頭ごとにタイトルを繰り返し、その後に`continuedSuffix`を付けます。既定は「Key points (cont.)」の形です。繰り返したタイトルにはタイトルのスタイルが適用されるので、`textTransform: 'uppercase'`と組み合わせれば脚本の「HAMLET (CONT'D)」になります。アイコンとラベルタブは最初の部分にだけ付きます。
- **`continuesMarkerEnabled: true`にすると**、続きのある各部分の最終行の下、囲みの中に`continuesMarker`（「Continued」、スペイン語の文書では「Continúa」）を、囲みの本文の書体とサイズで置きます。`continuesMarkerItalic`が`false`でない限りイタリックで、`continuesMarkerAlign`が`'left'`か`'center'`でない限り右そろえです。マーカーは自分が締めくくる部分の中に場所を取り、切れ目はマーカーが収まるように選ばれます。
```ts
calloutStyles: [{
id: 'speech',
keepTogether: false,
titleStyle: { textTransform: 'uppercase' },
repeatTitle: true,
continuedSuffix: "(CONT'D)",
continuesMarkerEnabled: true,
continuesMarker: '(MORE)',
continuesMarkerAlign: 'center',
continuesMarkerItalic: false,
}],
```
```md
:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::
```
ページを締めくくる部分は「(MORE)」で終わり、次のページは「HAMLET (CONT'D)」で始まります。どちらもページ割りのための補助的な表示です。アクセシブルなPDFではアーティファクトになり、HTMLでは支援技術から隠されるので、タイトルは1度だけ読み上げられます。VDTでは、`artifact: true`の付いた`designOverlay`のテキストブロックです。
## 部
`parts`プロパティは、文書が`:::part{number="…" title="…"}`コンテナーで開く部扉のページを設定します。章のまとまりを束ねる「Part I — Foundations」のページです。部は常に独立したページを占めます。コンテナーは設定した奇偶の新しいページへ改ページし、そのページを`parts.margins`で本文領域を決める1段のページに変え、部扉のデザインをページ全体に重ね、閉じるフェンスの後でもう一度改ページします。こうして次の章（自身の`breakBefore.parity`を持ちます）はきれいに始まります。H1の既定の設定では、奇数ページの部扉、白の偶数ページ、次の奇数ページに章、という古典的な構成になります。
```ts
const config: PostextConfig = {
parts: {
breakBefore: { parity: 'odd' },
breakAfter: { enabled: true, parity: 'any' },
margins: { top: { value: 9, unit: 'cm' }, left: { value: 3, unit: 'cm' }, right: { value: 3, unit: 'cm' } },
design: {
elements: [
{
kind: 'text', id: 'number', content: 'Part {numberRoman}',
fontSize: { value: 12, unit: 'pt' }, fontWeight: 600, align: 'left',
placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 3, unit: 'cm' }, y: { value: 5, unit: 'cm' } }, size: { width: 'auto', height: 'auto' } },
},
{
kind: 'text', id: 'title', content: '{titleText}',
fontSize: { value: 28, unit: 'pt' }, fontWeight: 700, align: 'left', overflow: 'wrap',
placement: { anchor: { to: '#number', edge: 'below' }, size: { width: { value: 15, unit: 'cm' }, height: 'auto' } },
},
],
},
bodyStyle: { fontSize: { value: 11, unit: 'pt' }, numberColor: { hex: '#AA0000', model: 'hex' } },
},
};
```
```md
:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
3. Reading the weather
:::
# The lantern and its parts
```
| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `page` | `boolean` | `true` | `:::part`が部扉のページを開くかどうかです。`false`ではページを開かず、フェンスの本体も組みません。部の番号、タイトル、パレットは、それ自体の改ページなしに、次の内容から効力を持ちます。典型的な使い方は`htmlViewer.overrides.parts.page: false`で、部扉のない画面用の版にします。 |
| `breakBefore.parity` | `HeadingBreakParity` | `'odd'` | 部が始まるページの奇偶です。値と白ページの帰属の規則は見出しの[breakBefore](https://postext.dev/ja/docs/configuration-text.md#前で改ページ)と同じです。奇偶を合わせるために挿入した白ページは部に属し（その`{partTitle}`はすでに新しい部を指します）、`'always-*'`の必須の区切りページは前の内容に属します。 |
| `breakAfter.enabled` | `boolean` | `true` | 閉じるフェンスの後の内容を新しいページに送ります。`false`のときは、部扉のページの1段の中で続きます。 |
| `breakAfter.parity` | `HeadingBreakParity` | `'any'` | その新しいページの奇偶です。`'any'`のままにして、白の偶数ページを入れるかどうかは次の章自身の`breakBefore.parity`に決めさせます。改ページは次のブロックを配置するときに適用されるので、文書の最後にある部の後に空のページは残りません。 |
| `margins` | `PageMargins` | ページの余白 | 部扉のページの本文領域で、フェンスの中のブロックが流れる1段です。各辺は、未設定ならページの余白を継承します。`mirror`は、ページの余白とまったく同じように偶数ページでのどと小口を入れ替えます。 |
| `design` | `DesignSlot` | 空 | 部扉のデザインです。コンテナーはページの**仕上がり枠**なので、コンテナーのアンカーと`'page'`のアンカーは一致し、トンボを表示しているときは`'bleed'`が裁ち落としまで届きます。装飾専用で、本文の場所を確保することはありません。本文と重ならないようにするには`margins.top`を大きくしてください。空のときは、本文領域の左上に既定の`{number} {titleText}`のテキストをH1の文字組みで生成し、番号とタイトルの間にH1の`numberSeparator`を入れます。 |
| `versoDesign` | `DesignSlot` | 空 | 部扉のページの後に続く白の偶数ページ（部扉の丁の裏）のデザインです。コンテナーとプレースホルダーは`design`と同じです。何もない裏ページにするには空のままにします。部扉の次のページが白のまま残るときにだけ描画され、それには奇偶を指定した改ページが必要です。後述の[部扉裏のデザイン](https://postext.dev/ja/docs/configuration-styles.md#部扉裏のデザイン)を参照してください。 |
| `bodyStyle.fontFamily`, `fontSize`, `lineHeight`, `color`, `textAlign` | `bodyText`と同じ | `bodyText`を継承 | フェンスの中の段落、引用、リスト項目の文字組みです。ウェイト、強調の色、ハイフネーションは本文テキストから取ります。 |
| `bodyStyle.bulletColor` | `ColorValue` | `unorderedLists.color` | 部の中の箇条書きリストの行頭記号の色です。 |
| `bodyStyle.numberColor` | `ColorValue` | `orderedLists.color` | 部の中の番号付きリストの番号の色です。番号は常に本文の太字のウェイトで組むので、章のリストは目次のように読めます。 |
| `bodyStyle.unorderedLists` | `UnorderedListsConfig` | — | 部の中で、`bulletColor`の後に文書の`unorderedLists`に重ねて適用する部分的な上書きです。リスト全体の値は、それを継承していたレベルに伝わります。`levels`の要素はそのレベルにだけ適用されます。 |
| `bodyStyle.orderedLists` | `OrderedListsConfig` | — | 部の中で、`numberColor`と太字のウェイトの後に文書の`orderedLists`に重ねて適用する部分的な上書きです。たとえば部扉の章のリストに、独自の`separatorFontFamily`と`separatorColor`を持つ`'•'`の`separator`を使えます。 |
### 部扉デザインのプレースホルダー
デザインスロットは、見出しのプレースホルダーを部自身の値で解決します。`{titleText}`はフェンスの`title`、`{number}`は書いたとおりの`number`です。`{numberDecimal}`、`{numberRoman}`、`{numberRomanLower}`、`{numberAlpha}`、`{numberAlphaLower}`はそれを書式化し直します。番号は10進数、ローマ数字、漢数字として、それを囲む語の有無にかかわらず解析され（`"IV"`、`"iv"`、`"4"`、`"４"`、`"四"`、`"卷四"`、`"第四卷"`はどれも`{numberDecimal}`＝`4`になります）、それ以外は`''`になります。`{partTitle}`/`{partNumber}`、`{chapterTitle}`/`{chapterNumber}`（部の前の章）、`{pageNumber}`、`{totalPages}`、`{bookTotalPages}`、メタデータのプレースホルダーも使えます。`{attr.}`は現在の章のH1の属性を読みます。
### 部扉裏のデザイン
`versoDesign`は、部扉の直後のページに内容がないとき、そのページ、つまり部扉の丁の裏を飾ります。部そのものがそのページを白のまま残すことはありません。`breakAfter.parity`の既定は`'any'`なので、何かが奇偶を求めない限り、フェンスの後の内容はすぐ次のページから始まります。
- **次の章の見出し**。H1の既定の`breakBefore`は`'always-odd'`で、奇数ページの部扉の後では`'odd'`も同じ結果になります。章は次の奇数ページに移り、偶数ページは白のまま残ります。部扉裏のデザインが描画されます。
- **`parts.breakAfter: { enabled: true, parity: 'odd' }`**。次の見出しの設定にかかわらず、部自身が次の奇数ページを求めます。章が左右どちらのページからでも始まるとき（`breakBefore.parity: 'any'`、または`breakBefore.enabled: false`）に使います。
どちらもなければ、章は偶数ページから始まり、部扉裏のデザインは描画されません。`breakAfter.enabled: false`のときは、内容は部扉のページそのものに続きます。部扉裏は部のパレットに従うので、フェンスの`palette="band=#…"`は部扉裏の色も変えます。
```ts
parts: {
breakBefore: { parity: 'odd' },
breakAfter: { enabled: true, parity: 'odd' }, // always a blank verso to paint
versoDesign: {
elements: [{
kind: 'box', id: 'field',
style: { backgroundColor: { hex: '#b07d2b', model: 'hex', paletteId: 'band' } },
placement: { anchor: { to: 'page', edge: 'top-left' }, size: { width: 'fill', height: 'fill' } },
}],
},
}
```
**章を締めくくる部**。章ごとにレイアウトする本（Sandbox、`buildBundle`）では、`:::part`のフェンスはそれだけで1つの章にも、章の終わりにもなります。このとき部扉のページは章の最後のページになり、部がまだ果たしていないことを次の章が引き継ぎます。最初のブロックの前に`breakAfter`を適用し、最初のページが白のまま残るときはそこに`versoDesign`を描画します。ページは、本全体を1つの文書で組んだときと同じになります。フェンスの後に置けるのは、何も配置しないディレクティブ（`:::numbering`、`:::space`）だけです。それ以外は章の内容となり、その場合は章自身が改ページします。部の直後の空の章は独立した1ページになり、そのページが部扉裏になります。章を自分でレイアウトするホストは、これを`continuationAfter()`から得られます。部で終わる章に対して`afterPartPage: true`を返すので、それを次の章の`continuation`に渡してください。
### `:::part`コンテナー
`:::part{number="…" title="…"}`の行で部を開き、`:::`だけの行で閉じます。どちらの属性も省略できます（既定は`''`）。間のブロック（典型的には章のリスト）は、部扉のページの1段の中を`bodyStyle`で、`margins.top`から流れます。ページに収まらない本体は通常のページに続きます。このページは`role: 'part'`に分類され（`VDTPage.partInfo`が番号とタイトルを持ちます）、ヘッダーとフッターの要素は`pages: 'part'`/`pages: 'body'`でこのページを対象にしたり除外したりできます。PDFバックエンドは、しおりの中で部をその章の上に加えます。本体が空のもの（`:::part{…}`の直後に`:::`）がよくある形で、これでもページは作られます。続けて書いた部が1ページを共有することはありません。部の中に入れ子にした`:::part`は外側の部にまとめられます。
3つ目の属性`palette="=[, =…]"`は、部に独自の色を与えます。部扉のページと、その後の次の部までのすべてのページで、これらのパレットidのいずれかにリンクしたデザインの色（ヘッダー、フッター、章扉の帯、部扉と部扉裏のデザイン）は、文書のパレットの値の代わりに部の値を取ります。こうして、本の各部が2つ目のデザインなしに、角のタブ、柱の点、章扉の帯の色を変えられます。例：`:::part{number="II" title="…" palette="band=#f6c297"}`。テキストの流れも従います。同じページで、上書きしたパレットの要素の基本値と等しい流れの色はすべて部の値を取ります。対象は、見出し、太字、イタリック、参照の色、行頭記号とリストの番号、キャプションのラベルとキャプションのバー、表のテキスト、罫線、塗り（ヘッダー、本体、縞模様の行、セル自身の塗り）、囲み（背景、枠線、帯、タイトル）、チップ（塗り、輪郭、テキスト）です。そのため`band`にリンクした`headings.levels[1].color`は、各部の見出しをその部の色で組みます。インラインのスウォッチは書かれた色のままです。組は、カンマ、セミコロン、スペースで区切り、`=`または`:`でidと色をつなぎます。`#`は省略できます。部はフェンスが閉じた後も効力を持ち続けます。`{partTitle}`、`{partNumber}`、パレットは流れに沿ってその後の章へ引き継がれ、さらに`continuationAfter()`が返す`continuation.part`を通じて、個別にレイアウトする章にも引き継がれます。そのため、ある部の2つ目の章も、1つ目の章とまったく同じように柱にその部を表示します。
2つのパレットの要素が同じ基本値を持っていても、部が一方だけを上書きしたり、異なる色を与えたりすれば、部の中では異なる値を取ることがあります。値だけでは流れの色がどの要素から来たのかわからないので、流れの各色は、それが由来しうる設定と照合され、それらの設定がリンクする値を取ります。次のものは区別されます。
- ブロックのテキストの色：テキストの色、太字・イタリック・参照の色、リストの記号（行頭記号または番号）、番号の後の区切り。`bodyText.color`を`ink`に、`bodyText.boldColor`を`accent`にリンクし、どちらも`#1a1a1a`のとき、`palette="accent=#b8413d"`の部は太字の部分の色を変え、テキストはそのままにします。代わりに`unorderedLists.color`を`accent`にリンクすると、行頭記号の色を変え、項目のテキストはそのままにします。
- 見出しの各レベルと、色を設定する各見出しスタイル
- 目次の行のテキスト、番号、ページ番号と副題
- 各囲みスタイルの塗り（背景、帯、ラベルタブ）、枠線、罫線（マーカーとラベル）、テキスト（タイトル、アイコン、マーカーのグリフ、ラベル）
- 各表スタイル、チップスタイル、キャプションスタイルのそれぞれの色。名前付きの表スタイルは`tableStyle`とは区別され、リソースの種類のキャプションスタイルは`captionStyle`とは区別されます。セル自身の塗りは、そのセル自身のリンクに従います。
1つのケースだけは、まだ値で決まります。異なる場所にある設定が、ブロックの同じ色を設定する場合です。たとえば`bodyText.color`、`bodyText.blockquote.color`、段落スタイルの`color`、囲みスタイルの`body.color`は、どれもブロックのテキストの色を設定します。そのうち2つが同じ基本値を持つ要素にリンクし、部がそれらを別の値にするとき、色は上書きを取ります（両方とも上書きされていれば、最後に書いたもの）。そうした要素には、それぞれ独自の基本値を与えてください。
```ts
const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => margins filled from the page, bodyStyle from the body / list configs
const minimal = stripPartsDefaults(config.parts);
// => undefined when only static defaults remain
```
## 見出しスタイル
`headingStyles`プロパティは、文書が`# Title {style=""}`で見出しに適用する名前付きスタイルを宣言します。スタイルは2つのことをします。1つは、見出しのレベルの文字組み、デザイン、番号付けを上書きすることです。レベルの要素の`level`以外のすべてのフィールド（フォント、サイズ、色、`breakBefore`、`span`、`advancedDesign`、`textTransform`、`hidden`、`numberingTemplate`…）が対象です。もう1つは、見出しが開く**節**を制御することです。節のページ（同じかそれより上のレベルの次の見出しまで）は、スタイルの柱、ページのジオメトリー、本文の文字組み、パレットを取ります。こうして、2つ目の設定なしに、10進数で番号を振った2段組みのマニュアルの中に、本の前付け（ローマ数字のノンブルと青い帯を持つ、1段の広い段で組んだ序文）を収められます。
```ts
const config: PostextConfig = {
headingStyles: [
{
id: 'front-matter',
numbered: false,
breakBefore: { enabled: true, parity: 'odd' },
span: 'page',
advancedDesign: { enabled: true, minHeight: { value: 52, unit: 'mm' }, slot: { elements: [/* bands, `{titleText}` */] } },
header: { elements: [/* folio | rule | `{title}. {subtitle}` */] },
margins: { left: { value: 50, unit: 'mm' }, right: { value: 17, unit: 'mm' } },
layout: { layoutType: 'single' },
bodyStyle: { fontSize: { value: 10.5, unit: 'pt' }, textAlign: 'justify' },
palette: { band: '#547396' },
},
],
};
```
```md
# Preface {style="front-matter"}
```
| プロパティ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `id` | `string` | — | 見出しの行の`{style="…"}`から参照する識別子です。未知のidの見出しはそのままです。 |
| `name` | `string` | `id` | 人が読むための名前です（エディターのUIでのみ使います）。 |
| `numbered` | `boolean` | `true` | 見出しを数えるかどうかです。数える見出しは、そのレベルのカウンター（`numberingTemplate`の番号、リソース番号の`{h1}`）、`{chapterNumber}`の元になる章の序数、目次に印字する番号を進めます。序文、執筆者一覧、索引には`false`を使います。その後の最初の番号付きの章は章1のままで、それらのページでは`{chapterNumber}`は空になります。 |
| `toc` | `boolean` | `true` | `:::toc`が見出しを載せるかどうかです。見出しは`{toc="false"}`/`{toc="true"}`で上書きできます。 |
| `runningChapter` | `boolean` | `true` | このスタイルのレベル1の見出しを、柱の章にするかどうかです。柱の章とは、そのページとそれ以降のページで`{chapterTitle}`、`{chapterNumber}`、`{attr.}`とそれらの`…AtTop`形が指す章です。章の中にH1として組んだ図版ページ、地図、表紙には`false`を使います。柱はその見出しを飛ばし（その見出し自身のページでも）、割り込まれた章を指し続けます。`h1`のガイドワード（guide word）も設定しません。`numbered`なら見出しはなお数えられ（自身のデザインは自身の`{chapterNumber}`を読みます）、`toc`なら`:::toc`になお載ります。さらに`toc: false`にするとPDFのしおりも作られないので、章扉の前のページに置いた章の図版ページは、しおりを章に任せます。ほかのレベルの見出しはこの設定を無視します。既定のままでは、図版ページの後のページは図版ページのタイトルを印字します。`numbered: false`の序文や序章は、なお独立した章なので既定のままにします。このオプションが変えるのは、プレースホルダーがどの章を指すかだけです。スタイルはすべての見出しスタイルと同じく独自の節を開くので、次のレベル1の見出しまで、ページは図版ページのスタイルの柱のスロット、余白、段組み、本文スタイル、パレット（スタイルが設定しないものは文書の値）を取ります。割り込まれた章が開いたスタイル付きの節の値ではありません。章ごとにレイアウトする本では、柱は章のファイルから次のファイルへ引き継がれないので、ファイルの先頭にある図版ページでは、そのファイルの最初の章見出しまで章のプレースホルダーは空になります。 |
| レベルのフィールド | `headings.levels[]`と同じ | そのレベルの値 | `fontFamily`、`fontSize`、`lineHeight`、`fontWeight`、`italic`、`color`、`marginTop`、`marginBottom`、`snapToGrid`、`breakBefore`、`span`、`advancedDesign`、`textTransform`、`letterSpacing`、`lineSpan`、`indent`、`firstLineIndent`、`jidori`、`dropCap`、`hidden`：設定したものはそれぞれ、このスタイルの見出しについて見出しのレベルの値を置き換えます（`dropCap: false`はレベルのドロップキャップを外します）。`breakBefore`はレベルの値にフィールドごとにマージされます。`parity`だけを設定したスタイルはレベルの`enabled`を保ち、`enabled: true`だけを設定したスタイルはレベルの奇偶を保ちます（postext 1.4までは、欠けたフィールドは改ページなしの既定値から取られていました）。 |
| `numberingTemplate` | `string` | そのレベルの値 | このスタイルの見出しを、レベルのテンプレートの代わりに番号付けするテンプレートです（トークンは[`levels[].numberingTemplate`](https://postext.dev/ja/docs/configuration-text.md#レベルごとの上書き)と同じです）。カウンターはレベルのものなので、5つの章の後で`'Appendix {1:A}'`を使う付録のスタイルは*Appendix F*と印字します。最初の付録で`{startAt=1}`を付けて数え直してください。`''`は番号を印字しませんが、見出しはなお数えられます。テンプレートのないレベル1の見出しで目次と`{chapterNumber}`が表示する章の序数も印字しません。番号は、流れの中、スタイルのデザインの`{number}`、目次、`{chapterNumber}`に表示されます。 |
| `header`, `footer` | `DesignSlot` | 文書の値 | 節のページの柱で、そこでは`header`/`footer`を置き換えます（要素の`parity`と`pages`のフィルターは引き続き適用されます）。空のスロットにすると柱をなくします。 |
| `margins` | `PageMargins` | ページの余白 | 節のページの本文領域です。各辺は、未設定ならページの余白を継承します（`mirror`も含みます）。効力を持つのは節が開くページなので、`breakBefore`と組み合わせて使います。 |
| `layout` | `LayoutConfig` | `layout` | 節のページの段組み（`layoutType`、`gutterWidth`…）です。2段組みの本で序文を1段の広い段で組む場合などに使います。その`columnRule`は節のページに描かれ、未設定のフィールドは文書の`layout.columnRule`の値を取るので、段組みだけを変える節は文書の罫線を保ちます（[段間罫](https://postext.dev/ja/docs/configuration-page-layout.md#段間罫)を参照）。 |
| `bodyStyle` | `PartsBodyStyleConfig` | `bodyText`を継承 | 節の中の段落、引用、リストの文字組みです。フィールドは[parts.bodyStyle](https://postext.dev/ja/docs/configuration-styles.md#部)と同じです。 |
| `palette` | `Record` | `{}` | 節のページのパレットの上書き（id → 16進数）で、現在の部の上書きに重ねて適用します。部の`palette`属性と同じしくみで、及ぶ範囲も同じです。それらのページに組まれるデザインスロット（柱、章扉の帯。上書きしたidにリンクしたすべての色）だけでなく、テキストの流れにも値で及びます。上書きした要素の基本値と等しい流れの色（見出し、太字、イタリック、参照の色、行頭記号とリストの番号、キャプションのラベルとキャプションのバー、表のテキスト、罫線、塗り、囲み（背景、枠線、帯、タイトル）、チップ（塗り、輪郭、テキスト））はすべて、部の下と同じように節の値を取ります。同じ基本値を持つ2つの要素についての規則も同じです（[`:::part`コンテナー](https://postext.dev/ja/docs/configuration-styles.md#partコンテナー)を参照）。インラインのスウォッチは書かれた色のままです。ページの地色も変わります。`page.backgroundColor`が上書きされた項目にリンクしている（またはリンクなしでその基本値を持つ）とき、節のページは節の値で塗られます。新聞の経済面がサーモンピンクの紙に刷られ、ほかの面は白のままになるのはこのためです。postext 1.18以降。 |
節は、同じかそれより上のレベルの次の見出しで閉じます。スタイル付きの見出しの後にあるスタイルなしの`#`は、文書の柱とジオメトリーに戻ります。スタイル付きの見出しは独自の節を開きます。節が奇偶を合わせるために白のまま残したページは、章のタイトルと同じく、その節に属します。
**改ページは見出し自身の改ページの代わりにはなりません**。スタイルはレベルの`breakBefore`を継承し（レベル1の既定値は`{ enabled: true, parity: 'always-odd' }`）、見出しはどこにあってもそれを適用します。`:::pagebreak`の直後でも同じです。改ページで新しいページが開き、見出しはそれでもなお見開きの自分の側を求めます。`parity: 'odd'`では、偶数ページで終わる改ページの後に白ページが入り、見出しは次の奇数ページから始まります。`'always-odd'`では区切りの白ページも入り、改ページは何も変えません。見出しはいずれにしてもそのページを開いていたからです。タイトルページの後の目次のページのように、手動の改ページが開いたページから始めたいスタイルは、自分の改ページをオフにします。
```ts
headingStyles: [
// Starts where the text puts it: on the page the `:::pagebreak` before it opened.
{ id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false } },
],
```
左右を選ばずに独立したページを保つには、代わりに`breakBefore: { parity: 'any' }`を設定し、`:::pagebreak`は省きます。
**ページがどの節に属するか**。柱とパレットは、見出しごとではなくページごとに選ばれます。ページは、そのページ上の最後の節の切り替わりの後に有効な節を取ります。同じページで1つの節が終わって別の節が始まるとき（たとえば辞書の短い2つの文字の項）、ページは2つ目の節の柱とパレットを持ちます。スタイル付きの節がページの途中でスタイルなしの見出しによって終わるときは、ページは文書の値に戻ります。`{chapterTitle}`も同じ規則に従い、2つの章が出会うページは後の章のタイトルを表示します。白ページは[章のタイトル](https://postext.dev/ja/docs/configuration-text.md#白ページの帰属)の規則に従います。奇偶を合わせる白ページ（`blankForParity`）はその後に開く節に属し、`'always-odd'`/`'always-even'`の改ページが加える区切り（`blankForForce`）はその前の節に属します。部扉は開いている節を閉じます。
```md
# A {style="letter"}
Aardvark, abacus.
# B {style="letter"}
Babble, badger… (runs on to the next page)
```
どちらの文字もページ1から始まるので、ページ1は`B`の節の柱を取ります。スタイルのヘッダーに置いた爪見出しはそこで「B」になり、「A」の爪見出しを持つページはありません。どの節にも爪見出しが必要なら、各節に独立したページ（`breakBefore`）を与えてください。番号付きの章の後のアルファベット付きの付録と、目次とPDFのしおりには載るがページ上にはタイトルを出さない献辞のページの例です。
```ts
headingStyles: [
{ id: 'appendix', numberingTemplate: 'Appendix {1:A}' },
{ id: 'silent', hidden: true, numbered: false },
],
```
```md
# Dedication {style="silent"}
For M., who read every draft.
# Method
…
# Survey instrument {style="appendix" startAt=1}
# Raw data {style="appendix"}
```
レベル1に`numberingTemplate: '{1}.'`を設定すると、章は*1.*、*2.*…、付録は*Appendix A*と*Appendix B*と印字されます。献辞は自分のページを開き（そのレベルの`breakBefore`）、段落だけを印字しますが、`:::toc`、`{chapterTitle}`の柱、PDFのしおりには*Dedication*として表示されます。目次から外すには、スタイルに`toc: false`を加えます。章の途中にH1として組んだ図版ページや地図は、献辞とは逆のことを求めます。`runningChapter: false`のスタイル（通常は`numbered: false`と`toc: false`も付けます）は、柱を割り込まれた章のまま保ちます。
```ts
const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => level overrides normalised, margins filled from the page, bodyStyle from the body
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => undefined when no style remains
```