執筆ガイド

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 セルは 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 セルは 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 セルは 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。
• title: cell UI に表示される non-empty string の見出し。明示した値は前後の空白を除去し、省略時は id を使います。
• run: button、reactive、autorun。default は button。
• inputs: lowercase cross-language identifier から input definition への mapping。autorun では指定できません。
• crates: Rust helper crate。Rust のみ。
• packages: Pyodide package。Python のみ。
• timeoutMs: 1 以上 2147483647 以下の integer で指定する millisecond timeout。default は 30000。
• showSource: source の初期表示を決める boolean。default は 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 時に拒否されます。

数式を追加する

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 も置きます。