Getting Started

Oxiquill requires Node.js 24 or newer. A static starter with no executable cells needs only Node.js and npm or pnpm; language toolchains become prerequisites only when the document manifest uses that language.

Create a Project

The supported starter command creates a new directory without installing dependencies or initializing Git:

pnpm dlx oxiquill init my-docs
cd my-docs

Omit my-docs to initialize the current directory. The target must not exist or must be empty; init never overwrites a non-empty directory and has no force option.

You can also install Oxiquill into an existing static documentation project:

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

or:

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

Add these scripts to package.json if the starter did not create them:

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

Configure the Site

Create 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' }] }]
});

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

Write the first page at content/docs/index.mdx:

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

# Home

Write prose-first technical documentation in MDX.

See Project Configuration before changing source, cache, public, or output paths.

Install and Check

Use the package manager selected for the project:

pnpm install
pnpm check

or:

npm install
npm run check

check loads the project config, validates cell metadata, generates only required runtimes/assets, synchronizes Astro types, and reports Astro/MDX/TypeScript diagnostics.

Develop, Build, and Preview

pnpm dev

Prose, ordinary code blocks, math, Mermaid, and media use Astro HMR. Cell or helper-source changes regenerate the corresponding manifest/runtime. Stop the server with Ctrl-C.

Create and inspect the production site:

pnpm build
pnpm preview

build runs strict generation and checks before writing Astro’s static outDir, normally dist. preview serves that existing output; it does not replace a production web server, TLS, domain, or reverse-proxy configuration.

Optional Language Prerequisites

Content	Author/build prerequisites	Reader prerequisites
Static MDX, math, Mermaid, media	Node.js 24+ and npm/pnpm	Supported browser
Python cells	Network or verified offline Pyodide cache during generation	Supported browser; assets are served by the site
Rust cells	Pinned Rust toolchain, wasm32-unknown-unknown, wasm-pack	Supported browser
Haskell cells	Linux/macOS and wasm32-wasi-ghc 9.14	Supported browser on any desktop OS

Repository maintainers additionally need cargo-llvm-cov and Playwright browsers for the full validation suite.

Generated Output

Oxiquill owns .oxiquill/**, public/oxiquill/**, Astro’s type/cache output, and dist/**. Keep them ignored and regenerate them through CLI commands. Verified downloads live separately under .cache/oxiquill/downloads/v1/**; the starter ignores this directory, and oxiquill clean preserves it for later online or offline regeneration. Do not copy generated output between configurations unless the matching manifest, fingerprints, and runtime inputs are unchanged.

Continue with the Authoring Guide, CLI reference, and Troubleshooting.