設定：リストと数式

#箇条書きリスト

unorderedListsプロパティは、箇条書きリスト（-、*、+）とGFMのタスクリスト（- [ ]、- [x]）の描画方法を制御します。入れ子は5階層までサポートしています。

#箇条書きリストの既定値

#タスクリストの拡張

GFMのタスク項目（- [ ] …、- [x] …）は、行頭記号の代わりにチェックボックスを置いた箇条書きの項目として描画されます。ボックスはエンジン自身が描きます。四角い枠線で、完了した項目にはチェックが入ります。フォントに字形を求めないので、どのマシンでも、キャンバス、PDF、HTML、EPUBのどれでも同じ形になり、支援技術は☐または☑と読み上げます。一辺はマーカーのサイズ（bulletFontSize、またはレベルのfontSize）の0.6 emで、gapの前に取る幅もこの長さです。マーカーが本文と同じサイズなら、項目の1行目のベースラインに載ります。線の太さはマーカーのfontWeightに、色はマーカーのcolorに従います。次のフィールドはタスク項目にだけ適用されます。

#箇条書きリストのレベル別上書き

levelsの各エントリーは1つの深さ（1–5）を対象とし、次のどの項目でも上書きできます。

インデントの連鎖。レベル1は常に全体のindentの値から始まります（既定は0 emで、行頭記号は段の端に固定されます）。レベル2–5では、indentを未定義のままにすると、エンジンは行頭記号を1つ上のレベルの文字の開始位置（親のインデント＋行頭記号の幅＋gap）に置きます。あるレベルにindentを明示すると連鎖が切れ、その深さを好きな位置に固定できます。

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#番号付きリスト

orderedListsプロパティは番号付きリスト（1.、2)など）を制御します。入れ子は5階層までサポートしており、深さごとに異なる番号の書式を使えます。

#番号付きリストの既定値

#番号付きリストのレベル別上書き

levelsの各エントリーでは、numberFormat、prefix、separator、fontFamily、fontSize、color、fontWeight、italic、indent、verticalOffsetと区切りのスタイル（separatorFontFamily、separatorFontWeight、separatorItalic、separatorColor、separatorGap）を上書きできます。箇条書きリストと同じインデントの連鎖が適用されます。あるレベルの区切りのスタイルは、リスト全体の区切りの設定が指定されていない限り、そのレベル自身の番号のスタイルを継承します。

右そろえ。パイプラインは連続部分の中でもっとも幅の広い書式付きの番号を測り、その連続部分のすべての項目をインデントして、番号の右端をそろえます。1.–10.と描画される10項目のリストでは、1桁の番号に余白を補い、区切りが同じ位置にそろうようにします。

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

これで、定番の入れ子の組み合わせになります。

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

中国語の公文書の階層（GB/T 15834—2011、付録B.3）は5レベルで、一、→（一）→1.→（1）→①の順になります。

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#数式

mathプロパティは、$...$（インライン）と$$...$$（別行立て）で囲んだLaTeXの数式の解析と描画の方法を制御します。基盤のエンジンはSVG出力モードのMathJax（mathjax-fullパッケージ）で、キャンバスにはラスタライズして描画し、PDFには拡大縮小可能なグリフとして埋め込みます。

