機能

Shojikuは、テンプレートのYAMLとデータのJSONからPDFを作るエンジンです。このページは、そのエンジンで実際に何が作れるかを一通り並べたものです。キーの綴りや既定値はリファレンスにあります。ここでは、作れるものと作れないものを先に把握できるようにしました。

書いてある機能はすべて実装済みで、ギャラリーの25点はどれもこのエンジンが出力したPDFです。

作れる書類

請求書、見積書、納品書、領収書、宛名ラベル、イベントチケット、商品カタログ、賞状、履歴書、飲食店のメニュー、原稿用紙、縦書きの文庫本。ギャラリーにあるのはこれらの実物で、テンプレートとデータのファイルもリポジトリにそのまま入っています。

得意なのは、書式は決まっていて、中身のデータだけが変わる書類です。1件のデータから1枚を出すことも、22行の明細を見出し付きで複数ページに送ることも、1枚の用紙に6面を面付けすることも同じ仕組みでできます。

ページを組む

配置の方法は4つあります。上から順に積むflow、横に並べて余りを配分するflex、行と列で揃えるgrid、座標で置く絶対配置です。1つのテンプレートの中で混ぜられます。請求書の本文はflowで流し、宛名欄だけ座標で固定する、という書き方になります。

containerで入れ子にすると、内側の要素は親の幅を基準に%で書けます。中身が増えてページに収まらなくなったときは自動で改ページされ、page_breakを置けば明示的に切れます。用紙サイズはA4やLetterのような名前でも、80mmのレシート紙のような実寸でも指定できます。

表と繰り返し

tableは明細行のための要素です。行数はデータの長さで決まり、ページをまたぐときは見出し行を各ページの先頭に繰り返せます。列幅、罫線、セルの結合、行ごとの条件付きスタイル（「状態がpartialの行だけ背景色を変える」など）が指定できます。

同じ形を何度も並べるのがrepeatで、宛名ラベルの2列3段やチケットの2列4段はこれです。1件ごとに高さが変わるものはrepeat_flowを使い、カタログのカードのように高さがまちまちな箱を順に流します。

日本語の組版

縦書きを本文として組めます。ルビ、禁則処理、縦中横、行頭行末の約物処理、文字送りの調整が揃っていて、ギャラリーの文庫本はこれで組みました。原稿用紙はchar_gridという専用の要素で、マス目に1文字ずつ入り、ルビも振れます。

和暦にするかどうかは、データではなく表示側の指定です。値は日付のまま持ち、令和で出すか西暦で出すかをテンプレートが決めます。郵便番号の枠、税率ごとの内訳、丸を付ける選択欄のような、日本の帳票でよく出る形も揃っています。

データを流し込む

データ項目はdefinitions.ymlという台帳に宣言します。テンプレートはそこにあるキーしか参照できず、未宣言のキーを書くとレンダリングの前にエラーになります。型、制約、サンプル値も台帳側に書きます。

値は数値や日付のまま渡し、桁区切りや通貨記号や日付の書式は表示の瞬間に適用されます。書式はCSSと同じように継承するので、通貨スタイルを親に一度書けば下の金額はすべて従います。ロケールを差し替えると、通貨、日付の並び、フォントが一緒に切り替わります。日本語と英語は組み込みで、繁体字、簡体字、ヒンディー語、フィリピン語、タイ語はパックとして同梱しています。

文字以外の要素

要素の種類は全部で15です。文字、矩形、線、表、ページ番号、画像、コンテナ、繰り返し2種、QRコード、箇条書き、改ページ、原稿用紙、楕円、チェックボックス。

画像はPNG、JPEG、GIF、WebP、SVGを置けて、枠に対する収め方（coverやcontain）と不透明度が指定できます。QRコードは値から生成され、リンクはPDFのクリック可能な領域になります。丸囲みやチェックボックスはフォームマークとして要素になっていて、申込書の選択欄はこれで作ります。

フォント

フォントはパックとして同梱します。日本語のBIZ UDゴシックと明朝、Noto Sansの各種、等幅、繁体字と簡体字、デーヴァナーガリー、タイ文字の8パックが入っていて、足りなければ自分のフォントをパックにして追加できます。

エンジンはシステムにインストールされたフォントを一切見ません。これは意図的な設計です。同じテンプレートを手元のマシンとCIでレンダリングしたとき、参照するフォントのバイト列が同じになるので、出力も一致します。フォント名の解決に失敗したときは黙って代替せず、診断として報告します。

出力と検証

出力はPDFと、プレビュー用のPNGです。同じ入力からは、いつどのマシンで実行してもバイト単位で同一のPDFが出ます。作成日時のようなメタデータも入力から決まります。

PDFへの署名と、その検証も同じエンジンが担います。検証結果は「何を確認したか」だけでなく「何を確認していないか」も報告します。署名の対象範囲が文書全体を覆っていない場合、署名自体が有効でも改竄として扱います。レンダリング、署名、検証はネットワークに出ません。

呼び出し方と、できないこと

コマンドラインから使えます。AIエージェント向けにはMCPサーバがあり、検証、プレビュー、機能一覧を扱えます。Ruby、Python、.NET、Java、JavaScript、PHP、Goの7言語のSDKが公開済みで、どれも同じエンジンのバイナリを呼びます。ブラウザではWASMとして動き、このサイトのプレイグラウンドがそれです。テンプレートをGUIで編集するDesignerもあります。

できないことも書いておきます。エンジンは計算しません。合計や税額は、渡す前に計算しておく必要があります。テンプレートにスクリプトは書けず、条件はデータ側の値で表現します。システムフォントは使えません。エンジンが扱えない書き方をしたときは、それらしい出力を作らずに、132個ある診断コードのどれかで報告します。