77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
|
# 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.
|