コマンドライン：ターミナル、スクリプト、エージェントでpostextを使う

postextは、ターミナル、スクリプト、エージェントから本を組みます。

Sandboxは、目で確かめながら本を書き、デザインする場所です。コマンドラインは同じ本を受け取り、ブラウザーなしでそのファイルを作ります。印刷用のPDF、HTMLのページ、EPUB、1ページまたは全ページの画像、Wordの文書です。ほかに、.postextバンドルをまとめたり展開したり、Wordの文書を読み込んだり、本の内容を示したり、本に問題がないかを検査したりもします。

システムごとに自己完結した1つの実行ファイルです。postextのエンジン、PDF、EPUB、HTML、Wordの書き出し、ページを描くペインター（Skia）、アラビア語などの複雑な文字のためのHarfBuzz、印刷用のICCプロファイル、既定のフォント（EB GaramondとOpen Sans）がすべて入っています。インストールするランタイム、パッケージ、ライブラリーはありません。レイアウトはSandboxと同じなので、同じ本は同じページに分かれます。

#入手する

Postextのリリースごとに、実行ファイルがGitHub Releaseで公開されます。チェックサム（SHA256SUMS）とreadme.txtも付いています。

各ファイルの大きさは115〜140 MBです。https://github.com/drnachio/postext/releases/latest/download/<file>のリンクは、つねに最新のものを指します。

LinuxまたはmacOSでは次のとおりです。

curl -fL -o postext https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
chmod +x postext
./postext

PATHの通ったフォルダー（/usr/local/bin、~/.local/bin）に移すと、どこからでもpostextとして実行できます。macOSは、ブラウザーでダウンロードしたファイルを隔離します。一度だけ、そのフラグを外します。

xattr -d com.apple.quarantine postext-macos-arm64

Windowsでは、PowerShellで次のようにします。

Invoke-WebRequest https://github.com/drnachio/postext/releases/latest/download/postext-windows-x64.exe -OutFile postext.exe
.\postext.exe

Node.jsがあれば、npx postext-cliが自分のシステム用の実行ファイルをnpmからダウンロードして実行します。npm install -g postext-cliなら、postextコマンドとして残ります。

引数なしで実行すると、postextはヘルプを表示します。postext help <command>は1つのコマンドのオプションを一覧にします。

#最初の本

フォルダーに入れた3つのMarkdownファイルは、それだけで1冊の本です。ファイルごとに1章になり、名前の順に並びます。

postext pdf chapters/ --name "Field notes" -o field-notes.pdf

最初の章のフロントマターが本のタイトルと著者を決め、残りはエンジンの既定値が受け持ちます。2段組み、ベースライングリッド、両端そろえとハイフネーション、柱です。必要になったら、設定と画像を加えます。

postext pdf chapters/ --config design.json --resources pictures/ -o field-notes.pdf

Sandboxで作った本（本パネルのダウンロード（.postext））は、そのまま使えます。

postext pdf my-book.postext -o my-book.pdf
postext image my-book.postext --page 1 -o cover.png

#本として読めるもの

本を読むコマンドは、どれも次のいずれかを受け付けます。

• .postextファイル：Sandboxが書き出し、開くバンドルです（バンドルを参照）。
• 本のフォルダー：展開したバンドルで、preset.json、章、リソース、フォントを持ちます。エージェントスキルが納品するのはこの形で、postext unpackもこれを書き出します。
• ばらのMarkdown：1つ以上の.mdファイルで、指定した順に1ファイル1章になります。フォルダーを渡すと、その中の.mdファイルを名前の順に読みます（01-intro.md、02-method.md…）。あわせて次のものを指定できます。
  • --config design.json：設定です。設定のオブジェクトだけでも、preset.json全体でもかまいません。
  • --resources pictures/：画像です。それぞれ、拡張子を除いたファイル名を名前とする図になります（map.pngは::resource{id="map"}）。フォルダーにresources.jsonがあれば、代わりにそれが画像を記述します（id、種類、キャプション、代替テキスト）。形式はpreset.jsonのresourcesと同じです。
  • --fonts fonts/：本が持つフォントファイル（TTF、OTF、WOFF2）です。フォントのテーブルが示すファミリー名で識別されます。
  • --name "Title"：本の名前です。

