Write and maintain Wazapin docs

This guide is for contributors who add or update Wazapin documentation. The docs site is an Astro project powered by Nimbus: content is owned in this repository, and the build validates MDX tags and internal links before deployment.

Choose the page shape first

Start from the reader’s question, not the component you want to use:

Do not create a new page type when an existing shape fits. Keep the title answer-first and make the first paragraph explain the outcome.

Project structure

 docs/
 ├── astro.config.ts           # Site URL, sidebar, redirects, build rules
 ├── nimbus.json               # CLI-managed component provenance
 └── src/
     ├── components.ts         # MDX globals registry
     ├── components/ui/        # Nimbus components owned by this project
     ├── content/docs/         # English pages; directory becomes URL path
     ├── content/docs-id/      # Indonesian pages under /id/
     ├── content/partials/     # Reusable MDX snippets
     ├── layouts/              # BaseLayout and DocsLayout
     └── styles/               # Theme tokens and prose styles

A page at src/content/docs/guides/example.mdx becomes /guides/example. Add the file to the sidebar only when it is ready for readers; the build will catch an unresolved sidebar reference.

Write Markdown and MDX

Every page needs frontmatter with at least a title. Keep the description short because it is used in page metadata and the page header:

---
title: "Handle delivery status updates"
description: "Process sent, delivered, read, and failed transitions from webhooks."
---

Explain the result first.

## Next step

Link to the next action with a descriptive label.

MDX components are available without imports only when registered in src/components.ts. The current registry includes Aside, CardGrid, LinkCard, Accordion, Steps, Tabs, and the other shared Nimbus primitives. Unknown PascalCase tags fail the Nimbus pre-build validation; do not work around that check by writing a custom HTML approximation.

For navigation cards, use the official LinkCard component:

<LinkCard
  title="Send your first message"
  description="Follow the quickstart from an API key to a successful request."
  href="/getting-started/quickstart"
/>

Use Card only for non-link content. Use CardGrid to keep card spacing and responsive columns consistent.

Reuse exact shared content

Repeated guidance belongs in src/content/partials/. Render a partial instead of importing an MDX page directly:

<Render file="authentication" />

Use a partial when the same paragraph, prerequisite list, or warning must stay identical across multiple pages. Do not extract content merely to shorten one file, and do not hide page-specific instructions inside a generic snippet.

Layouts and banners

Normal documentation pages use DocsLayout automatically. Use frontmatter only when the page genuinely needs a different shape:

---
title: "A wide reference table"
sidebar: false
tableOfContents: false
---

Use a banner for a real release, migration, deprecation, or temporary availability notice—not as decoration:

---
title: "Legacy endpoint"
banner:
  content: "This endpoint is deprecated. Use the messages API instead."
  type: caution
  dismissible:
    id: legacy-endpoint-v1
    days: 14
---

Keep the banner ID stable while the notice is the same. Change the ID only when the meaning changes and readers should see it again.

Add Nimbus components safely

Use the official registry so dependencies and provenance stay correct:

npx @cloudflare/nimbus-docs list --type ui
npx @cloudflare/nimbus-docs add <component>

Review the generated files and nimbus.json entry before using the component. Then register it in src/components.ts when it will be used from MDX. Install a component because a real page needs it—for example, LinkCard for navigation or Accordion for long status/error sections—not just because it appears in the Nimbus catalog.

Verify before publishing

Run these commands from docs/:

npm run lint:docs
npm run build

The lint must have zero errors. Existing warnings should be reviewed but not hidden. The build must complete with MDX validation and static route generation. For visual changes, open the built preview and check the actual page at desktop and mobile widths, including keyboard focus for links, sidebar groups, and disclosure controls.