Ariadocs

Build documentation sites and API references in React.

Write your guides in MDX, bring your OpenAPI spec, and render both with the same components. Pages work as React Server Components, and on the client when you need it.

Website · Docs · Components · Example API reference

Packages

Package	What it does
@ariadocs/mdx	Reads MDX files into pages, a table of contents and a sidebar. Replaces @ariadocs/react.
@ariadocs/openapi	Reads an OpenAPI 3.x spec into typed data for every endpoint.
@ariadocs/components	React components for docs pages and API references.
@ariadocs/core	Types and helpers the other packages share.

Quick start

Add the packages to your app:

pnpm add @ariadocs/mdx @ariadocs/openapi @ariadocs/components

import { createDocs } from "@ariadocs/mdx";
import { createOpenAPI } from "@ariadocs/openapi";
import { OpenAPI } from "@ariadocs/components";

const docs = createDocs({ contentDir: "content/docs" });
const openapi = createOpenAPI({ source: "./openapi.yaml" });

// A docs page
const { MDX, frontmatter } = await docs.parse({ slug: "intro" });

// An API endpoint
const api = await openapi.parse();
<OpenAPI.Root api={api}>
  <OpenAPI.Operation id="emails-send" />
</OpenAPI.Root>;

Both docs.getNavigation() and openapi.getNavigation() return the same format, so one sidebar can list your guides and your endpoints.

The framework guides cover the Next.js App Router, the Pages Router, React Router and TanStack Start.

AI agents

The skills folder has one agent skill per package, for AI coding agents:

• ariadocs-mdx: MDX docs pages, frontmatter, TOC, sidebar and routes for each framework.
• ariadocs-openapi: API references from an OpenAPI spec, endpoint pages and code samples.
• ariadocs-components: the UI: layout, mobile nav, theming, composed API pages, and copy-paste Callout, Tabs, Steps and Cards.

Install them with:

npx skills add nisabmohd/Aria-Docs

Or copy the folders into .claude/skills/ (Claude Code) or your agent's skills directory.

Working on this repo

pnpm install
pnpm build          # packages and the docs site
pnpm test
pnpm --filter web dev

The docs site lives in apps/web. Its API Reference renders three endpoints from Resend's public OpenAPI spec (MIT).

To release the packages, follow PUBLISH.md.

License

MIT © Nisab Mohd