interface MathConfig {
  enabled?: boolean;        // Render LaTeX. When false, spans pass through as literal TeX.
  fontSizeScale?: number;   // × the surrounding text's size (the body size for display maths).
  color?: ColorValue;       // Formula colour; inherits body colour if omitted.
  marginTop?: Dimension;    // Space above display math blocks.
  marginBottom?: Dimension; // Minimum space below; baseline grid snap may enlarge it.
  indentAfterDisplay?: boolean; // Indent a paragraph that follows a display formula.
  keepWithLeadIn?: boolean; // Keep a display formula with the line that leads into it.
  equationNumbering?: {      // Number the display formulas that carry a \label.
    enabled?: boolean;           // default true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numbers by chapter
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': what the formula and \eqref print
  };
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

数式のサイズ（postext 1.5で変更）。MathJaxは数式のボックスをexで返し、TeXフォントの1exは0.442emです。postext 1.4まではエンジンがこれを0.5emとして扱っていたため、どの数式もbodyText.fontSize × fontSizeScaleより約13%大きく組まれていました。現在は数式がドキュメントに記載したとおりのサイズで組まれ、数式を含む行とページは組み直されます。1.4向けにコードで書いた設定は、書いたままの状態でpostext/bundleのpinLegacyMathSizeに1回通すと、1.4の数式サイズを保てます。

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // formulas, and the space around display formulas, as 1.4 set them

1.5でのほかの規則の変更でも、ページが動くことがあります。対象は、見出しの改行位置、インラインの図の周囲のアキ（本文中と囲みの中）、見出しのインラインのマーク、ドロップキャップのサイズ、コロンで終わる行の下に、それが導入するリストのために確保する余地、囲みの分割で段落やリスト項目に残る行、ダッシュの後の改行、行末不ぞろいのテキストの改行、見出しの下での段落の分割、複合語のハイフンの後の改行、:::paragraphsコンテナーの下のアキです。その設定で組むMarkdownを渡してmigrateConfigを1回実行すると、そのテキストに必要なものを、数式のサイズも含めて固定します（postext 1.4以前で書き出したバンドルを参照）。

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // heading breaks, formulas, inline gaps, heading marks, drop caps, colon lines, box cuts, dash breaks, compound breaks, ragged breaking, splits under a heading and container space as 1.4 set them

これで、こうした規則の変更によって動くものは抑えられますが、1.4のページがすべて保たれるわけではありません。バージョン1.5ではレイアウトのバグも修正しており、修正は固定できません。古い設定にも新しい設定と同じく修正が適用されるため、修正の影響を受けるページは動くことがあります。主なものは次のとおりです。独自のデザインを持たないページ幅の見出しは、ページ全体の幅で測られ、そのレベルの行送りで組まれます。見出しデザインの中のドロップキャップのベースラインの下には、何も確保されません。ドロップキャップはセクションのパレットの色を取り、overflowが'wrap'でないデザインテキストにも組まれ、そのテキストは回り込むようになります。囲みの中の段落は、測ったときのトラッキングで描画されます。分割された囲みは、すべての断片でアイコンの列を保ちます。語間を3倍を超えて広げることになる囲みの行は、本文と同じく行末不ぞろいで組まれます。ゆるい段落を調整する仕組みは、両端そろえの行をmaxWordSpacingが許す以上に広げません。フロートとして配置した囲みは、フロートのアキより広いmarginBottom（上の帯の場合）またはmarginTop（下の帯の場合）を保ちます。トラッキングを指定した中央そろえまたは右そろえのデザインテキスト（柱、章扉のタイトル）は、最後の文字の後のトラッキングを含めず、文字そのもので位置が決まります。ページ幅の章扉の下では、2段目を始めるテキストが、章扉の直下のテキストと同じ位置から始まります。章扉の後に見出しが続く場合も同様です。連続するドットをカーニングで離す書体でも、目次のリーダーはページ番号の手前で止まります。柱は見出しを書かれたとおりに読み、ハイフンやダッシュの後、または幅のために分割された語の途中で行が終わる箇所に空白を入れません（MEDIOAMBIENTALE SではなくMEDIOAMBIENTALES）。見出しデザインの{titleText}も同じように読みます（thousand- colourではなくthousand-colour）。見出しデザインの帯の下端または中央に固定したテキストは、それが収まる高さに帯を保つため、見出しの上のテキストに重なることがなくなりました。行より幅の広い語が、その語に含まれるハイフンの隣で分割される場合は、そのハイフンの後で分割され、2つ目のハイフンは付きません。別のリストに入れ子にしたリストの後の項目は、入れ子のリストではなく自分のリストのitemSpacingを使います。最後に、行より幅が広いために分割された語の残りは、その語自身の分割位置を保ちます。そのため、Webアドレスは区切りの位置で、複合語はハイフンの位置で改行され続け、辞書の音節で改行されることはありません。

pinLegacyMathSizeは倍率に1.1312（0.5 ÷ 0.442）を掛け、emで指定した別行立て数式のアキを同じ係数で割ります。別行立て数式を含む本では、倍率だけでは足りません。そのアキは数式自身のサイズに対する長さなので、同じく13%大きくなり、下のテキストを押し下げてしまいます。既定のアキについて書き出すと、3つの値は次のとおりです。

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // formulas as large as 1.4 set them, with the space 1.4 left around them

設定が保存されていた場合は、エンジンがそれを判別して自動的に処理します。1.5より前に書かれた.postextバンドルではopenBundle / readBundleが（postext 1.4以前で書き出したバンドルを参照）、その時期に保存された本、作業コピー、postext-config.jsonファイルではSandboxが処理します（Sandbox → 作業内容の保存を参照）。これらはmigrateConfigを通して読み込まれ、サイズが固定されます（pinLegacyMathSize）。fontSizeScaleは保存されていた倍率（未設定なら1）×1.1312になり、emまたはremで指定した別行立て数式のアキ（数式自身のサイズに対する長さ）は同じ係数で割られるため、別行立て数式の周囲のアキは1.4のときのまま保たれます（既定の0.8emは0.7072emになります）。ページの単位（pt、mm…）で指定したアキはそのままで、enabled: falseの設定や、本に$がない設定も変更されません。こうして古い本は1.4と同じように組まれ、そのmathセクションには実際に組まれるサイズが表示されます。そのような本を現在のサイズで組みたい場合は、これらの値をリセットします。Sandboxでは数式 → サイズの倍率、別行立て数式の上のアキ、別行立て数式の下のアキで、コードでは次のようにします。

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // today's size and margins

番号付きの数式。番号の付いた別行立て数式は、その組幅（段、または囲みの内側の幅）いっぱいに広がります。数式は中央に置かれ、その番号は数式の行の右端にそろえて組まれます。alignでは、番号の付いたすべての行でそうなります。番号は\label{eq:x}から付きます（postext 1.19以降）。ラベルを付けた数式と、align、gather、alignat、flalign、eqnarrayのラベルを付けた行には、\nonumberや\notagを書いた行を除き、equationNumberingに従って読む順に番号が振られます。equationなどの環境はそれだけでは番号が付かず、ラベルのない数式には番号がありません。\tag{…}は指定したラベルを括弧に入れて、\tag*{…}は書かれたとおりに印字します。どちらも数えられず、その横の\labelはそれに名前を付けます。組幅より広い番号付きの数式は、ほかの別行立て数式と同じく右へはみ出します。（postext 1.4までは、\tagを含む数式はまったく描画されず、1.18までは\tagだけが番号を付けていました。）

本文の\eqref{eq:x}は番号をそのformatで（(3)）、\ref{eq:x}は番号だけを印字します。:ref{id="eq:x"}と@eq:xも同じです（相互参照を参照）。数式の中では、\eqrefは番号をテキストとして印字します。章ごとに組む本では、カウンターは前の章から続きます。continuationAfterがそれをLayoutContinuation.statementCounters（equation）で引き継ぎ、本のアウトラインがすべてのラベルに番号を与える（OutlineEntry.numberLabel）ので、別の章の数式への参照もその番号を印字します。

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1), (1.2)… (2.1)
}

