---
title: "Write and maintain Wazapin docs"
description: "The practical conventions for adding pages, reusable content, and Nimbus components to this documentation site."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.wazapin.id/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Reader question | Page shape | Wazapin examples |
| --- | --- | --- |
| What is this and where do I start? | Overview | [Overview](/introduction), [WhatsApp concepts](/whatsapp-basics/overview) |
| How fast can I see it work? | Quickstart | [Quickstart](/getting-started/quickstart), [SDK quickstart](/sdk/quickstart) |
| How do I do one concrete task? | How-to | [Connect your number](/getting-started/connect-channel), [Handle delivery status](/guides/handle-delivery-status) |
| What does this concept mean? | Concept | [Service window](/whatsapp-basics/session-window), [Message lifecycle](/whatsapp-basics/message-lifecycle) |
| What are the exact values or fields? | Reference | [API overview](/api/overview), [Error codes](/api/error-codes) |
| Show me working code | Example | [Send a text message](/recipes/send-text-message), [Handle webhooks](/recipes/handle-webhook-events) |
| Why did this fail? | Troubleshooting | [Error handling](/api/errors), [Rate limits](/api/rate-limits) |

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

```text
 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:

```mdx
---
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:

```mdx
<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:

```mdx
<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:

```mdx
---
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:

```mdx
---
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:

```bash
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/`:

```bash
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.

Source: https://docs.wazapin.id/guides/writing-docs/index.mdx