Writing Help Articles

Help articles live as MDX files in apps/support/src/content/docs/. They’re written by the product team (usually AI-assisted) and committed to git. Publishing happens automatically on every merge to main.

Where articles live

apps/support/src/content/docs/
  getting-started/   ← onboarding articles
  features/          ← feature explainers
  troubleshooting/   ← fix guides
  account/           ← billing & privacy
  internal/          ← this folder (team-only)

Creating a new article

1. Create a new .mdx file in the relevant folder
2. Add frontmatter at the top:

---
title: Article Title
description: One-sentence summary shown in search results and meta tags.
---

3. Write the content in Markdown
4. Add the article to the sidebar in apps/support/astro.config.mjs
5. Commit and push — the article goes live on next deploy

Frontmatter options

Field	Required	Description
title	Yes	Page heading and browser tab title
description	Yes	SEO description and search snippet
badge.text	No	Badge label shown in sidebar and header
badge.variant	No	note, tip, caution, danger, success

Content standards

• Write for users, not engineers. Avoid jargon. Assume the reader isn’t technical.
• One topic per article. Don’t try to cover everything — link to other articles instead.
• Lead with the action. Start sections with what the user needs to do, not background context.
• Verify before publishing. Every claim must be verifiable from the codebase or confirmed behaviour. If unsure, mark it as approximate or remove it.
• Keep it short. If an article exceeds ~500 words, consider splitting it.

Syncing articles to the AI index

After merging, run the sync script so the AI support chat can answer questions based on the new content:

SYNC_API_KEY=<admin-jwt> pnpm help:sync-articles

This runs automatically in CI but can be triggered manually if needed.

Updating the sidebar

After adding an article, add it to astro.config.mjs under the appropriate section:

{ label: 'Your Article Title', link: '/your-category/your-article' },

The sidebar label can differ from the page title — keep it short (3–5 words).