--configはバンドルやフォルダーにも使え、本自身の設定の上に統合されます。多言語のバンドルは、--localeで別の言語を求めない限り（--locale en）、バンドル自身の言語で読まれます。

#コマンド

どのコマンドも、-oでパスを指定しない限り、実行した場所に入力の名前で書き出します。-o -は、1つの出力を標準出力に書き出します。

#pdf

postext pdf book.postext -o book.pdf
postext pdf book/ --pdfx x4 --profile fogra51 -o book-print.pdf
postext pdf book/ --color-space grayscale --no-outlines

PDFは本自身の設定に従います（PDF生成と印刷出力を参照）。次のオプションは、1回の実行に限ってそれを変えます。

• --pdfx none|x1a|x4：印刷所向けのPDF/X規格。
• --profile NAME|FILE：出力ICCプロファイル。名前（fogra39、fogra51、fogra52、swop5、gracol2006、snap2007、ifra26など、印刷設定のプロファイル）か、.iccファイルで指定します。
• --color-space rgb|cmyk|grayscale。
• --accessible / --no-accessible：スクリーンリーダーのためのタグ構造。
• --no-outlines：しおりを入れません。
• --page-negative：一部の印刷ワークフロー向けのネガのページ。

#html

postext html book.postext -o book.html
postext html book.postext -o site/ --mode single

.htmlで終わるパスには、画像とフォントを中に収めた1つのファイルを書き出します。送るのに便利です。それ以外のパスはフォルダーになり、index.htmlの横にassets/を置きます。assets/には画像、フォント、自前でホストする動画が入ります。--assets embed|folderを使うと、どのパスでもどちらかを選べます。ページは印刷用のレイアウトを画面の大きさで表示したもので、横に並べるか（--mode multi、既定）、縦に重ねるか（--mode single）を選べます。redistributable: falseと指定したフォントは、名前は記されますがコピーはされません。

#epub

postext epub book.postext -o book.epub
postext epub book.postext --layout reflowable --cover cover.jpg

--layout fixed（既定）は、すべてのページを印刷したとおりに保ち、テキストは選択できます。--layout reflowableは、読書システムがその画面に合わせてテキストを組み直せるようにします（EPUBの本を参照）。表紙は、--coverで画像を指定しない限り本のサムネイルです。パッケージのメタデータ（タイトル、著者、言語、識別子）は、Sandboxと同じく最初の章のフロントマターから取ります。

#imageとimages

postext image book.postext --page 12 -o page-12.png
postext image book.postext --page "#1" --dpi 300 -f jpeg -o cover.jpg
postext images book.postext -o pages/ --dpi 100
postext images book.postext --pages 1-10,iv -f webp --pattern "{chapter}-{label}"

ページは、印刷された番号（12、iv、範囲の7-9）か、#を付けた本の中の位置（#1は何が印刷されていても最初のページ、#10-#20、終わりまでの#30-）で指定します。--pagesはコンマ区切りのリストを受け付けます。描画するのはSandboxのCanvasビューと同じペインターなので、画像はPDFを経ずに、レイアウトしたとおりのページを示します。

• --format png|jpeg|webp（または-oの拡張子）。JPEGとWebPには--quality 1-100。
• --dpi：解像度。既定は150です。ページを読むには72〜100で足り、印刷用には300です。
• --pattern：imagesが書き出すファイルの名前。{n}（位置。{n:03}は3桁にゼロで埋めます）、{label}（印刷された番号）、{chapter}から作ります。既定はpage-{n:03}です。
• --print-preview：出力プロファイルを通して、印刷所が再現するとおりのページを、仕上がり線と塗り足しを描いて示します。
• --jobs N：同時にエンコードする画像の数。

#docxとimport-docx

postext docx book.postext -o book.docx
postext import-docx manuscript.docx -o manuscript/ --locale es --report
postext import-docx manuscript.docx -o manuscript.postext

