What this is

@blaaiz/docs-core is the shared engine for Blaaiz-family documentation sites. It wraps Fumadocs and adds the pieces every docs site needs. The core owns the logic. Each docs site installs this package and supplies only its own config and content.

• Mintlify-compatible — reads a docs.json navigation file and Mintlify-style MDX components.
• OpenAPI-native — renders an API reference and an interactive try-it playground from your OpenAPI files.
• Secure by default — the try-it proxy forwards the caller's own token, injects no secrets, and only reaches the API origins a site allow-lists. Every forward is rate-limited per client IP.
• Ask AI built in — ai: { provider: 'anthropic' } in config is a complete setup: a streaming answer panel grounded in the site's own pages, with Anthropic and OpenAI as equals. The API key stays on the server.
• A CLI and agent skills — npx docs-core init scaffolds a working site; npx docs-core agents installs the docs-core skill for Claude Code and Codex, so an assistant edits the site correctly.

Status — This repository currently contains the project foundation: the toolchain, the standards, and the architecture. Feature code lands next. See docs/adr/.

Who uses it

Blaaiz publishes this as a public npm package. Any organization can install it and keep its own config and content private. Each site is config plus content:

your-docs/
  docs.config.ts                  # theme, auth mode, API allow-list
  content/docs.json               # navigation
  content/docs/**/*.mdx           # prose
  content/api-reference/**/*.json # OpenAPI files
  package.json                    # installs @blaaiz/docs-core

Start a site

npx docs-core init      # docs.config.ts, content/docs.json, starter pages, .env example
npx docs-core agents    # the docs-core skill for Claude Code and Codex, plus AGENTS.md

init never overwrites without --force, and both commands print exactly what they wrote.

Wire a site

Three pieces of the API reference live in this package and plug into a site:

/* app/globals.css — after the fumadocs imports */
@import '@blaaiz/docs-core/styles/docs.css';
@import '@blaaiz/docs-core/styles/api-reference.css';

// components/api-page.tsx
'use client';
import { apiOperationLayout } from '@blaaiz/docs-core/ui';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';

export const APIPage = createOpenAPIPage({
  content: { renderOperationLayout: apiOperationLayout },
});

Copy patches/fumadocs-openapi.patch into the site and register it in pnpm-workspace.yaml under patchedDependencies. It turns the code-sample language tabs into a dropdown with the endpoint name as the panel title. Re-check the patch on each fumadocs-openapi upgrade.

Design in one rule

The core owns the logic. Each site owns config and content. If a thing is the same for every organization, it is in this repo. If it changes per organization, it is in the site.

See docs/ARCHITECTURE.md.

Develop

corepack enable
pnpm install
pnpm run verify   # format, lint, types, architecture, tests, build, public API

See CONTRIBUTING.md for the full workflow.

License

MIT © Blaaiz