文書形式：ディレクティブ

#ディレクティブ

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

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

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

#属性の値

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

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

# The Long Road {lead='A "road novel", they said' price="$18"}
 
:::callout{type="note" title='The "fast" path'}
…
:::

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

#コンテナー

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

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

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

本文の流れの中で認識するコンテナー名は5つです。それぞれが何を描くかは、設定のそれぞれの節で決めます。

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

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

フロートする囲み（placementがauto、top、bottom）はcolumnsも受け付けます。複数の段があるページでまたがる隣り合う段の数で、:::callout{placement="top" columns="2"}のように書きます（postext 1.18以降）。

ボックスも、続く本文を横に組めます。wrap（left、right、start、end）、width（段幅の割合、0 から 1。未設定ならlayout.wrap.defaultWidth）、wrapGap（6ptのような長さ）を、:::callout{wrap="right" width=0.4}のように指定します（回り込みを参照。postext 1.24以降）。

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

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

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

# The lantern and its parts

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

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

#:::columns

:::columns{count=2}…:::のグループは、フェンスの間のブロックを同じ幅のcount段（2〜6段）に組み、グループのあとのテキストはまた全幅に戻ります。:::calloutの中では、段は囲みの内側の幅を分け合い、間隔はスタイルのcolumnGapで、囲みの本文とリストの書体設定で組まれ、囲みは最も高い段に合わせて伸びます。本文中では（postext 1.25から）、段は本文の段を分け合い、間隔は本文1行分で、ブロックは本文自体の書体設定を保ちます。複数の段があるページでspan="page"を付けると、グループは全幅の囲みと同じくページを帯に分けます。上の段は高さをそろえて閉じ、グループは版面の幅いっぱいに（間隔は段間で）組まれ、本文はその下のすべての段で続きます。1段のページでは、span="page"を付けてもその段の中に組まれます。グループの中の見出しは、スタイル、番号、目次の項目を保ちます。グループの中で引用した脚注は本文の段の下端に置かれ、グループが参照する図は通常どおりフロートします。

丸ごと組まれるグループは、段の高さが最もそろう位置で切られます。切る位置はブロックの間か、段落やリスト項目の行の間で、後者の場合は残りが行頭記号なしで次の段の先頭に続きます。breaksで段の開始位置を固定した場合は、段落の途中では切りません。図の段の横にテキストの段を置く場合などです。

グループの前後のアキ。本文中では、グループのあとに本文の段落間のアキが入ります（bodyText.paragraphSpacingがオンなら1行、オフならなし）。囲みの中では、グループ自身のアキはありません。フェンスのmarginTopとmarginBottomでこれを指定できます：:::columns{count=3 span="page" marginBottom="0.75em"}。どちらも最小値で、隣のブロックが自分のために取るアキと相殺されます。囲みのマージンと同じ扱いです。本文中では、グループの下でテキストがベースライングリッドに戻るので、アキは行単位になります。段やページをまたいで分かれたグループでは、上のマージンは最初の部分に、下のマージンは最後の部分に付きます。emはグループが置かれたテキストの文字サイズです。長さとして読めない値や負の値は無視されます。

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

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

:::callout{type="verse"}
:::columns{count=2 breaks="4"}
The lamp is lit at dusk,
 
and trimmed before the dawn.
 
:::space
 
The keeper sleeps by day.
 
La lámpara se enciende al anochecer,
 
y se despabila antes del alba.
 
:::space
 
El farero duerme de día.
:::
:::

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

グループの分割

postext 1.25から、与えられた余地に収まらないグループは、段と段の間で切られ、次の段やページに続きます。余地とは、本文中では段の残り、囲みの中では分割される囲み（keepTogether: false、または段より高い囲み）の一部分です。囲みの中のグループは、続きが新しい囲みの断片に入ります。

• flow="snake"、breaksがないときの既定値：グループのブロックは、新聞記事の本文のように、ひと続きの流れとして進みます。続きのある部分は、切れ目の許すかぎり高さをそろえながら段を順に埋め、ブロックの間か、段落やリスト項目の行の間で切ります（切れ目の両側に、その段落や項目の行を少なくともlayout.boxChildSplitMinLines行、既定では2行残します）。最後の部分は、丸ごとのグループと同じく高さをそろえます。
• flow="parallel"、breaksがあるときの既定値：breaksが始めるそれぞれのまとまりが、自分の段を保つ1つの流れになります。各部分はどの流れも与えられた余地の下端まで埋め、それぞれの流れは次の部分の同じ段で続きます。そのため、横に並べた詩とその訳は、連ごとに高さがそろったままになります。breaksのない parallel のグループは、snake のグループとして続きます。

