Project Configuration
Oxiquill loads one project configuration and uses the same resolved paths for development, checks, generation, builds, tests, and cleanup. Keep astro.config.mjs at the project root unless every command receives the same --config option.
Minimal Configuration
Section titled “Minimal Configuration”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' }] }]});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() returns an Astro configuration with static output, Oxiquill’s Markdown transforms, Preact, and Starlight already installed.
Configuration Fields
Section titled “Configuration Fields”| Field | Meaning |
|---|---|
title, description, sidebar | Shorthand for the corresponding Starlight settings. |
desktopTableOfContentsToggle | Enables the persistent desktop table-of-contents control. Defaults to true. |
starlight | Any other Starlight option. A value here overrides the matching shorthand. |
framework.starlight | Required Starlight integration factory imported from @astrojs/starlight. |
framework.preact | Optional Preact integration-factory override for embedded/framework consumers. |
integrations | Additional Astro integrations, appended after Oxiquill, Preact, and Starlight. |
markdown | Supported Astro Markdown settings and plugins. Oxiquill’s required plugins run first. |
vite | Additional Vite settings. Oxiquill preserves required aliases, deduplication, worker plugins, and filesystem access. |
paths | Oxiquill-owned source, cache, generated, and public paths described below. |
python | Pyodide download behavior: preload, offline, and the optional packageMirror. |
rust | Rust module grouping: page (default), directory, site, or a function returning a group key. |
missingTranslations | fallback (default) keeps Starlight’s fallback pages; omit generates and links only translated pages. See Multilingual Sites. |
docRedirects | Redirects whose destinations are base-relative documentation paths. See Document Redirects. |
| Other Astro fields | Passed through to Astro. Oxiquill always produces static output. |
Use oxiquillIntegration() only when composing an Astro configuration manually. It accepts base, markdown, paths, python, rust, and vite; the caller is then responsible for adding Preact and Starlight. missingTranslations and docRedirects also configure Starlight and Astro, so only defineOxiquillConfig() accepts them.
Oxiquill owns markdown.processor because interactive cells, Mermaid, KaTeX, and public-asset base paths require its unified pipeline. A custom processor is not supported and throws a TypeError; configure supported Markdown fields and append remarkPlugins or rehypePlugins instead.
Desktop Table of Contents
Section titled “Desktop Table of Contents”On pages with a table of contents, Oxiquill adds a desktop collapse/expand button while preserving Starlight’s mobile disclosure. Collapsing the table of contents removes the complete right column and lets the main content use the released width. The preference is stored for the current browser tab in sessionStorage under oxiquill-table-of-contents-collapsed; it is independent from the left-sidebar preference.
Set desktopTableOfContentsToggle: false to retain Starlight’s always-visible desktop table of contents:
export default defineOxiquillConfig({ desktopTableOfContentsToggle: false, framework: { starlight }, title: 'My Docs'});The control is not rendered for tableOfContents: false or splash pages. Consumer entries in starlight.components take precedence over Oxiquill’s defaults, including PageFrame, TableOfContents, and TwoColumnContent overrides.
The table-of-contents column is --oq-toc-width wide. The default, clamp(14rem, 18vw, var(--sl-sidebar-width)), narrows the column on small desktops so the content keeps more of its measure and reaches the sidebar width on large screens. Wider screens divide the remaining space between the content and the table of contents, keeping both near the center. Long entries wrap inside the column, and the toggle sits on the column border at every width. Set the property on :root to choose a fixed width:
:root { --oq-toc-width: 16rem;}The property applies to Oxiquill’s toggle layout. With desktopTableOfContentsToggle: false, Starlight’s own column sizing remains.
Content Width
Section titled “Content Width”Collapsing the left sidebar adds --sl-sidebar-width to the current --sl-content-width, and collapsing the table of contents adds its column width, --oq-toc-width. The default reading measure stays the same when both columns are expanded.
To customize the measure and column size, register a stylesheet with starlight.customCss, for example starlight: { customCss: ['./styles/custom.css'] }. It loads after Oxiquill’s CSS. Set both properties on :root:
:root { --sl-content-width: 80rem; --sl-sidebar-width: 20rem;}Fluid values such as --sl-content-width: 100% stay fluid through every toggle state. Starlight gives pages without a sidebar, including splash pages, a separate base measure. Override that measure with :root:not([data-has-sidebar]) { --sl-content-width: 100%; } when needed.
A page can drop the reading measure without changing the rest of the site. Set contentWidth: full in its frontmatter; the content then fills the space between the navigation columns, and both toggles keep working. Use it for wide reference tables or several charts, and keep prose pages at the default measure.
---title: API IndexcontentWidth: full---createOxiquillCollections() adds contentWidth (default or full) to the docs schema. A project with its own docs schema needs the same optional field.
A custom PageFrame keeps table-of-contents widening through Oxiquill’s TwoColumnContent, but sidebar widening requires Oxiquill’s PageFrame.
Multilingual Sites
Section titled “Multilingual Sites”Starlight fills untranslated pages with default-locale content, called fallback pages, so every locale has every route. Set missingTranslations: 'omit' when a locale should contain only translated pages:
export default defineOxiquillConfig({ framework: { starlight }, missingTranslations: 'omit', starlight: { defaultLocale: 'root', locales: { root: { label: 'English', lang: 'en' }, ja: { label: '日本語', lang: 'ja' } } }});Oxiquill removes fallback routes before Astro generates pages, so they produce no HTML, sitemap entry, or search record, and the development server answers them with 404. Navigation follows the generated pages:
- The language select lists only locales that have the current page and is hidden when no other locale does.
- The sidebar drops links to untranslated pages and the groups that become empty.
- Previous and next links skip untranslated pages;
prevandnextfrontmatter still applies. hreflangalternates and the site title link point only at generated pages.
The default, 'fallback', keeps Starlight’s behavior. Omit mode requires prerendered Starlight pages, which is the default. It adds Oxiquill’s LanguageSelect component and a route middleware: a LanguageSelect entry in starlight.components takes precedence, and entries in starlight.routeMiddleware run after Oxiquill’s and see the filtered navigation.
Document Redirects
Section titled “Document Redirects”Astro matches redirects sources below base, but it leaves a destination unprefixed when it cannot see a matching route. Pages served by Starlight are such destinations. Use docRedirects for moved documentation pages. Each destination is a base-relative documentation path, and Oxiquill adds base:
export default defineOxiquillConfig({ base: '/docs/', docRedirects: { '/guides/setup/': '/guides/getting-started/', '/ja/old-guide/': { status: 301, destination: '/ja/guide/' } }, framework: { starlight }});Here /docs/guides/setup/ redirects to /docs/guides/getting-started/. A destination must start with a single / and cannot contain route parameters. The build fails when a destination produces no page, for example after a typo or when missingTranslations: 'omit' leaves the target untranslated. Keep external and other non-documentation destinations in Astro’s redirects; a source cannot appear in both.
Japanese Typography
Section titled “Japanese Typography”oxiquill/styles/japanese.css styles content whose language is Japanese (lang="ja" or a ja- tag). It applies strict line breaking, so small kana and prolonged sound marks do not start a line, and sets line height and letter spacing for prose and headings. Content in other languages is unaffected, including an untranslated fallback page under a Japanese route. Add it to starlight.customCss:
starlight: { customCss: ['oxiquill/styles/japanese.css', './styles/custom.css'];}To tune the preset, set these properties on :root in a stylesheet listed after it:
| Property | Default | Applies to |
|---|---|---|
--oq-ja-line-height | 1.9 | Paragraphs, list items, definitions, quotations, table cells, and captions |
--oq-ja-letter-spacing | normal | The same prose elements |
--oq-ja-heading-line-height | 1.4 | The page title and headings |
--oq-ja-heading-letter-spacing | 0.01em | The page title and headings |
--oq-ja-word-break | normal | Content; auto-phrase breaks at phrase boundaries in supporting browsers |
Path Fields
Section titled “Path Fields”| Field | Default | Resolution base |
|---|---|---|
workspaceRoot | project root | current project/config root |
frameworkRoot | installed 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 |
Every path accepts a relative string, an absolute string, or a file: URL. Nested relative paths resolve against the parent shown in the table, not against the process’s incidental working directory.
Astro’s root, publicDir, outDir, and cacheDir and Oxiquill’s explicit path settings must normalize to the same locations when they describe the same directory. Conflicting explicit values are errors; Oxiquill never silently chooses one. All CLI commands load this resolved configuration before reading, writing, or cleaning files.
Generated Rust Assets
Section titled “Generated Rust Assets”Runnable manifests in .oxiquill/generated/cells.json include a version 1 rust registry. Each Rust cell belongs to exactly one module, and each module is one Rust module group named <mode>-<hash>, such as page-3f2a9c41d07b5e68.
Each module records its build fingerprint, JavaScript glue URL, Wasm URL, Wasm SHA-384 integrity, byte length, and cell IDs. Files under public/oxiquill/rust-wasm/ use names such as page-3f2a9c41d07b5e68-<hash>.js and page-3f2a9c41d07b5e68-<hash>.wasm. Their content-addressed URLs are immutable. The registry stores paths relative to publicDir; Astro resolves browser URLs under its configured base, including custom runtime directories.
The Rust worker loads a module when one of its cells first runs and verifies Wasm integrity while fetching it. Text-only and Python-only pages fetch no Rust module assets. Development updates invalidate changed module fingerprints; cancellation and timeout still reset the whole Rust worker. Generation publishes the new registry before removing obsolete registered module assets.
Source-only docgen does not compile Rust. Run oxiquill docgen --wasm dev or build the site to produce runnable module assets. Do not edit generated manifests or assets manually.
Python Downloads
Section titled “Python Downloads”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 defaults to false. python.packageMirror accepts a string or URL and changes the package download base without changing lockfile integrity checks. paths.downloadCacheDir also accepts a string or URL. The exported OxiquillPythonOptions and OxiquillPathOptions types describe these public fields.
Precedence and Merging
Section titled “Precedence and Merging”--config <path>selects the config file; otherwise Astro’s normal config discovery applies.- Explicit project settings override defaults.
starlight.title,starlight.description, andstarlight.sidebaroverride the shorthand fields.- Consumer Markdown, Vite, CSS, component, and integration additions are retained after Oxiquill’s required entries.
- A conflicting path, missing Oxiquill integration, multiple Oxiquill integrations, or an unreadable config fails before generation or cleanup.
Cleanup Ownership and Safety
Section titled “Cleanup Ownership and Safety”oxiquill clean recursively removes exactly three resolved roots: cacheDir, Astro’s outDir, and publicAssetsDir. It does not remove downloadCacheDir; the default verified download cache at .cache/oxiquill/downloads/v1 persists across clean and can be reused by later generation.
The exact default roots .oxiquill, dist, and public/oxiquill are reserved generated locations and may be cleaned without an ownership marker. For a custom cleanup root, the corresponding generation or build lifecycle writes .oxiquill-ownership.json after claiming a missing or empty directory. A pre-existing non-empty custom directory without the matching marker is never inferred to be generated output. Do not create or edit the marker manually.
Every recursively deleted root must stay inside workspaceRoot. Cleanup roots must be disjoint from one another and from docsDir, cratesDir, publicDir, frameworkRoot, the selected Astro config, recognized project config/manifest/lock files, the persistent download cache, and discovered VCS or package-installation state such as .git and node_modules. Generated child roles must also be disjoint from their siblings. The only authored/generated containment exception is a strict publicAssetsDir child below publicDir; it cannot equal publicDir or sit below another authored public subtree.
Oxiquill canonicalizes existing paths and symlinked ancestors before comparing or deleting them. Clean validates every root and every ownership marker before its first recursive deletion. If one root is unsafe or unowned, no root is removed; the diagnostic names the field, absolute resolved path, conflicting path role, and corrective action.
Runtime Fingerprints
Section titled “Runtime Fingerprints”Runtime fingerprints contain semantic build inputs rather than machine-local paths. Python fingerprints include the Pyodide version, lockfile SHA-256, verified core-file hashes, selected package metadata, and requested package set. Haskell build fingerprints include the cells, generated source, supported compiler-version prefix, and the compiler’s exact reported version (or its unavailable state). The Haskell compiler command, executable path, and diagnostic text are excluded, so moving an equivalent toolchain does not force a rebuild; changing its reported version or supported-version policy does.
Rust and Haskell build fingerprints also include the installed generator’s content hash and package identity. This detects codegen, build-flag, postprocessing, staging, and runtime-data changes even when a workspace package version stays unchanged. Rust additionally hashes RUSTFLAGS, CARGO_ENCODED_RUSTFLAGS, every CARGO_PROFILE_*, CARGO_BUILD_*, and CARGO_TARGET_* variable, every BINARYEN_* variable, and the workspace’s .cargo/config and .cargo/config.toml. CARGO_BUILD_JOBS and BINARYEN_CORES only choose parallelism and are excluded, as are unrelated environment variables. Each module also fingerprints its resolved dependency closure and the helper manifests that take part in the workspace build. Artifact mode is recorded: production output may satisfy a dev request, while dev output must rebuild for production.
Before reusing published Rust, Haskell, or Python files, Oxiquill checks their recorded byte sizes and SHA-256 digests. Development syncs check content-addressed Rust module files and generated module sources by existence and size, so an unchanged sync reads no module bytes; production builds always verify SHA-256. Missing, edited, or truncated files trigger regeneration. Older runtime state without integrity records is regenerated automatically.
Compiler Caches
Section titled “Compiler Caches”Compiler caches live below the configured cacheDir: build-cache/rust-target for Cargo and build-cache/haskell/<mode>-<ghc-version> for Haskell. They survive runtime staging and failed compilation. Haskell uses stable cached source paths and preserves unchanged source timestamps so GHC can reuse module objects; mode and exact compiler version select separate caches. Cargo manages dependency recompilation itself.
Release Rust builds cache wasm-opt -O results in build-cache/wasm-opt. The optimizer is wasm-opt from PATH or the verified Binaryen 117 download. The cache keys the input bytes and size, optimizer version and executable hash, optimization arguments, schema version, and sorted BINARYEN_* environment variables except BINARYEN_CORES. Changing the optimizer invalidates Rust build reuse. Dev builds skip optimization. Hits verify content integrity and copy bytes into the build stage. Corrupt entries regenerate automatically. The cache retains at least the 16 most recently used results, and twice the number of Rust modules for larger sites; it normally survives failed builds. oxiquill clean or pnpm build:clean clears it while preserving verified downloads.
Oxiquill passes the Cargo target directory to every Cargo invocation. An explicit CARGO_TARGET_DIR takes precedence and remains user-owned; clean does not delete an external target directory. Compiler caches are separate from published output and the verified download cache. oxiquill clean removes Oxiquill-owned compiler caches but preserves verified downloads.
Cargo configuration outside the workspace root, including ancestor .cargo files, $CARGO_HOME/config*, and files referenced by configuration, is not fingerprinted. After changing these inputs, run the repository’s pnpm build:clean, or oxiquill clean followed by oxiquill build in a consumer project.
Base Paths and Public Assets
Section titled “Base Paths and Public Assets”Set Astro’s base when publishing below a subpath. Oxiquill applies it to interactive-cell manifests, language runtimes, diagrams, and /media/... references. Keep every authored public URL in root-relative /media/... form, even when base itself is /media or starts the same way. Do not add the configured base manually; the normal Markdown pass prefixes the authored URL. Redirects to documentation pages use docRedirects, which also adds the base.
Generated runtime files belong under .oxiquill and public/oxiquill; the verified download cache belongs under .cache/oxiquill/downloads/v1; and the final static site belongs under Astro’s outDir (normally dist). Generated directories and their ownership markers must not be edited directly. The download cache may be retained across builds and reconstructed outputs, but its files are verified before every use.
When you customize generated directories, update tsconfig.json exclusions to the resolved cache, helper-crate target, output, and public-asset paths. Otherwise a broad include such as **/* can make Astro/TypeScript analyze generated JavaScript such as Pyodide instead of treating it as output.
python.preload defaults to false. Enable it to prepare Python at DOM readiness on pages containing Python cells. See Python Runtime Assets.
python.additionalPackages accepts package names mapped to { version, license, licenseFiles } records. It extends the built-in allowlist using the installed Pyodide lock. Only packages required by cells are distributed. See Additional Packages for dependency notices, integrity checks, and an example.
python.experimentalSetup defaults to false. Enable it to allow page-local Python setup references that execute afresh before each cell. See Experimental Setup.
Rust Module Groups
Section titled “Rust Module Groups”rust.grouping decides which pages share a compiled Rust module. Every grouping uses the same pipeline: one Cargo workspace below paths.rustCellsDir, one member crate per group, and one content-addressed Wasm module per group. Pages without Rust cells create no module. A page never spans modules, so page-local definitions, uses, exports, and dependsOn always stay within one crate.
| Value | Group key | Choose it when |
|---|---|---|
'page' (default) | The page path | Most sites and large books: an edit rebuilds one page’s module, and readers download only the modules of the pages they use. |
'directory' | The page’s parent directory | Readers work through chapters section by section and the chapter’s pages share helpers; fewer, larger modules reduce per-module overhead. |
'site' | One key for the whole site | Many small pages that are read together: one module is downloaded once and cached, but every Rust edit rebuilds it. |
({ path }) => string | The returned string | Any other partition, such as one module per top-level part of a book. |
Paths are POSIX paths relative to paths.docsDir, including any locale prefix, so guides/a.mdx and ja/guides/a.mdx never share a directory group. Keys are normalized to Unicode NFC, so checkouts on file systems that store decomposed names produce the same modules. A grouping function must be pure. It receives a frozen { path }, runs once per page with Rust cells in each generation, and must synchronously return a non-empty, well-formed string of at most 256 characters; any other result fails generation and names the page. The function lives in the project configuration, so the CLI, Astro, and the development runtime use it alike, and saving the configuration file regroups the development runtime.
export default defineOxiquillConfig({ framework: { starlight }, title: 'My Book', // One module per top-level part, such as `part-1/...` or `ja/part-1/...`. rust: { grouping: ({ path }) => path .split('/') .slice(0, path.startsWith('ja/') ? 2 : 1) .join('/') }});Module ids combine the mode with a 16-character digest of the key (page-…, directory-…, site-…, or custom-…). They stay lowercase on case-insensitive file systems and keep Cargo’s target paths short on Windows. After rust.grouping changes, modules whose id, pages, and sources are unchanged are kept.
Each build compiles only modules whose sources, helper closure, resolved dependencies, toolchain, or build options changed. Cargo compiles every stale module in one invocation and shares dependencies in build-cache/rust-target. As each module finishes, wasm-bindgen and, for production, wasm-opt run in a bounded pool sized by a positive CARGO_BUILD_JOBS or the available CPUs. Unless BINARYEN_CORES is set, wasm-opt divides the CPUs among the modules optimized at the same time. Output does not depend on scheduling: clean builds are byte-identical for every pool size. Use oxiquill build --explain to inspect the plan.
Readers download only the modules needed by the cells they run. Shared dependencies are compiled once but are linked into every module that needs them, so total download and storage bytes grow with the number of modules.
A production build fails and publishes nothing when any module fails. The oxiquill dev runtime publishes every module that builds: a failing module keeps its last working build, its pages keep their previous Rust cells and show the compiler errors, and it is not recompiled until its inputs change. One-shot commands such as oxiquill docgen --wasm dev fail without publishing instead.
Rust generation requires Cargo and the wasm32-unknown-unknown target. Oxiquill uses a wasm-bindgen CLI matching the pinned runtime crate from PATH, or downloads the official host release, verifies its pinned SHA-256, and caches it under paths.downloadCacheDir; a mismatching PATH binary is not used. Production optimization similarly uses wasm-opt from PATH or a verified Binaryen 117 release with -O. Archive extraction requires tar. Failed verification or an unsupported host reports the expected tool version and cache path; installing the matching tool on PATH is an alternative.
The generated workspace lock starts from the runtime’s exact pins and from the normal and build dependency versions locked by helper workspaces; helper dev-dependencies are ignored. Cargo resolves this seed once whenever the workspace’s dependencies change, including edits to a helper’s normal or build dependencies, reaching the network only for packages that are not cached locally, and every build then uses --locked. See Troubleshooting if resolution fails.
Generated module crates have stable source paths below paths.rustCellsDir/modules. Removing or regrouping pages prunes obsolete module sources and assets after publication, and outputs of earlier single-crate or per-page layouts are replaced on the next generation without oxiquill clean. oxiquill clean removes generated and compiler outputs while retaining verified tool downloads.