docxは、見出し、段落、囲み、引用、リスト、注にWordのスタイルを使って章を書き出します。Wordで表現できないものはPostext Markupのスタイルでそのまま残り、読み込み用のテンプレートがファイルの中に入るので、編集者が手を加えたあとでも、文書は変わらずに読み込み直せます。import-docxはWordの文書を本にします。レベル1の見出しごとに章を分け（--no-splitなら1章のまま）、画像と表はリソースになります。--reportは、Sandboxが表示する品質レポート（使われているスタイル、直接の書式、手入力の番号…）を出力します。--templateは読み込み用のテンプレート（Sandboxから保存した.json、またはテンプレートを持つ.docx）を受け付けます。

#packとunpack

postext pack my-book/ -o my-book.postext
postext pack 01.md 02.md --name "Notes" --config design.json --resources img/ -o notes.postext
postext unpack my-book.postext -o my-book/

packは本のフォルダーをそのままzipにするか、ばらのMarkdownからバンドルを作ります。同じ入力からはつねに同じバイト列ができるので、バンドルを比べたり、ハッシュを取ったりできます。unpackは、--forceを付けない限り、空でないフォルダーには書き込みません。

#infoとcheck

postext info book.postext --pages
postext check book.postext
postext check chapters/ --strict --json

infoは、章（タイトル、語数、ファイル。--pagesを付けるとページも）、リソース、そしてすべてのフォントファミリーとその出どころ（本、フォルダー、実行ファイル、ダウンロードのキャッシュ、代替フォント）を一覧にします。本が始まりの位置を示している場合（preset.jsonのstart。58ページ、第4章から始まる抜粋など）は、それも表示します。どのコマンドも本をそこからレイアウトします。

checkは本をレイアウトし、Sandboxの検査パネルが示すものを報告します。閉じていないMarkdown、不明なリソース、ディレクティブ、スタイル、レイアウトが無理に収めた囲み、見つからないフォント、エンジンが置き換えた設定です。印刷用に設定した本（または--preflightを付けた場合）では、プリフライトも報告します。解像度不足の画像、細すぎる罫、複数インキの小さな文字、上限を超えるインキ量、仕上がり線に近い文字です。どの問題も、章のファイル、行、ページを示します。エラーが見つかると終了コードは3になります。--strictを付けると、警告が1つでもあれば3になります。

#buildと--watch

postext build book/ --pdf out/book.pdf --html out/book.html --images out/pages --pages 1-4
postext build chapters/ --pdf book.pdf --watch

buildは本を一度だけレイアウトし、指定したすべての出力（--pdf、--html、--epub、--images、--docx）を、各コマンドのオプションとともに書き出します。--watchを付けると動き続けます。章、設定、画像が変わると、フォントとエンジンを読み込んだまま本をレイアウトし直し（1章ならたいてい1秒もかかりません）、出力を書き直します。保存した内容で本が壊れたときは、エラーを出力し、最後に正しく作れたファイルを残します。

#すべての本に共通するオプション

さらに、すべてのコマンドで--json、--quiet（-q、エラーのみ）、--verbose（進行状況とすべての警告）、--no-color、--helpが使えます。

#フォント

フォントを持つ本（バンドル、または--fontsを付けたばらのMarkdown）は、そのフォントだけで組まれます。設定が指定するファミリーのうち本が持たないものは、postextが次の順に探します。

1. --font-dirで指定したフォルダー。
2. 実行ファイルに組み込まれた書体。エンジンの既定であるEB GaramondとOpen Sansです。
3. ダウンロードのキャッシュ。
4. Google Fonts。静的なTrueTypeファイルを丸ごと取得します。Google Fontsにないファミリー（Commit Mono、FiraGO）はFontsourceから取得します。取得したファイルはキャッシュに残るので、1つのファミリーのダウンロードは1回で済みます。

ファミリーにないウェイトや斜体は、いちばん近いフォントをそのまま使って組みます。ページ画像でもPDFでも同じです。ウェイトが1つだけの見出し用書体はボールドでも自分の字形のまま、イタリックのないファミリーは立体のままです。

