Oxiquill

Oxiquill は、技術ノートを Astro Starlight の静的サイトとして公開します。1つのノートに、本文、Rust/Wasm セル、Python/Pyodide セル、Haskell/WASI セル、数式、Mermaid 図、画像、PDF、表、グラフ、JSON、sandboxed HTML 出力をまとめられます。

執筆モデルは Markdown に近い形にしています。MDX ページを追加し、実行可能セルは先頭 metadata comment で説明し、build が browser runtime を生成します。英語ページは content/docs、日本語ページは同じ route で content/docs/ja に置きます。

想定する用途

Oxiquill は、説明と実行結果を同じページに置きたいドキュメントに向いています。

短い Rust、Python、Haskell の実験を含む学習ノート。
数式、パラメータ、表、グラフが必要な数値計算やデータのノート。
静的サイトとして公開しながら interactive example を載せたいプロジェクト文書。
英語と日本語で同じ構成を保ちたい多言語ドキュメント。

機能概要

Rust セルをビルド時に WebAssembly 化し、ブラウザで実行します。
Python セルは Pyodide worker で実行し、numpy、pandas、matplotlib などの vendored package を読み込めます。
Haskell セルをビルド時に WASI WebAssembly 化し、standard library code をブラウザで実行します。
セル metadata から入力 UI、実行方法、timeout、source 表示を生成します。
text、JSON、table、chart、image、sandboxed HTML のリッチ出力を表示します。
KaTeX でインライン数式とブロック数式を表示します。
fenced mermaid code block から Mermaid 図を表示します。
静的メディアは public/media から配信し、/media/... URL で参照します。
crates/* 配下の任意の Rust helper crate を MDX セルから再利用できます。

プロジェクト構成

content/docs/
  index.mdx
  guides/
    getting-started.mdx
    authoring.mdx
    templates.mdx
    validation.mdx
  features/
    interactive-cells.mdx
    rich-output.mdx
    math.mdx
    diagrams.mdx
    media.mdx
  samples/
    rust-ownership.mdx
    logistic-map.mdx
    haskell-series.mdx
  ja/
    index.mdx
    guides/
    features/
    samples/

生成 runtime は .oxiquill/generated、.oxiquill/rust-cells、.oxiquill/haskell-cells、public/oxiquill/pyodide、public/oxiquill/rust-wasm、public/oxiquill/haskell-wasm、public/oxiquill/licenses、dist に出力されます。生成物を直接編集せず、pnpm docgen、pnpm wasm:dev、pnpm wasm:build、pnpm check、pnpm build で再生成してください。

最初に読むページ

はじめには、install、local preview、build、static preview を説明します。
執筆ガイドは、ページ構成、多言語化、セル metadata、メディア、図の書き方を説明します。
実行可能セルは、Rust/Python/Haskell の実行、入力、run mode、helper crate、package、source 表示を説明します。
リッチ出力は、Rust/Python セルから出せる出力 artifact をまとめます。
テンプレートは、よく使う MDX ノートのひな形です。
ライセンスは、Oxiquill の dual license と各サイトに生成される notice を説明します。
サンプルノートは、Oxiquill の機能を文脈のある完成ページとして示します。