解決関数（resolver）と既定値の除去関数（stripper）は、ほかのセクションと同じ形です。

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#数式エンジンの起動

MathJaxはエンジンのほかの部分と一緒には読み込まれず、必要になったときに読み込まれます。メインスレッドでレイアウトする場合は、数式を含む文書を構築する前に起動してください。

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // loads MathJax once; later calls resolve at once
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• エンジンが動くまで、数式はプレースホルダーです。各数式は推定サイズの灰色のボックスとして配置されます。initMathEngine()を一度も呼ばずに数式を含む文書をレイアウトすると、コンソールにその旨の警告が1回表示されます。
• レイアウトワーカーは自動で起動します。postext/workerでのビルドは、Markdownに$が含まれていれば自らinitMathEngine()を呼びます。
• すぐにレイアウトし、準備ができたらもう一度。isMathReady()はエンジンが動いているかどうかを返します。onMathReady(fn)はエンジンが動き出したときに（すでに動いていればすぐに）fnを1回呼び、その呼び出しを取り消す関数を返します。エディターはすぐにプレースホルダーを表示し、MathJaxが届いたらもう一度レイアウトできます。initMathEngine()の実行中は警告は出ません。
• 失敗。MathJaxを読み込めない場合、initMathEngine()はrejectされます。次の呼び出しで再び読み込みを試みます。
• どのバンドラーでも、Nodeでも、CDNでも。MathJaxは、事前にバンドルした1つのモジュールとしてパッケージに同梱されています（圧縮前で約1.8MB、initMathEngineが呼ばれたときにだけ取得されます）。単純なimport { initMathEngine } from 'https://esm.sh/postext'で動作し、?bundleは不要です。mathjax-fullパッケージはpostextのビルドにだけ必要なため、postextをインストールしてもインストールされません。MathJaxと、それに同梱されたmhchemパーサーはApache-2.0ライセンスです。それらの告知とライセンス文は、モジュールの隣にdist/math/THIRD_PARTY_LICENSES.txtとして同梱されています。
• 1ページにエンジンは1つ。エンジンと、描画済みの数式のキャッシュは、同じJavaScriptレルムでpostextをインポートするすべてのコードで共有されます（1つのページで共有されるグローバルな状態を参照）。

文書側の文法（$...$、$$...$$、ドル記号そのもののエスケープ）については、文書形式を参照してください。