プロジェクト設定

Oxiquill は一つの project config を読み込み、development、check、generation、build、test、clean のすべてで同じ resolved path を使います。すべての command に同じ --config を渡す場合を除き、astro.config.mjs は project root に置きます。

最小構成

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 });

defineOxiquillConfig() は static output、Oxiquill の Markdown transform、Preact、Starlight を設定済みの Astro config を返します。

設定 field

Field	意味
title, description, sidebar	対応する Starlight setting の shorthand。
desktopTableOfContentsToggle	永続化される desktop 目次 control を有効にします。default は true です。
starlight	その他の Starlight option。同じ setting はこちらが shorthand より優先されます。
framework.starlight	@astrojs/starlight から import する必須の Starlight integration factory。
framework.preact	組み込み用途向けの optional Preact integration-factory override。
integrations	Oxiquill、Preact、Starlight の後に追加する Astro integration。
markdown	対応する Astro Markdown setting/plugin。Oxiquill 必須 plugin が先に動きます。
vite	追加の Vite setting。必須 alias、dedupe、worker plugin、filesystem access は保持されます。
paths	下記の source/cache/generated/public path。
python	Pyodide download の preload、offline と optional packageMirror。
その他の Astro field	Astro に渡されます。Oxiquill の output は常に static です。

Astro config を手動で組み立てる場合だけ oxiquillIntegration() を使います。受け取る option は base、markdown、paths、python、vite で、Preact と Starlight は caller が追加します。

interactive cell、Mermaid、KaTeX、public-asset base path には Oxiquill の unified pipeline が必要なため、markdown.processor は Oxiquill が管理します。custom processor は未対応で TypeError になり、代わりに対応する Markdown field と追加の remarkPlugins / rehypePlugins を設定します。

Desktop の目次

目次があるページでは、Starlight の mobile disclosure を保ったまま、Oxiquill が desktop 用の折りたたみ・展開 button を追加します。目次を折りたたむと右列全体がなくなり、main content が空いた幅を使います。設定は現在の browser tab の sessionStorage に oxiquill-table-of-contents-collapsed key で保存され、左 sidebar の設定とは独立しています。

Starlight の常時表示 desktop 目次を維持するには desktopTableOfContentsToggle: false を設定します。

export default defineOxiquillConfig({
  desktopTableOfContentsToggle: false,
  framework: { starlight },
  title: 'My Docs'
});

tableOfContents: false のページと splash page には control を出力しません。starlight.components に consumer が指定した entry は Oxiquill の default より優先され、PageFrame、TableOfContents、TwoColumnContent の override も保持されます。

Path field

Field	Default	解決基準
workspaceRoot	project root	current project/config root
frameworkRoot	install 済み oxiquill package	absolute/package location
docsDir	content/docs	workspaceRoot
cratesDir	crates	workspaceRoot
publicDir	public	workspaceRoot
cacheDir	.oxiquill	workspaceRoot
downloadCacheDir	.cache/oxiquill/downloads/v1	workspaceRoot
generatedDir	generated	cacheDir
rustCellsDir	rust-cells	cacheDir
haskellCellsDir	haskell-cells	cacheDir
publicAssetsDir	oxiquill	publicDir
rustWasmPublicDir	rust-wasm	publicAssetsDir
haskellWasmPublicDir	haskell-wasm	publicAssetsDir
pyodidePublicDir	pyodide	publicAssetsDir
licensesPublicDir	licenses	publicAssetsDir

各 path は relative string、absolute string、file: URL を受け取ります。nested relative path は偶然の working directory ではなく、表に示した parent から解決されます。

Astro の root、publicDir、outDir、cacheDir と Oxiquill の path setting が同じ directory を示す場合、正規化後の location が一致しなければなりません。明示値の競合は error になり、Oxiquill が黙って一方を選ぶことはありません。すべての CLI command は file の読み書きや clean より前にこの config を解決します。

Python download

export default defineOxiquillConfig({
  python: {
    preload: false,
    offline: process.env.OXIQUILL_OFFLINE === '1',
    packageMirror: new URL('https://packages.example/pyodide/')
  },
  paths: {
    downloadCacheDir: new URL('./.cache/verified-downloads/', import.meta.url)
  }
});

