diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..26d76ba --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# 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//
/`. +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 `` from `@astrojs/starlight/components`. Numbered lists inside `` get a nice visual. +- **Callouts:** use `