グループの中の入れ子の囲みは丸ごとのまま次の部分に移り、入れ子の囲みの中のグループは決して切りません。収まるグループは、これまでとまったく同じに組まれます。layout.flowColumns: falseにすると、postext 1.24の規則のままになります。囲みの外のフェンスは無視され、グループは決して切られません。1.25より前に保存され、:::columnsグループを含む本は、この設定で読み込まれます。Sandboxは、知らないflow（不明な段組の流し方）と、テキストの6 emより狭い段（段が狭すぎる）を知らせます。

## 短信
 
:::columns{count=3 span="page" rule}
**港。** 新しい桟橋は月曜日に開業します…
 
**市場。** 出店料は据え置きです…
 
**天気。** 夕方から西の方で雨になります…
:::

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

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

:::callout{type="card"}
The statement of the exercise.
 
:::callout{type="answer"}
A white answer box with its own border and padding.
:::
 
:::callout{type="answer"}
A second answer box.
:::
:::

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

#:::paper

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

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

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

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

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

#:::pagebreak

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

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

The old chapter ends here.
 
:::pagebreak{parity="odd"}
 
# A new chapter

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

:::pagebreak{center}
 
# 上　先生と私
 
:::pagebreak

奇偶の属性

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

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

白ページの帰属

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

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

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

文書冒頭の例外

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

#:::numbering

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

---
title: "A Book With Front Matter"
---
 
# Preface
 
…
 
:::pagebreak{parity="odd"}
:::numbering{format="decimal" startAt=1}
 
# Chapter 1

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

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

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

linesはページのカウンターではなく、行番号の数を振り直します。lineNumbers.restartの設定にかかわらず、次に数える行が指定した番号になります。0以上の整数でない値は無視されます。

## 第二幕
 
:::numbering{lines=1}

#:::space

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

The last paragraph of the scene.
 
:::space
 
A new scene begins one line lower.
 
:::space{lines=2}
 
Two lines lower still.

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

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

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

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

#:::verse

詩です。:::verseは2つの組み方のどちらかで組みます。多くの詩が印刷されるとおりの行ごとの組み方と、カスィーダ（qaṣīda）の古典アラビア語の配置（各ベイトを2つの半句に分けて横に並べる）です。行に半句の区切り（||、または前後に空白のある\\）がある詩はアラビア語の配置で、それ以外は行ごとに組みます。開始行にlayout=linesまたはlayout=baytと書けば、どちらかを指定できます。

行ごと

詩は印刷されるとおりに書きます。Markdownの1行が詩の1行、連と連のあいだは空行、行頭の空白で字下げします。

:::verse{keepStanzas=3}
古池や
  蛙飛び込む
    水の音
 
柿食へば
  鐘が鳴るなり
    法隆寺
:::

