設定：スタイルと部

#段落スタイル

paragraphStylesプロパティは名前付きのスタイルを宣言し、文書は:::paragraphs{style="…"}コンテナーで一連の段落にそれを適用します。参考文献、用語集、注記など、独自の書体、ウェイト、傾き、サイズ、行送り、大文字、スモールキャピタル、ぶら下げインデントを必要とする項目のまとまりに使います。文字組みのフィールドはどれも省略でき、未設定のときは本文の値を継承するため、スタイルには通常の本文と異なる点だけを書けば済みます。

const config: PostextConfig = {
  paragraphStyles: [
    {
      id: 'bibliography',
      name: 'Bibliography',
      fontSize: { value: 7, unit: 'pt' },
      lineHeight: { value: 1.2, unit: 'em' },
      hangingIndent: { value: 2, unit: 'em' },
      spaceBetween: { value: 0.25, unit: 'em' },
      marginTop: { value: 1, unit: 'em' },
      marginBottom: { value: 1, unit: 'em' },
    },
  ],
};

## References
 
:::paragraphs{style="bibliography"}
Knuth, D. E. (1984). *The TeXbook*. Addison-Wesley.
 
Bringhurst, R. (2004). *The Elements of Typographic Style*. Hartley & Marks.
:::

戯曲では、ト書きをイタリックで、配役表をスモールキャピタルで組みます。

paragraphStyles: [
  { id: 'direction', italic: true, fontSize: { value: 9, unit: 'pt' } },
  { id: 'cast', smallCaps: true, textAlign: 'center', fontWeight: 600 },
],

:::paragraphs{style="direction"}
Elsinore. A platform before the castle. *Francisco* at his post.
:::

ト書きはイタリックで、その中の名前は正体で印字されます。スタイルのウェイト、italic、smallCapsは囲みの中でも適用されます。

詩集では、一部の行を字下げし、行長に収まらない長い行の折り返しを、行そのものより深くぶら下げます。indentは段落のすべての行を内側に寄せ、ぶら下げインデントはそこから数えます。

paragraphStyles: [
  { id: 'verse', textAlign: 'left', firstLineIndent: { value: 0, unit: 'em' }, hangingIndent: { value: 4, unit: 'em' } },
  { id: 'verse-indented', textAlign: 'left', indent: { value: 1.5, unit: 'em' }, hangingIndent: { value: 2.5, unit: 'em' } },
],

verse-indentedの行は1.5 emから始まり、折り返しは4 emから始まるため、verseの行の折り返しとそろいます。indentがなければ、スタイルは1行目を字下げするか、ほかの行をぶら下げるかのどちらかしかできません。hangingIndentを設定するとfirstLineIndentは無視されます。

メニューでは、各料理の値段を点のリーダーの後に置き、行長の終わりにそろえます。

paragraphStyles: [
  {
    id: 'menu',
    textAlign: 'left',
    firstLineIndent: { value: 0, unit: 'em' },
    tabStops: [{ position: 'end', align: 'end', leader: '. ' }],
  },
],

:::paragraphs{style="menu"}
オニオンスープ :tab 850
 
真鯛のグリル、フェンネルとレモン添え :tab 2,100
:::

どの行の点も、値段の二分手前で終わります（leaderGap）。行に収まらない長い料理名は折り返し、その最終行がリーダーと値段を保ちます。値段が最後の語の隣に収まらないときは、その語も一緒に次の行へ送られます。

#:::paragraphsコンテナー

:::paragraphs{style="<id>"}の行でコンテナーを開き、:::だけの行で閉じます。間にあるすべての段落は名前付きのスタイルを取り、中にある見出し、リスト、その他のブロックは通常のスタイルを保ちます。コンテナーはほかのフェンス付きコンテナーの中に入れ子にできます。不明なstyleのidはエラーにならず、段落は通常の本文として描画されます。

