Development Setup#

This page is for contributors and for anyone building Ox Content itself from source.

If you just want to use the plugin or APIs, go back to Getting Started.

Prerequisites#

Before you begin, ensure you have the following installed:

Requirement	Version	Installation
Rust	1.95+	Provided by `nix develop` (pinned in `rust-toolchain.toml`) or rustup.rs
Node.js	26+	Provided by `nix develop` or managed via `devEngines.runtime` in `package.json`
Vite+	Latest	Available as `vp` inside the dev shell
wasm-pack	Latest	Provided by `nix develop`; needed when you run `vp run build:wasm`

Clone and Bootstrap#

# Clone the repository
git clone https://github.com/ubugeeei-prod/ox-content.git
cd ox-content

# Enter the pinned development shell
nix develop

# Install JS dependencies
vp install

# Build all crates and packages
vp run build

# Run tests to verify installation
vp run test

Workspace Tasks#

Enter the pinned shell with nix develop, then run workspace tasks via vp run <task>. The canonical task graph lives in vite.config.ts.

# Setup
vp install

# Building
vp run build
vp run build:rust
vp run build:rust-release
vp run build:napi
vp run build:npm
vp run build:wasm

# Testing
vp run test
vp run test:rust
vp run test:rust-verbose
vp run test:ts
vp run watch

# Code quality
vp run fmt
vp run fmt:check
vp run clippy
vp run lint
vp run check:panic-constructs
vp run ready

# Documentation
vp run doc:cargo
vp run doc:cargo-open
vp run deploy#docs

# Docs and examples
vp run dev
vp run dev:docs
vp run dev:playground
vp run playground
vp run integ-vue
vp run integ-react
vp run integ-svelte
vp run ssg-vite

# Benchmarks
vp run bench
vp run bench:rust
vp run bench:parse
vp run bench:bundle

Project Structure#

ox-content/
├── Cargo.toml              # Workspace configuration
├── flake.nix               # Nix flake wiring (inputs, systems, module list)
├── tools/nix/              # Nix modules: dev shell, packages, vp wrapper, Blacksmith CLI
├── package.nix             # Nix build of the workspace binaries, via crane
├── rust-toolchain.toml     # Rust channel, components, and targets for Nix and rustup alike
├── package.json            # npm workspace metadata and devEngines runtime
├── vite.config.ts          # Vite+ workspace task graph
├── crates/                 # Rust crates
│   ├── ox_content_allocator/   # Arena allocator
│   ├── ox_content_ast/         # AST node definitions
│   ├── ox_content_parser/      # Markdown parser
│   ├── ox_content_renderer/    # HTML renderer
│   ├── ox_content_search/      # Full-text search engine
│   ├── ox_content_napi/        # Node.js N-API bindings
│   ├── ox_content_wasm/        # WebAssembly bindings
│   ├── ox_content_og_image/    # OG image generation
│   └── ox_content_lsp/         # Unified language server
├── npm/                    # npm packages
│   ├── vite-plugin-ox-content/       # @ox-content/vite-plugin
│   ├── vite-plugin-ox-content-vue/   # @ox-content/vite-plugin-vue
│   ├── vite-plugin-ox-content-react/ # @ox-content/vite-plugin-react
│   ├── vite-plugin-ox-content-svelte/# @ox-content/vite-plugin-svelte
│   ├── vite-plugin-ox-content-solid/ # @ox-content/vite-plugin-solid
│   ├── unplugin-ox-content/          # @ox-content/unplugin
│   └── vscode-ox-content/            # VS Code extension
├── editors/                # Editor integrations
│   ├── zed/                # Zed extension
│   └── neovim/             # Neovim plugin
├── examples/               # Usage examples
├── docs/                   # Documentation site
└── .github/workflows/      # CI/CD

Running Tests#

All Tests#

vp run test

# or
cargo test --workspace

Specific Crates#

cargo test -p ox_content_parser
cargo test -p ox_content_renderer

With Output#

cargo test --workspace -- --nocapture

Running the Docs and Playground#

# Start docs and playground together
vp run dev

# Only the docs site
vp run dev:docs

# Only the playground
vp run playground

Then open http://127.0.0.1:4173 for the docs site and http://127.0.0.1:5173 for the playground.

Deploying the Docs to Void#

Deploy the documentation site to Void with:

vp run deploy#docs

The task builds the Rust workspace and local npm packages before running void deploy, and it uses a root base path so assets resolve correctly on https://ox-content.void.app.

See Docs Deployment for environment variables and overrides.

Running Benchmarks#

vp run bench
vp run bench:rust
vp run bench:parse
vp run bench:bundle

Absolute ceilings for fixture bundle gzip, rendered HTML gzip, build time, initial requests, and runtime floors live in tools/benchmarks/perf-budgets.json. After a JSON sweep, check them with:

node tools/benchmarks/bundle-size/measure.mjs --json /tmp/bundle.json
node tools/benchmarks/bundle-size/check-budgets.mjs --bundle /tmp/bundle.json

The PR Benchmark job runs that checker on head measurements. Raise a ceiling in the same PR as the intentional growth, or apply the benchmark-regression-accepted label. See Performance.

For committed benchmark tables and charts, use the Blacksmith-backed docs refresh workflow instead of a local machine:

gh workflow run benchmark-docs.yml --ref main -f runs=7

That workflow runs on blacksmith-32vcpu-ubuntu-2404 and opens a PR with the updated README.md, docs/content/performance.md, and benchmark SVGs. To run the same generator locally, use:

vp run bench:docs

For quick remote checks against the Blacksmith testbox runner:

blacksmith auth login
TESTBOX_ID=$(blacksmith testbox warmup .github/workflows/testbox.yml --job testbox --idle-timeout 60)
blacksmith testbox run --id "$TESTBOX_ID" "vp run bench"
blacksmith testbox stop --id "$TESTBOX_ID"

The latest published benchmark snapshot lives on Performance.

Troubleshooting#

`cargo: command not found`#

Ensure Rust is installed and in your PATH:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

`nix: command not found`#

Install Nix with the official installer, restart your shell, then re-enter the repo:

nix develop

Build fails with linking errors#

On Linux, you may need build essentials:

# Ubuntu / Debian
sudo apt-get install build-essential

# Fedora
sudo dnf groupinstall "Development Tools"

On macOS, install Xcode Command Line Tools:

xcode-select --install

N-API build fails#

Ensure you are on the expected Node.js version:

nix develop
node -v
vp run build:napi

If you manage Node.js outside Nix, match the devEngines.runtime version in package.json.

`wasm-pack: command not found`#

The WASM build task expects wasm-pack to be available:

nix develop
vp run build:wasm

If you are not using Nix, install wasm-pack manually and make sure wasm32-unknown-unknown is available through rustup.