• 詩の行。 空でない各行が詩の1行で、それぞれ単独でインラインのMarkdownとして読みます。強調、スモールキャピタル、注、参照が使えます。続く空行はまとめて1回の連の区切りです。
• 字下げ。 行頭の空白1つの幅はindentStepで、既定は0.5 emなので、空白2つで1字下がります。タブは空白4つ、全角スペース（U+3000）は2つと数えます。
• 折り返し。 行長よりわずかに長い詩の行は、まず語間の空白を自然な幅のbodyText.minWordSpacingまで詰めて（両端揃えの文の詰めの限度）一行に収めます。開始行にtighten=falseを書くかbodyText.verse.tighten: falseとすると、詰めずに折り返します。詰めても収まらない行は語間の空白で折り返します（日本語の行は日本語の行分割の規則で字間で折り返します）。turnover=hang（既定）では残りを次の行にぶら下げ、その行自身の頭からhangだけ下げます。hangは詩の段落スタイルのhangingIndent、なければ2 em（bodyText.verse.hang）です。turnover=rightでは、残りを開き角括弧（turnoverMark、既定は[）の後ろに置いて行末側に寄せます。英語とスペイン語の詩集の組み方です。段落スタイル自身がhyphenation: trueを決めていない限り、詩はハイフンで分割しません。詩の行とその折り返しは、段や頁の区切りで離れることはありません。
• 連。 連と連のあきは詩の行送り1行分です。stanzaSpace=0.5で半行、長さ（stanzaSpace=6pt）で正確な量になります。ベースライングリッド上では整数行になります。段と頁はまず連のあいだで区切り、連の中ではウィドウ・オーファンの規則で区切ります。そのときはその連の行数を数えます。keepStanzas=NはN行以下の連を分けずに保ちます。俳句ならkeepStanzas=3、短歌ならkeepStanzas=5です。
• 配置。 横組みでは、詩はいちばん長い行を基準に行長の中央に置かれ、各行は詩の行頭にそろいます（align=center、散文の中に詩を引くときの通常の組み方）。align=startは行長の行頭にそろえ、縦組みではこれが既定です。詩を導く段落は、最後の行を詩の最初の行と一緒に保ちます。
• 段落ちの行。 + …と書いた行は、上の行の終わりから語間の空白1つ分あとに始まります。詩劇で2人の人物が分け合う1行の組み方です。プラス記号で始まる行は\+と書きます。
• 句切れ。 開始行にkeepSpacesがあると、行の中で2つ以上続く空白がその幅を保ちます。なければ、ほかの段落と同じく空白は1つにまとまります。
• 書体と方向。 styleで段落スタイルを指定すると、書体、サイズ、行送り、indent、詩の前後のあきが決まります。dirとlangは詩の方向と言語を決めます。アラビア語の本の中のラテン文字の詩（dir=ltr）は、その詩自身の行頭側から字下げします。縦組みでは詩の各行が1列になり、天から字下げします。

bodyText.verseはすべての詩の既定値を決めます（設定 › 詩を参照）。プレーンテキストは詩を書いたとおりに保ち、行のあいだに改行、連のあいだに空行が入るので、コピーした文章も検索も1行ずつ読めます。リフロー型EPUBは各連を1つの要素にして各行の折り返しをぶら下げ、タグ付きPDFは各連を1つの段落としてタグ付けします。

行番号。 lineNumbersを有効にすると、詩の行が数えられます（設定 › 行番号を参照）。詩の各行は1回だけ数えます。折り返した部分には番号が付かず、連と連のあきも数えません。既定では5行ごとに小口側の余白に番号を印字し、詩ごとに数え直します。古典アラビア語の配置で組んだ詩は、1ベイトを1行と数えます。開始行で1つの詩を調整できます。lineStart=Nで最初の行に番号を与え、interval=Nで独自の間隔にし、numbered=falseで数えないようにします。

:::verse{lineStart=37}
…
:::

既定の間隔5では、この詩の行の横に40、45などが印字されます。

古典アラビア語の配置

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

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

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

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

#:::toc

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

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

2つの属性を使うと、設定にかかわらず、1つの目次の出力を変えられます。levelsは載せる見出しレベルを指定します。範囲（levels="1-2"）、1つのレベル（levels="2"）、リスト（levels="1,3"）のいずれかです。toc.levelsにスタイルのないレベルは、最も近い上位レベルのスタイルを使います。keepは、toc.groups.keepTogetherと同じく、目次の各グループを1つの段、1つのページにまとめます。keep="part"は部の行とその章を、keep="1"（～"6"）はそのレベルの見出しとその下の項目をまとめ、keep="none"は設定でのまとめを解除します。入りきらないグループは、まるごと次の段か次のページに移ります。1段より高いグループは分割し、続きが入る段の頭にもう一度先頭行を組んで、「（続き）」のような続きの印を添えます。

# Contents {style="front-matter" toc="false"}
 
:::toc{keep="part" levels="1-2"}

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

#:::index

:::indexは、その位置に索引を出力します。本全体で:index[…]や:index{term="…"}で印を付けた語を、テキストの移動に追随するページとともに並べます。印の付け方とあわせて、索引で説明します。段がグループの最初の項目の直後や最後の項目の直前で終わることはありません。そのグループの項目を前後に2つずつ残すか、グループをまとめて次の段に送ります（index.groups.splitMinEntries）。

# Index {style="index"}
 
:::index

#段落内の改行

段落の行はスペースを挟んでつながります（和文の文字どうしの間には入りません）。新しい段落を始めずに段落の中で改行するには（住所、手紙の宛名、献辞など）、原稿の行末にバックスラッシュを置くか（CommonMarkのハードブレーク）、\\の後にスペースを入れて書きます。

北の桟橋の先に住む\
灯台守の方へ
 
山田花子 \\ 東京都千代田区丸の内1-1 \\ 〒100-0005

• 改行の前の行は、段落の最終行と同じく自然な幅で組み、版面の幅まで伸ばしません。改行の後の文字は同じ段落の新しい行として始まり、字下げも段落間のアキも入りません。ぶら下げインデントがあれば、1行目より後の行と同じくぶら下がります。
• 段落、引用（> 1行目\の次に> 2行目）、脚注、リスト項目で使えます。リスト項目は原稿の1行なので、\\で改行します。
• 段落の末尾のバックスラッシュはCommonMarkと同じくそのまま印字され、続けて2つ置いた改行は1つになります。空行を入れたいときは新しい段落にするか、:::spaceを加えます。
• 次の文字に続けて書いた\\は改行になりません。\\*はバックスラッシュとエスケープしたアスタリスク、C:\\Tempは2つのバックスラッシュを印字します。インラインのコードと数式の中のバックスラッシュは、コードと数式のものです。
• CommonMarkのもう1つのハードブレークである行末の2つのスペースは改行になりません。エディターでは見えず、多くのエディターが消し忘れたスペースを残すので、意図しない行で改行してしまうためです。
• HTMLビューアーからコピーした文章には改行の位置に改行文字が入り、リフロー型EPUBは<br/>、PDFから取り出した文章は行末、Wordへの書き出しは手動改行（Shift+Enter）になり、Wordからの読み込みではそれを改行として読み戻します。
• 詩は:::verseブロックに入れれば、行、字下げ、連がそのまま保たれ、各行にバックスラッシュを置く必要はありません。

postext 1.22まではバックスラッシュがそのまま印字され、行はスペースを挟んでつながっていました。その当時に保存した本で、行末がバックスラッシュで終わる行や、後ろにスペースのある\\を含むものは、その読み方を保ちます（bodyText.hardLineBreaks: false。設定 › postext 1.4以前で書き出したバンドルを参照）。

#タイトル内の改行

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

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

#漫画

漫画のページ、帯漫画、見開きは、エンジンが中身を自分で1行ずつ読む2つのフェンス付きブロック、:::pageと:::stripで書きます。その中では::panelの行がコマを始め、台本の行がそのコマを写植します。割り付けの規則、写植、出力を含むガイドは漫画に、設定は設定 › 漫画にあります。

#:::page

:::page{split="30 [30 | 20 | *] / *" gutter=4mm}
::panel{art=lh-arrive}
caption: 毎年夏になると、マヤは灯台で一週間を過ごした。
maya: おじいちゃん、来たよ！
::panel{art=lh-radio focus="40% 50%"}
tomas: ちょうどいいところに来た。
::panel{art=lh-maya}
maya{thought}: あのバルブ、ゆるんでるみたい……
::panel{art=lh-beam bleed}
sfx{rotate=-8}: バキッ
:::

:::pageブロック1つが漫画の1ページです。新しいページを始めてその全体を占め、閉じの:::の後のテキストは次のページから始まります。属性はsplit（ページを区画に割る方法。段は/、横に並ぶコマは|で区切ったパーセントのサイズ、区画をさらに割るには角かっこの並び、残りは*、斜めの線はa~b）、gutter（長さ1つ、または段の間とコマの間の2つ。単位のない数値はミリメートル）、style（名前付きのコマのスタイル）、bleed、direction（ltrかrtl。dirとも書けます）、spread（見開きを参照）です。splitがなければ、コマは同じ高さの段に積み重なります。ブロックの中では、Markdownのブロック、コンテナー、ディレクティブは読まれませんが、<!-- comments -->はコメントとして認識されます。

#コマ

::panel{…}の行がコマを始めます。コマは読む順で次の区画を埋め、次の::panelの行か閉じのフェンスまで続きます。

#台本の行

コマの各行は、吹き出し、ナレーション、描き文字のどれか1つで、key{attributes}: textと書きます。

maya: おじいちゃん、来たよ！
tomas{whisper}: しっ。聞いてごらん。
caption{at=bottom-end}: 通りを三本隔てたところ。
sfx{at="62% 40%" rotate=-8 size=1.4}: バキッ
ben{tail=start}: （コマの外から）こっちだ！
sfx{vertical size=2.6 font="Dela Gothic One"}: ドン
maya：この行は
  次の行に続いて、\
  ここで改行される。

• キーは話し手のID（英字、数字、_、.、-）で、どの言語の版でも同じです。caption、sfx、noteは予約されています。コロンは全角の：でもかまいません。
• 波かっこの中に語だけを書くと吹き出しのスタイルになります（thought、whisper、shout、radio、inner、またはcomics.balloonStylesのどれか）。style=でも同じことを指定できます。
• atは吹き出しの位置を固定します。コマの絵に対するパーセントで表した点（at="62% 40%"）か、角か辺（top-start、top-end、bottom-start、bottom-end、top、bottom）です。toはしっぽを絵の点に向け、tail=noneはしっぽをなくし、tail=top|bottom|start|end|left|rightはしっぽをコマの外へ向けます。joinとjoin=falseは、吹き出しを同じ話し手の直前の吹き出しにつなげるか、離しておきます。breakは枠線を越えることを許し、その越境ははみ出しとして報告されません。rotate（度）、size（倍率。描き文字用）、color、fontは文字を変えます。
• verticalとhorizontal（またはmode=vertical、mode=horizontal）は、本全体より優先して、その行の組み方向を決めます。翻訳しないドンを横組みの版で縦に、横書きの看板を縦組みの版で横に組む、といった使い方です。ほかの言語の本で縦に組んだ行は、その行自身の文字の規則に従います（かながあれば日本語の規則）。縦組みの本では、中国語や日本語の文字を含まない行はもともと横に組まれます。
• スペース2つかタブで字下げした行は、上の吹き出しの続きになります。行末のバックスラッシュは、テキストをそこで改行します。空行は無視されます。
• テキストはインラインのMarkdownです。強調（ボールドイタリックで写植します）、:tcy、:ruby（読みを親文字の上に組みます。右から左に読む親文字は除きます）、:ltr、:rtl（文字列を本来の向きのまま保ちます）が使えます。脚注と:refの印は読まれません。

#:::strip

:::strip{split="* | * | *" aspect=3 span=page placement=top}
::panel{art=pip-1}
pip: おはよう、オットー！
::panel{art=pip-2}
::panel{art=pip-3}
otto: いい朝かね？
:::

:::stripはページと同じ中身を持ちますが、本文の中に、コマに割った分割できない1つの箱として置かれます。属性はspan（columnが既定、またはpage）、placement（書いた位置に置く既定のhere、または図と同じくフロートにするtop、bottom、auto）、そしてサイズで、height（長さ。単位のない数値はミリメートル）かaspect（幅と高さの比。3、4/1、4:1。既定はコマが正方形になる比）のどちらかです。複数段のページでhereに置いたページ幅の帯漫画は、ページ幅の囲みと同じく、置いた位置で段を区切ります。widthは帯漫画をまたぐ行長より狭くし（行長の60%、または長さ）、alignはその行長のstart、center（既定）、endのどこに置くかを、文字の方向に沿って決めます。caption="…"は、キャプションスタイルで帯漫画の下にキャプションを組みます。type=figure（リソースの種類）を付けると、キャプションにその種類のラベルと番号が付き、帯漫画はその種類の番号の並びに数えられます。id=…を付けると:refで参照できます。splitがなければ、コマは横に並びます。帯漫画は章の最上位でだけ読まれます。

#見開き

:::page{spread}は、1ページを向かい合う2ページにわたって組みます。割りは、内側の余白を除いてのどでつないだ2つの版面を覆い、コマはのどをまたいでもかまいません。見開きは偶数ページから始まり、必要なら前に白ページが入ります。漫画 › 見開きを参照してください。

#テンプレートページ

テンプレートページは、設定のページテンプレート（pageTemplates）から組み、その枠へ名前で内容を流し込むページです。警告を含む手引きはテンプレートページにあります。

• ::::page{template="…"} … ::::がページです。コロンは4つ以上で、同じ数のコロンだけのフェンスで閉じます。中のコロン3つのフェンス（:::frame、:::callout、:::figure…）はほかの場所と同じように働き、単独の:::がページを閉じることはありません。コロン3つの:::pageはコミックのページのままです。
• :::frame{slot="…" label="…"} … :::には、その名前の枠の中身を入れます。どんなMarkdownでもかまいません。
• 見出し（## Retos {slot="retos-titulo"}）、::resource{id="…" slot="…"}、コードフェンス、:::コンテナーに付けたslot="…"は、そのブロックだけを送ります。スロットのない内容は、テンプレートの流し込み枠に入ります。
• :::figure{resource="…" slot="…"} … :::は、1つのリソースを::label[テキスト]{at="…" style="…"}の行とともに置きます。atは絵のアンカーか、"x% y%"の点です。図は本文の流れの中でも使えます。