フェンスは、スタイルの有無にかかわらずalign（start、end、left、right、center、justify）、indent、endIndent（単位のない数値はem）も取ります。スタイルがあればそれを上書きし、なければ外側のコンテナーのスタイル、またはフェンスのある場所のテキストのスタイル（本文、部、スタイル付きの節、ボックス）の上に適用されます。:::paragraphs{align=end}はブロックを行末にそろえて組み（地付き）、:::paragraphs{align=end endIndent=1}はそこから1字上げて組みます。postext 1.16から使えます。

コンテナーの中では流れがベースライングリッドから外れます（7ptで行送り1.2emの項目は、8pt/1.5emのグリッドには乗りません）。最後の段落で流れはグリッドに戻ります（グリッドが優先され、下のアキは最小値になります。見出しと同じ規則です）。項目は本文の段落と同じく段やページをまたいで分割され、オーファンとウィドウの保護も同じです。コンテナーの直前の見出しは、その最初の段落と離れないように保たれます。

コンテナーの下のアキは、スタイルのspaceBetweenとmarginBottom、そして周囲のテキストの段落間のアキ（bodyText.paragraphSpacingがオンなら1行）のうち最も大きいものになり、2つの本文の段落の間のアキと同じく、次のブロックが自身の上に取るアキと統合されます。参考文献の後の見出しは、最後の項目から自身のmarginTopだけ下に置かれ（スタイルのアキのほうが大きければそちら）、詰めた項目のまとまりの後の段落は、テキストの段落間のアキを保ちます。流れはまずテキストの下でグリッドに戻り、グリッドに戻すことで埋まらなかった分はグリッドの行単位で持ち越されるため、コンテナーの後のテキストはグリッドに乗ります。postext 1.4までは、スタイルのアキはグリッドに戻る前に最後の行の下に置かれ、その下に次のブロックの上のアキが加えられ、段落間のアキは含まれませんでした。bodyText.paragraphContainerSpacing: 'add'はこの規則を保ち、この設定より前に保存された設定はこの規則で読み込まれます。snapToGrid: falseのスタイルはグリッドに戻りません。コンテナーの後のテキストはその正確なアキだけ下に置かれ、次にグリッドに合わせるブロックまでグリッドから外れます。リストで終わるコンテナーは、どちらの規則でも1.4と同じに組まれます。リストは自身の下のアキを保ち、marginBottomはそのアキの後に続いて、次のブロックのアキと統合されます。

:::calloutの中でも、コンテナーはスタイルのマージンを同じように取ります。marginTopとmarginBottomは前後のブロックのアキと相殺され（負の値は前後を近づけます）、ボックスの先頭にあるコンテナーは、段の頭と同じく上のマージンを取りません。ボックスには戻る先のベースライングリッドがないため、最後の段落の下のアキは、marginBottom、spaceBetween、ボックス自身の段落間のアキ（そのbody.paragraphSpacing、つまりボックスのテキスト1行分。paragraphContainerSpacing: 'add'では含まれません）のうち最も大きいもの、または次のブロック自身の上のマージンのほうがさらに大きければそれになります。負のmarginBottomは、代わりに次のブロックを引き上げます（postext 1.4までは、囲みの中のコンテナーはどちらのマージンも無視していました）。

const resolved = resolveParagraphStylesConfig(config.paragraphStyles, resolvedBodyText);
// => every unset field filled from the resolved body text
 
const minimal  = stripParagraphStylesDefaults(config.paragraphStyles);
// => undefined when the list is empty; zero margins and `name === id` dropped

#チップスタイル

chipStylesプロパティは、インラインの:chip[text]{style="…"}の名前付きスタイルを宣言します。単語リストや、キーボードのキー、タグに使う、角を丸めた色付きのボックスです（構文と改行の規則は文書形式のリファレンスにあります）。既定ではchipというスタイルが1つ用意されています（淡い青の塗りに、メインカラーのヘアラインの枠、わずかな角丸、テキストは周囲の語と同じ）。そのため:chip[…]は設定なしで使えます。chipStylesを宣言すると、この既定のリストが置き換えられます。styleのないチップや、どのスタイルも宣言していないidを持つチップは、最初のスタイルになります。

