コンテンツにスキップ

執筆ガイド

Oxiquill のページは MDX file です。ページは通常の文章ノートにも、実行可能な計算ノートにも、メディア付きの説明にも、その組み合わせにもできます。

各ページは Starlight frontmatter から始めます。title はページ見出しと sidebar label に使われます。description は metadata と検索結果に使われます。

---
title: Page title
description: 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: 完成したサンプルノート。

最初に、そのページで読者が何をできるようになるかを書き、その後で例に進みます。見出しで目的、構文、動作を分けます。サンプルセルはテスト、スクリーンショット、読者の表示が安定するように deterministic にします。

日本語翻訳は英語版と同じ route と大まかな構成を保ちます。一字一句同じ訳である必要はありませんが、同じ動作と例を扱います。

通常のページには Starlight の目次が表示されます。desktop では右列を折りたたむことができ、Oxiquill は現在の browser tab でその選択を記憶します。mobile では Starlight の既存 disclosure をそのまま使います。

目次も desktop control も不要なページでは、frontmatter に tableOfContents: false を指定します。Starlight の splash page でも両方が自動的に省略されます。このページ単位の設定は、desktop collapse control だけを有効・無効にする project-wide の desktopTableOfContentsToggle option とは別です。

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 セルは 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 セルは 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 は使えません。

主な 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 も通常の入力として公開し、ケースに含めてください。実行例は名前付き入力ケースを参照してください。

ページの移動や見出しの変更に追従するリンクには論理名を使います。セルの動作と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 に依存します。

inline math は $...$、block math は $$...$$ で書きます。

The state is $x_n \in [0, 1]$.
$$
x_{n+1} = r x_n (1 - x_n)
$$

数式はページ表示時に KaTeX で render されます。

Mermaid 図は mermaid の fenced block として書きます。import は不要です。

```mermaid
flowchart LR
MDX[MDX body] --> Build[Static build]
Build --> Site[Published site]
```

Mermaid source は repository-owned MDX に置きます。信頼できない外部入力をそのまま Mermaid に渡さないでください。

PNG、JPEG、PDF など処理せずに配信したい静的 file は public/media に置きます。MDX からは root-relative の /media/... URL で参照します。Astro の configured base は含めず、Oxiquill の Markdown transform に追加させます。

![Sample image](/media/examples/sample.png)
<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 ブロックに kind: definitions を指定し、同じページの ID を uses: [model] で参照します。定義から別の定義も参照できますが、循環参照はできません。共有するアイテムやフィールドには pub(crate) 以上の可視性を指定し、実行文は実行セルに置きます。

定義で許可されるのは id、kind、title、crates、uses、showSource のみです。入力、実行モード、ケース、テスト、タイムアウト、出力は指定できません。ヘルパークレートの依存関係は参照先から引き継がれます。ページ内の Rust 定義 に完全な例があります。