Contributing to kb.anhonesthost.com

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

Quick start

Fork or branch this repo.
Edit Markdown files under src/content/docs/<product>/<section>/.
Preview locally with npm install && npm run dev (Node 20+ required).
Open a PR. CI runs a build + link check.
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:

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

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.

2.9 KiB Raw Blame History