はじめに

Oxiquill には Node.js 24 以上が必要です。実行可能 cell のない static starter は Node.js と npm/pnpm だけで動き、language toolchain は document manifest がその language を使うときだけ必要です。

Project を作る

supported starter command は dependency install や Git init をせずに新しい directory を作ります。

pnpm dlx oxiquill init my-docs
cd my-docs

my-docs を省略すると current directory を初期化します。target は未作成または空でなければならず、init は non-empty directory を上書きせず force option もありません。

既存 static documentation project に Oxiquill を追加する場合:

pnpm add oxiquill@0.3.1 astro@7.2.9 @astrojs/starlight@0.41.9

または:

npm install oxiquill@0.3.1 astro@7.2.9 @astrojs/starlight@0.41.9

starter が作成していない場合は package.json に次の script を追加します。

{
  "scripts": {
    "dev": "oxiquill dev",
    "build": "oxiquill build",
    "check": "oxiquill check",
    "preview": "oxiquill preview",
    "clean": "oxiquill clean"
  }
}

Site を設定する

astro.config.mjs:

import starlight from '@astrojs/starlight';
import { defineOxiquillConfig } from 'oxiquill/astro';

export default defineOxiquillConfig({
  framework: { starlight },
  site: 'https://example.com',
  title: 'My Docs',
  sidebar: [{ label: 'Overview', items: [{ label: 'Home', slug: 'index' }] }]
});

content.config.ts:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
import { createOxiquillCollections } from 'oxiquill/content';

export const collections = createOxiquillCollections({ defineCollection, docsLoader, docsSchema });

最初の page を content/docs/index.mdx に書きます。

---
title: Home
description: Start writing with Oxiquill.
---

# Home

Write prose-first technical documentation in MDX.

source/cache/public/output path を変える前に プロジェクト設定 を確認してください。

Install と check

project で選んだ package manager を使います。

pnpm install
pnpm check

または:

npm install
npm run check

check は project config を読み、cell metadata を検証し、必要な runtime/asset だけを生成して Astro type を同期し、Astro/MDX/TypeScript diagnostic を報告します。

Develop、build、preview

pnpm dev

prose、通常 code block、math、Mermaid、media は Astro HMR を使います。cell/helper source の変更は対応 manifest/runtime を再生成します。Ctrl-C で server を停止します。

production site を作って確認します。

pnpm build
pnpm preview

build は strict generation/check 後に Astro の static outDir（通常 dist）を書きます。preview は既存 output を serve するだけで、production web server、TLS、domain、reverse proxy の代わりではありません。

Optional language prerequisite

Content	Author/build prerequisite	Reader prerequisite
Static MDX、math、Mermaid、media	Node.js 24+ と npm/pnpm	supported browser
Python cell	generation 時の network または verified offline Pyodide cache	supported browser。asset は site が配信
Rust cell	pinned Rust toolchain、wasm32-unknown-unknown、wasm-pack	supported browser
Haskell cell	Linux/macOS と wasm32-wasi-ghc 9.14	任意 desktop OS の supported browser

repository maintainer は full validation suite 用に cargo-llvm-cov と Playwright browser も必要です。

生成物

Oxiquill は .oxiquill/**、public/oxiquill/**、Astro type/cache output、dist/** を所有します。ignore し、CLI command から再生成してください。verified download は別の .cache/oxiquill/downloads/v1/** に置かれ、starter はこの directory を ignore し、oxiquill clean は後の online/offline 再生成用に保持します。matching manifest、fingerprint、runtime input が同一でない限り、config 間で生成物を copy しないでください。

続けて 執筆ガイド、CLI reference、トラブルシューティング を参照してください。