const config: PostextConfig = {
  chipStyles: [
    { id: 'chip', name: 'Word bank' },
    {
      id: 'key',
      name: 'Keyboard key',
      background: { hex: '#fff4d6', model: 'hex' },
      borderColor: { hex: '#8a6d1f', model: 'hex' },
      borderRadius: { value: 2, unit: 'pt' },
      bold: true,
    },
  ],
};

Classify: :chip[battery] :chip[cable] :chip[switch]
 
Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"}.

ボックスのemの長さ（paddingX、paddingY、borderRadius、borderWidth、gap）は、チップ自身のフォントサイズに対する値です。ボックスはベースラインの0.8 em上から0.25 em下までの帯で、paddingYと枠線の分だけ大きくなります。行のボックスの外側に描かれ、行送りを変えることはないため、ベースライングリッドは保たれます。ボックスが行送りより高くなると、チップが上下の行のチップに重なることがあります。異なる行の2つのチップが重なると、Sandboxは重なりをポイントで示したチップが隣の行に接触の警告を表示するため、paddingY、枠線、fontSizeを小さくして対処できます。上下にチップのない背の高いチップは報告されません。

VDTでは、チップはkind: 'chip'の行のセグメントで、そのchipフィールドがテキストのラン（それぞれフォント文字列と幅を持つ）、ボックスのジオメトリー（boxWidth、ascent、descent、paddingX、borderWidth、borderRadius、間隔のマージン）、色を持ちます。セグメントのtextは1文字のプレースホルダーなので、プレーンテキストのオフセットとソースマップではチップは1文字として数えられます。

const resolved = resolveChipStylesConfig(config.chipStyles);
// => the built-in `chip` style when unset; every field filled
 
const minimal  = stripChipStylesDefaults(config.chipStyles);
// => undefined for the built-in default; static defaults dropped
 
const style = pickChipStyle(resolved, 'key');
// => the `key` style, else the first one

#コードリスト

