執筆ガイド
Oxiquill のページは MDX file です。ページは通常の文章ノートにも、実行可能な計算ノートにも、メディア付きの説明にも、その組み合わせにもできます。
ページを追加する
Section titled “ページを追加する”各ページは Starlight frontmatter から始めます。title はページ見出しと sidebar label に使われます。description は metadata と検索結果に使われます。
---title: Page titledescription: Explain the page in one sentence.---
Write the body here.英語ページは content/docs に追加します。日本語翻訳は同じ route で content/docs/ja に追加します。primary navigation に出したいページは astro.config.mjs の sidebar に追加します。
置き場所の目安:
guides/<topic>.mdx: 作業手順の説明。features/<feature>.mdx: 機能説明と例。samples/<topic>.mdx: 完成したサンプルノート。
読者向けに書く
Section titled “読者向けに書く”最初に、そのページで読者が何をできるようになるかを書き、その後で例に進みます。見出しで目的、構文、動作を分けます。サンプルセルはテスト、スクリーンショット、読者の表示が安定するように deterministic にします。
日本語翻訳は英語版と同じ route と大まかな構成を保ちます。一字一句同じ訳である必要はありませんが、同じ動作と例を扱います。
ページの目次を選ぶ
Section titled “ページの目次を選ぶ”通常のページには Starlight の目次が表示されます。desktop では右列を折りたたむことができ、Oxiquill は現在の browser tab でその選択を記憶します。mobile では Starlight の既存 disclosure をそのまま使います。
目次も desktop control も不要なページでは、frontmatter に tableOfContents: false を指定します。Starlight の splash page でも両方が自動的に省略されます。このページ単位の設定は、desktop collapse control だけを有効・無効にする project-wide の desktopTableOfContentsToggle option とは別です。
Rust セルを書く
Section titled “Rust セルを書く”Rust セルは rust の fenced code block で、先頭に //| または ///| metadata comment を置きます。metadata comment は cell の先頭から連続させ、source code が始まった後の option comment 風の行は source code のままにします。id は lowercase kebab-case でページ内一意にします。英語版と日本語版は同じ local id を使えます。build が page-scoped internal ID を作ります。
```rust//| id: sample-rust-cell//| title: Rust calculation//| run: button//| crates: [doc-rust]let next = doc_rust::logistic_step(3.2, 0.2);println!("next = {next:.6}");```crates には crates/* 配下の helper crate package name を指定します。共有 Rust ロジックを使わないセルは crates: [] にします。
Python セルを書く
Section titled “Python セルを書く”Python セルは python の fenced code block で、先頭に #| metadata comment を置きます。
```python#| id: sample-python-cell#| title: Python calculation#| run: reactive#| inputs:#| scale: { type: number, label: Scale, description: Multiplier from 1 through 10., min: 1, max: 10, step: 1, value: 2 }print(scale * 10)```Python セルは Pyodide worker で実行されます。vendored package が必要な場合は packages に指定します。対応 package には numpy、pandas、matplotlib と、それらの vendored dependency が含まれます。
Haskell セルを書く
Section titled “Haskell セルを書く”Haskell セルは haskell の fenced code block で、先頭に --| metadata comment を置きます。runtime generation 時に WASI WebAssembly へ compile され、browser worker で実行されます。
```haskell--| id: sample-haskell-cell--| title: Haskell calculation--| run: reactive--| inputs:--| count: { type: integer, label: count, min: 1, max: 10, step: 1, value: 4 }import Data.List (intercalate)
let values = take count [2, 4 ..]putStrLn (intercalate ", " (map show values))```standard library module だけを使います。Haskell セルでは外部 package、packages、crates は使えません。
セルの動作を設定する
Section titled “セルの動作を設定する”主な metadata field:
id: 必須の lowercase kebab-case ページ内 cell ID。ref: 任意の安定した参照名。同じ locale の cell と見出し全体で一意にします。title: cell UI に表示される non-empty string の見出し。明示した値は前後の空白を除去し、省略時はidを使います。run:button、reactive、autorun。default はbutton。inputs: lowercase cross-language identifier から input definition への mapping。autorunでは指定できません。cases: 名前付き入力プリセットの配列。各ケースにid、label、部分上書きのinputs、任意のdescriptionを指定します。autorunでは指定できません。crates: Rust helper crate。Rust のみ。packages: Pyodide package。Python のみ。timeoutMs:1以上2147483647以下の integer で指定する millisecond timeout。default は30000。showSource: source の初期表示を決める boolean。default はtrue。outputLayout:stack(default)またはcolumns。columnsではセルの幅が十分なときにグラフと画像を同じ行に並べます。editable: 読者がローカルの Python draft を編集・実行できるかを決める boolean。Python のみ。default はtrue。setup: 本体の前に実行する同じページの Python セル ID。python.experimentalSetup: trueが必要です。
top-level ではこれらの field だけを指定できます。dependency array は重複のない空でない string で構成します。対応 input type は range、number、integer、text、textarea、checkbox、select、radio です。input field、default、constraint、option schema の正確な仕様は実行可能セルを参照してください。
integer metadata の portable domain は -2147483648 以上 2147483647 以下の signed 32-bit です。この制限は value、min、max、step に適用され、generated Rust/Haskell/Python binding に同じ正確な integer を渡します。
numeric default は input の step grid にも揃える必要があります。effective step は明示した step、または 1 です。base は min があればその値、なければ明示または default の numeric value です。不一致の default は丸めたり clamp したりせず、authoring 時に拒否されます。
ケースの id はセル内で一意の kebab-case にし、予約語 default は使えません。入力とケースの label は空でない256文字以内の文字列です。省略した入力は宣言した既定値で補完します。ケースは全入力を一度に適用し、reactive セルは一度だけ実行し、button セルは「実行」を待ちます。乱数計算の seed も通常の入力として公開し、ケースに含めてください。実行例は名前付き入力ケースを参照してください。
安定した参照でリンクする
Section titled “安定した参照でリンクする”ページの移動や見出しの変更に追従するリンクには論理名を使います。セルの動作とautorun セルは実際に参照を解決する例です。
セルの先頭の metadata block に ref を指定します。
```rust//| id: demo//| ref: solver-demo//| crates: []println!("solver ready");```見出しには、そのページの frontmatter で参照名と現在の見出し slug の mapping を指定します。
---title: ソルバーreferences: step-size: ステップ幅の選択---
## ステップ幅の選択リンクは [ソルバーのデモ](oxref:solver-demo)、参照形式なら [solver]: oxref:solver-demo と書きます。query や fragment は指定できません。参照名は ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ に一致する64文字以内の文字列にします。
名前は同じ locale のセルと見出し全体で一意にします。英語版と日本語版では同じ名前を使えます。参照元と同じ locale だけを検索し、翻訳がない場合は他言語に fallback せず error にします。
build は既存のセル ID や見出し slug を保ち、ox-ref-<name> anchor を追加します。ページやセルを移動すると参照リンクが自動的に更新されます。見出しを変更したときは、そのページの references の slug だけを更新します。見出しが重複する場合は -1 などの suffix も含めます。開発中の移動にも server の再起動なしで追従します。外部に保存したページ URL の bookmark は移動前の URL に依存します。
数式を追加する
Section titled “数式を追加する”inline math は $...$、block math は $$...$$ で書きます。
The state is $x_n \in [0, 1]$.
$$x_{n+1} = r x_n (1 - x_n)$$数式はページ表示時に KaTeX で render されます。
図を追加する
Section titled “図を追加する”Mermaid 図は mermaid の fenced block として書きます。import は不要です。
```mermaidflowchart LR MDX[MDX body] --> Build[Static build] Build --> Site[Published site]```Mermaid source は repository-owned MDX に置きます。信頼できない外部入力をそのまま Mermaid に渡さないでください。
メディアを追加する
Section titled “メディアを追加する”PNG、JPEG、PDF など処理せずに配信したい静的 file は public/media に置きます。MDX からは root-relative の /media/... URL で参照します。Astro の configured base は含めず、Oxiquill の Markdown transform に追加させます。

<iframe class="media-frame" src="/media/examples/sample.pdf" title="Sample PDF"></iframe>
[Open the PDF in a new tab](/media/examples/sample.pdf)画像には具体的な alt text を書きます。PDF は embedded frame だけでなく、直接開ける通常 link も置きます。
基準曲線・標本・不確実性を一つの図に重ねるには、Rust の emit_chart!、Python の display_chart、Haskell の displayChart から 混合 XY レイヤーを使います。独自の HTML は不要です。
Rust アイテムの共有
Section titled “Rust アイテムの共有”Rust ブロックに kind: definitions を指定し、同じページの ID を uses: [model] で参照します。定義から別の定義も参照できますが、循環参照はできません。共有するアイテムやフィールドには pub(crate) 以上の可視性を指定し、実行文は実行セルに置きます。
定義で許可されるのは id、kind、title、crates、uses、showSource のみです。入力、実行モード、ケース、テスト、タイムアウト、出力は指定できません。ヘルパークレートの依存関係は参照先から引き継がれます。ページ内の Rust 定義 に完全な例があります。