python.offline の default は false です。python.packageMirror は string または URL を受け取り、lockfile の integrity check を変えずに package download base だけを変更します。paths.downloadCacheDir も string または URL を受け取ります。公開 type の OxiquillPythonOptions と OxiquillPathOptions がこれらの field を定義します。

優先順位と merge

1. --config <path> が config file を選び、省略時は Astro 標準の探索を使います。
2. 明示した project setting が default より優先されます。
3. starlight.title、starlight.description、starlight.sidebar が shorthand field より優先されます。
4. Consumer の Markdown、Vite、CSS、component、integration の追加は Oxiquill 必須 entry の後に保持されます。
5. path の競合、Oxiquill integration の欠落・重複、config 読み込み失敗は generation/clean より前に失敗します。

Clean の ownership と安全性

oxiquill clean が再帰削除する resolved root は cacheDir、Astro の outDir、publicAssetsDir の3つだけです。downloadCacheDir は削除しません。default の verified download cache .cache/oxiquill/downloads/v1 は clean 後も残り、次の generation で再利用できます。

default の .oxiquill、dist、public/oxiquill は生成専用 location として予約され、ownership marker がなくても clean できます。custom cleanup root では、対応する generation/build lifecycle が存在しないか空の directory を claim し、.oxiquill-ownership.json を書きます。matching marker のない既存の non-empty custom directory を生成物とは推測しません。marker を手動で作成・編集しないでください。

再帰削除する root はすべて workspaceRoot 内になければなりません。cleanup root 同士は disjoint であり、docsDir、cratesDir、publicDir、frameworkRoot、選択した Astro config、認識済み project config/manifest/lock file、persistent download cache、.git や node_modules など検出した VCS/package-installation state とも重複できません。generated child role 同士の重複も拒否します。authored/generated の包含で許可する唯一の例外は、publicAssetsDir が publicDir の厳密な子である関係です。publicDir と同一にはできず、別の authored public subtree の内側にも置けません。

Oxiquill は比較・削除前に既存 path と symlink ancestor を canonicalize します。clean は最初の再帰削除より前に全 root と全 ownership marker を検証します。unsafe/unowned root が一つでもあれば何も削除せず、diagnostic に field、absolute resolved path、conflicting path role、corrective action を示します。

Runtime fingerprint

runtime fingerprint には machine-local path ではなく semantic build input が入ります。Python fingerprint は Pyodide version、lockfile SHA-256、検証済み core-file hash、選択 package metadata、requested package set を含みます。Haskell build fingerprint は cell、generated source、supported compiler-version prefix、compiler が報告した正確な version（または unavailable state）を含みます。Haskell compiler command、executable path、diagnostic text は除外されるため、同等 toolchain の移動だけでは rebuild せず、reported version や supported-version policy の変更では rebuild します。

Base path と public asset

subpath 配下へ公開するときは Astro の base を設定します。Oxiquill は interactive-cell manifest、language runtime、diagram、/media/... reference に適用します。base 自体が /media または同じ prefix で始まる場合も、authoring ではすべての public URL を root-relative の /media/... 形式で記述します。configured base は手動で追加せず、通常の Markdown pass に authored URL を prefix させます。

生成 runtime は .oxiquill と public/oxiquill、verified download cache は .cache/oxiquill/downloads/v1、最終 static site は Astro の outDir（通常 dist）に置かれます。生成 directory と ownership marker を直接編集しないでください。download cache は build や output 再生成をまたいで保持できますが、file は利用前に毎回検証されます。

生成 directory を変更するときは、resolved cache、helper-crate target、output、public-asset path に合わせて tsconfig.json の exclusion も更新します。そうしないと **/* のような広い include により、Astro/TypeScript が Pyodide などの生成 JavaScript を output ではなく source として解析することがあります。

python.preload の default は false です。有効にすると Python cell がある page の DOM ready 時に準備を始めます。詳細は Python runtime asset を参照してください。