codeStyleプロパティは、コードリストの見た目を設定します。対象はテキストの```と~~~のフェンス（文書形式 › コードブロックを参照）と、コードの書体を求めるときのインラインコードです。コードリストは等幅の書体で、書いたとおり1行ずつ枠の中に組まれます。どの行もハイフネーションや両端そろえをせず、スペースはどれも幅を保ち、タブは次のタブ位置まで進みます。枠は:::calloutと同じ仕組みで作られるので、コードリストは行と行の間で分かれて段やページをまたぎ、各部分がそれぞれの枠に入ります。囲みの中のフェンスは、その中に入れ子になった枠です。どのプロパティも省略できます。postext 1.23以降。

const config: PostextConfig = {
  codeStyle: {
    fontFamily: 'JetBrains Mono',
    fontSize: { value: 0.8, unit: 'em' },
    background: { hex: '#0e1116', model: 'hex' },
    color: { hex: '#d3d9df', model: 'hex' },
    padding: { top: { value: 4, unit: 'mm' }, right: { value: 5, unit: 'mm' }, bottom: { value: 4, unit: 'mm' }, left: { value: 5, unit: 'mm' } },
    borderRadius: { value: 2, unit: 'pt' },
    lineNumbers: true,
    tokens: {
      keyword: { color: { hex: '#f2b134', model: 'hex' }, bold: true },
      string: { color: { hex: '#3ddc84', model: 'hex' } },
      comment: { color: { hex: '#8a939d', model: 'hex' }, italic: true },
    },
    inline: { background: { hex: '#eef1f4', model: 'hex' } },
  },
};

#構文の色分け

エンジンに組み込まれた小さな字句解析器が、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）です。

ホストはregisterCodeHighlighterで独自のハイライタ（Shiki、Prism、highlight.js）を組み込めます。設定はシリアライズできるデータなので、関数はcodeStyleに書かず、エンジンに登録します。

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つのまとまりとして組み、行がその途中で分かれることはありません。未設定なら、インラインコードは本文の書体のままです。

#コードリストの組み方

• 元の1行を1行に：行は段落の改行処理ではなく、コードの書体自身の送り幅から組み立てます。スペースは幅を保ち、連続したスペースもそのまま残り、行頭のスペースは字下げになります。右から左の本のコードリストは左から右に読み、左から右の引用と同じく行を枠の終端の側から組み、番号は行の左の余白に置きます。縦組みの本では、コードリストは縦の流れに従い（ラテン文字は縦組みのテキストと同じく横倒しになります）、行番号は付きません。
• 分割：残りの高さより長いコードリストは、行と行の間で分かれて段やページをまたぎ、各部分がそれぞれの枠に収まります。どちらの側にもsplitMinLines行未満を残すことはありません。折り返した行の続きは、ほかの切れ目が収まるなら元の行と離れません。
• 出力：キャンバス、HTMLビューアー、PDFは、組んだとおりに行と枠を描きます。HTMLビューアーはスペースを保つ（white-space: pre）ので、選択するとコードリストが字下げごと、元の各行の後に改行を入れてコピーされ、番号と折り返しの記号は含まれません。タグ付きPDFは各コードリストをCode要素を含む段落とし、本物のスペースのグリフを置き、番号と折り返しの記号はアーティファクトにします。リフロー型のEPUBは、字句の色を付けた<pre><code class="language-…">と、codeStyleから作ったスタイルシートを書き出します。固定レイアウトのEPUBは印刷版のとおりです。
• フォント：SandboxとconfigFontFamiliesは、テキストにフェンスがあるとき（または設定にcodeStyleの項目があるとき）、コードの書体をレギュラーとボールド、正体とイタリックで読み込みます。PDFは行が使う書体を埋め込みます。

#囲みスタイル

calloutStylesプロパティは、文書が:::callout{type="…"}コンテナーで適用する名前付きの囲みスタイルを宣言します。注記、ヒント、警告、学習目標など、色付きの背景や枠線で本文から切り離して組む内容に使います。既定では中立的なスタイルnoteが1つ用意されています（薄いグレーの背景、枠線・帯・アイコン・タイトルなし）。そのため:::calloutは何も設定しなくても使えます。calloutStylesを宣言すると、この既定のリストは置き換えられます。

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' } },
    },
  ],
};

:::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.
:::

#:::calloutコンテナー

:::callout{type="<id>"}の行で囲みを開き、:::だけの行で閉じます。フェンスは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つの側として足ります）を残し、次の段かページでアイコンのない囲みとして続きます。スタイルで繰り返さない限りタイトルはなく、残した部分の下にマーカーを付けることもできます（分割された囲みの目印を参照）。
• フロートは分割できない囲みに譲ります。図の参照の直後のブロックが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を参照）。フェンスの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プロバイダーです。

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を印字します。

証明は、番号のないラベルと終わりの記号を持つスタイルです。

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を参照）。
• 入れ子の囲みは自分のスタイルにすべて従います。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'でない限り右そろえです。マーカーは自分が締めくくる部分の中に場所を取り、切れ目はマーカーが収まるように選ばれます。

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::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の既定の設定では、奇数ページの部扉、白の偶数ページ、次の奇数ページに章、という古典的な構成になります。

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' } },
  },
};

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

#部扉デザインのプレースホルダー

デザインスロットは、見出しのプレースホルダーを部自身の値で解決します。{titleText}はフェンスのtitle、{number}は書いたとおりのnumberです。{numberDecimal}、{numberRoman}、{numberRomanLower}、{numberAlpha}、{numberAlphaLower}はそれを書式化し直します。番号は10進数、ローマ数字、漢数字として、それを囲む語の有無にかかわらず解析され（"IV"、"iv"、"4"、"４"、"四"、"卷四"、"第四卷"はどれも{numberDecimal}＝4になります）、それ以外は''になります。{partTitle}/{partNumber}、{chapterTitle}/{chapterNumber}（部の前の章）、{pageNumber}、{totalPages}、{bookTotalPages}、メタデータのプレースホルダーも使えます。{attr.<key>}は現在の章の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=#…"は部扉裏の色も変えます。

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>=<hex>[, <id>=<hex>…]"は、部に独自の色を与えます。部扉のページと、その後の次の部までのすべてのページで、これらのパレット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つが同じ基本値を持つ要素にリンクし、部がそれらを別の値にするとき、色は上書きを取ります（両方とも上書きされていれば、最後に書いたもの）。そうした要素には、それぞれ独自の基本値を与えてください。

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="<id>"}で見出しに適用する名前付きスタイルを宣言します。スタイルは2つのことをします。1つは、見出しのレベルの文字組み、デザイン、番号付けを上書きすることです。レベルの要素のlevel以外のすべてのフィールド（フォント、サイズ、色、breakBefore、span、advancedDesign、textTransform、hidden、numberingTemplate…）が対象です。もう1つは、見出しが開く節を制御することです。節のページ（同じかそれより上のレベルの次の見出しまで）は、スタイルの柱、ページのジオメトリー、本文の文字組み、パレットを取ります。こうして、2つ目の設定なしに、10進数で番号を振った2段組みのマニュアルの中に、本の前付け（ローマ数字のノンブルと青い帯を持つ、1段の広い段で組んだ序文）を収められます。

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' },
    },
  ],
};

# Preface {style="front-matter"}

節は、同じかそれより上のレベルの次の見出しで閉じます。スタイル付きの見出しの後にあるスタイルなしの#は、文書の柱とジオメトリーに戻ります。スタイル付きの見出しは独自の節を開きます。節が奇偶を合わせるために白のまま残したページは、章のタイトルと同じく、その節に属します。

改ページは見出し自身の改ページの代わりにはなりません。スタイルはレベルのbreakBeforeを継承し（レベル1の既定値は{ enabled: true, parity: 'always-odd' }）、見出しはどこにあってもそれを適用します。:::pagebreakの直後でも同じです。改ページで新しいページが開き、見出しはそれでもなお見開きの自分の側を求めます。parity: 'odd'では、偶数ページで終わる改ページの後に白ページが入り、見出しは次の奇数ページから始まります。'always-odd'では区切りの白ページも入り、改ページは何も変えません。見出しはいずれにしてもそのページを開いていたからです。タイトルページの後の目次のページのように、手動の改ページが開いたページから始めたいスタイルは、自分の改ページをオフにします。

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つの章が出会うページは後の章のタイトルを表示します。白ページは章のタイトルの規則に従います。奇偶を合わせる白ページ（blankForParity）はその後に開く節に属し、'always-odd'/'always-even'の改ページが加える区切り（blankForForce）はその前の節に属します。部扉は開いている節を閉じます。

# A {style="letter"}
 
Aardvark, abacus.
 
# B {style="letter"}
 
Babble, badger… (runs on to the next page)

どちらの文字もページ1から始まるので、ページ1はBの節の柱を取ります。スタイルのヘッダーに置いた爪見出しはそこで「B」になり、「A」の爪見出しを持つページはありません。どの節にも爪見出しが必要なら、各節に独立したページ（breakBefore）を与えてください。番号付きの章の後のアルファベット付きの付録と、目次とPDFのしおりには載るがページ上にはタイトルを出さない献辞のページの例です。

headingStyles: [
  { id: 'appendix', numberingTemplate: 'Appendix {1:A}' },
  { id: 'silent', hidden: true, numbered: false },
],

# 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も付けます）は、柱を割り込まれた章のまま保ちます。

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