キャッシュは~/.cache/postext（Windowsでは%LOCALAPPDATA%\postext\cache）です。POSTEXT_CACHE_DIRか--cache-dirで場所を変えられます。--offlineはダウンロードを行いません。どこにも見つからないファミリーは、その名前のままEB Garamondで組まれるので、レイアウトとPDFは食い違いません。missingFontの警告がそのファミリーの名前を示します。各ファミリーの出どころはpostext infoで確かめられます。

#スクリプトとエージェントから使う

コマンドラインは、コーディングエージェントを含むほかのプログラムから動かせるように作られています。

• --json：コマンドが終わったときに、1つのJSONオブジェクトを標準出力に出力します。メッセージはすべて標準エラーに出ます。レポートには、書き出したもの、ページ、出どころ付きのすべての警告、各段階にかかった時間（ミリ秒）が並びます。

{
  "ok": true,
  "command": "pdf",
  "version": "1.22.1",
  "book": { "name": "notes", "id": "notes", "locale": "en", "chapters": 2 },
  "pages": 3,
  "outputs": [{ "kind": "pdf", "path": "notes.pdf", "bytes": 29746, "pages": 3 }],
  "warnings": [
    {
      "kind": "unknownResourceId",
      "severity": "warning",
      "message": "Unknown resource id \"map\" in ::resource — nothing is embedded (offset 26)",
      "at": "notes/02-more.md:5"
    }
  ],
  "timings": { "read": 13, "fonts": 8.4, "math": 28.2, "layout": 51.6, "pdf": 132.1, "total": 1638 },
  "exitCode": 0
}

• 終了コード：0は完了、1は失敗、2は使い方の誤り（不明なオプション、入力の指定漏れ）、3はcheckがエラー（--strictでは警告）を見つけたことを示します。
• 質問しません。入力を待つことはありません。空でないフォルダーは、確認を求めずに拒否します。
• 標準出力：-o -は、PDF、画像、バンドルを標準出力に書き出し、パイプで先に渡せるようにします。
• 速度。実行ファイルは数百分の1秒で起動します。短い本なら、PDFやページ画像は1秒を大きく下回る時間でできます。長い本は、そのレイアウトにかかる時間がかかります（140ページの挿絵入りの小説で約10秒）。長い本の数ページを見るには、--chaptersをimageかimages --pagesと組み合わせます。多くの変更を重ねながら本に取り組むときは、postext build --watchを動かしたままにして、その出力を読みます。

エージェントスキルは、作業中のページを描画したり、移植を検査したりするのにコマンドラインを使います。

#しくみ

コマンドラインは、リポジトリのpostext-cliパッケージです。Bunがそれをエンジンと書き出し機能とともに、システムごとに1つの実行ファイルにコンパイルします。テキストの計測と描画は、Sandboxでブラウザーのcanvasが行うのと同じように、Skia（@napi-rs/canvas経由）が行います。リリースのたびに実行ファイルがビルドされ、Linux、Alpine、macOS、Windowsで実行されてから、GitHub Releaseに添付されます。npmにはpostext-cliと、実行ファイルごとに1つのpostext-cli-<system>パッケージが公開されます。

リポジトリのコピーから実行するには次のようにします。

pnpm install
pnpm --filter postext-cli start pdf book.postext
pnpm --filter postext-cli build:bin --current

1つ目はソースから実行します。2つ目は、このコンピューター用の実行ファイルをpackages/postext-cli/bin/に書き出します。

#Sandboxとの違い

• HTMLは、印刷用のレイアウトを画面の大きさで表示したものです。SandboxのHTMLタブは、ウィンドウに合わせてテキストを組み直します。
• --chapters：指定した章だけを単独でレイアウトします。そのページ番号は振り直されますが、Sandboxは本全体の番号を続けます。
• フォントは、本、指定したフォルダー、実行ファイル、Google Fontsから取り、コンピューターにインストールされたフォントは使いません。そのため、本はどの環境でも同じように仕上がります。