Contributing documentation

The documentation is a separate Next.js workspace at apps/docs in the BitaKit repository. Pages are Markdown or MDX files in apps/docs/content/docs.

Keep one maintained sourceCopy Anchor Link

API explanations and tutorials belong in this handbook. Package READMEs provide a short introduction and link here; do not copy complete chapters into a package's docs/ folder. Repository-root docs/ is for development plans, architecture decisions and shared README assets. When retiring a guide, preserve useful content here and update its incoming links. Use TypeScript for new examples, TSX for React, and check them against the current API.

Add a guideCopy Anchor Link

1. Create a page such as content/docs/packages/my-provider.mdx with a title and description.
2. Add installation requirements, supported versions, a small working example and limitations.
3. Link it from the package overview. Use meta.json to control navigation order when needed.
4. Run the documentation build and check the page and search locally.
5. Submit the change as a pull request to the BitaKit repository when contributions are open.

---
title: My provider
description: Connect an external provider to BitaKit.
---

## Installation

Document the package's real installation command and release status.

## Usage

Include a minimal example verified against the public API.

Write a lesson people can finishCopy Anchor Link

1. Start with one visible result and the fewest files needed.
2. Keep the first example free of optional properties. Add one capability per later step.
3. Name the exact file and say whether a block replaces it or edits one property.
4. Show what should happen, then link to the next lesson.
5. Put exhaustive tables, alternative APIs and lifecycle details in the reference section.

Use the Counter learning path for the core concepts. Package-specific guides may use their own small example. Use the existing Markdown, code blocks, Callout and navigation components; no custom visual treatment is needed. Verify copied examples against the current generated types.

Add a visual that explains somethingCopy Anchor Link

Use the interactive examples in Actions, Settings and Slots as the style references. Keep each visual and its code together in the relevant section; do not add a separate gallery or repeat it at the end. For UI anatomy, reuse SettingsIllustration or SlotIllustration; they show the code for the selected region with the existing Fumadocs controls and theme.

Every other diagram is drawn with the diagram-design agent skill in the BitaKit profile, which the repository's .diagram-design file selects:

1. Install the skill once with npx skills add cathrynlavery/diagram-design.
2. Ask your agent to draw the diagram, or edit an existing source in apps/docs/diagrams/<name>.html. The light skin is the source; use only the profile's colors and keep the skill's rules (orthogonal connectors, masked labels, at most two accent elements).
3. Run npm run diagrams -- <name>. It derives the dark variant, exports both SVGs with the skill's helper and copies them to apps/docs/public/diagrams.
4. Add the title, caption, size and the implementation files it describes to apps/docs/components/diagrams/figures.json, then place <Figure name="…" /> beside its example.

Run npm run test --workspace @bitakit/docs: it checks every diagram's exports and references and every Figure name in the pages. Then check both themes and a narrow window in the browser.

Review expectationsCopy Anchor Link

Write in English. Distinguish released functionality, local previews and experimental support. Never include credentials. Use ordinary Markdown and existing Fumadocs components; MDX can execute code, so contributions must be reviewed before deployment.

An external package may stay in its author's repository and npm scope. Adding its guide here does not publish the package, activate it in applications or certify compatibility.

PreviewCopy Anchor Link

From the repository root:

npm run dev:docs
npm run build:docs

The development server uses port 3002. Search indexes the documentation content automatically.

Verify the generator before releaseCopy Anchor Link

These steps are for repository contributors, not application developers. Run them from the repository root with Node.js 24 and npm 10 or newer.

1. Install dependenciesCopy Anchor Link

npm install

2. Prepare local packagesCopy Anchor Link

The generator can install packed BitaKit packages before they are published. Build and pack the packages a minimal app installs, including discovery and the CLI:

npm run pack -- .tmp/docs-packages core discovery ui next cli

The script builds each package first and removes older BitaKit archives from that directory.

3. Generate your appCopy Anchor Link

Choose a destination that does not already exist. The official Next.js scaffold is downloaded, so this step requires internet access.

node packages/create-app/src/cli.mjs ../my-foundation-app \
  --framework next \
  --features none \
  --packages-dir "$PWD/.tmp/docs-packages" \
  --yes

The generator installs dependencies and creates native routes, next.config.ts with withBitaKit and the root layout with BitaKitProvider. It does not copy plugin implementations or create a backend.

4. Run itCopy Anchor Link

cd ../my-foundation-app
npm run dev

Open the local URL printed by Next.js. You should see the generated welcome page. The generated BitaKitProvider connects to Next's router internally; no per-page router adapter is required. npx bitakit doctor checks the wiring.

For the full check, run npm run verify:generated. It packs the packages itself, generates every supported project shape, and type-checks, builds and smoke-tests each one in a browser. It needs internet access and Playwright's Chromium.

ReleaseCopy Anchor Link

Releases run in GitHub Actions from main; nobody publishes from a laptop. Every @bitakit/* package stays on one release line (0.2.x), and only packages whose shipped content changed get a new version, so patch versions may differ within a line. Generated apps depend on the line (^0.2.0), never on one exact version.

1. Add a changeset to your pull requestCopy Anchor Link

A change to a published package needs a changeset: a short Markdown file in .changeset/ that names the packages and the bump.

npm run changeset

The command asks which packages changed and whether each is a patch or minor bump, then writes a file like this:

---
'@bitakit/cli': patch
---

Document how to update BitaKit in the CLI README.

The summary becomes the package's CHANGELOG.md entry. Changes that ship nothing (docs site, tests, workflows) need no changeset. Commit the file with the change.

A minor bump starts the next release line (0.2 to 0.3). Changesets moves only the packages a changeset names, so a new line needs one changeset that lists every published package as minor; CI's version check fails while packages sit on two lines. It also checks pending changesets, so a minor or major changeset that does not list every published package fails the pull request that adds it, before the Version packages pull request could split the line.

2. Merge into mainCopy Anchor Link

.github/workflows/release.yml runs on every push to main. It first runs CI (the format check, every package test, the version check, the docs build), then:

3. Merge the "Version packages" pull requestCopy Anchor Link

Review the bumped versions and changelogs, then merge. The next run publishes them. A dependent package only gets a new version when its own changeset says so or when a dependency leaves its caret range.

How the workflow authenticatesCopy Anchor Link

npm accepts the publish through trusted publishing: each @bitakit/* package on npmjs.com trusts the repository mvavesal/bitakit, the workflow file release.yml and the environment npm. No npm token is stored in GitHub, and only the publish job may request the identity token. A new package must first be published once by hand and then given the same trusted publisher. The repository is private, so npm records no provenance attestation.