# Contributing to kb.anhonesthost.com

Thanks for helping make our docs better. This guide covers how to add or edit an article.

## Quick start

1. Fork or branch this repo.
2. Edit Markdown files under `src/content/docs/<product>/<section>/`.
3. Preview locally with `npm install && npm run dev` (Node 20+ required).
4. Open a PR. CI runs a build + link check.
5. Once merged to `main`, the deploy workflow ships it automatically — usually live within 2 minutes.

## File layout

```
src/content/docs/
└── whp/                              ← product: WHP
    ├── getting-started/              ← section
    ├── how-to/
    ├── reference/
    └── add-ons/
```

New product? Create a folder under `src/content/docs/` and add a sidebar entry in `astro.config.mjs`. The landing hub only shows products that have content, so empty folders won't surface.

## Article template

Copy `src/content/templates/how-to.mdx.example` as your starting point. Frontmatter required:

```yaml
---
title: Add a domain                   # required
description: How to add a new ...     # required — drives meta + sidebar
sidebar:
  order: 1                            # optional, default alphabetical
  badge: New                          # optional, e.g., "New", "Beta"
---
```

## Importing shared partials

Use the `~` alias (configured in `astro.config.mjs`) so imports work from any file:

```mdx
import SignIn from '~/content/partials/signing-in.mdx';
import Support from '~/content/partials/support-link.mdx';
```

## Style notes

- **Audience:** customers — assume no platform-specific background.
- **Voice:** direct, second-person ("you"), short paragraphs, plain words. Avoid jargon; if you must use it, define it on first use.
- **Headings:** use `##` for section breaks; `#` is reserved for the auto-generated page title.
- **Steps:** use `<Steps>` from `@astrojs/starlight/components`. Numbered lists inside `<Steps>` get a nice visual.
- **Callouts:** use `<Aside>` for tips/warnings — variants `tip`, `caution`, `danger`, `note`.
- **Links to support:** always use the canonical partial (`<Support />`) — never `mailto:support@...` on customer-facing pages.
- **Server hostnames in screenshots:** screenshots should never show the URL bar (we have multiple servers).

## Adding a screenshot

Screenshots live at `src/assets/screenshots/<product>/<id>.png`. They're captured locally with Playwright via `npm run screenshots` — see `tools/screenshots/README.md`. Commit the PNG.

## Reusable partials

If your text would be useful in 2+ places, factor it into `src/content/partials/<name>.mdx` and import it via the `~` alias.

## Reviewing PRs

- Does the article match the template?
- Are screenshots viewport-only (no browser chrome)?
- Do internal links resolve? (CI catches this.)
- Does it use the support partial instead of a `mailto:`?

## Not in scope here

Admin/staff docs and internal runbooks live elsewhere. This repo is customer-facing only.