| name | write-fluentcommunity-doc |
| description | Create a NEW FluentCommunity end-user documentation page in this VitePress site, correctly placed in a section folder, wired into the hand-maintained sidebar in .vitepress/config.mts, with its image folder created and a clean build. USE FOR: add a doc, write a new doc page, create a guide for X, document this feature, scaffold a new article, turn these notes into a doc page. DO NOT USE FOR: editing an existing page (use edit-fluentcommunity-doc), renaming/moving/deleting/reordering pages (use restructure-fluentcommunity-docs), site-wide quality checks (use audit-fluentcommunity-docs), or non-doc markdown like README.md / CLAUDE.md. |
| license | MIT |
| compatibility | VitePress repo. Content at docs/<section>/<slug>.md served at /<section>/<slug> via cleanUrls. Sidebar inline in .vitepress/config.mts (themeConfig.sidebar). Images at docs/public/images/<section>/<article-slug>/ as .webp. Requires Node + npm (vitepress). |
| metadata | {"project":"fluent-community-user-docs","canonical-rules":"CLAUDE.md"} |
Write a FluentCommunity Doc
Create one new documentation page end-to-end: place it in the right section folder, write
it in the house style, set up its image folder, wire it into .vitepress/config.mts, and
verify with a clean build. Adding a page is a 3-place operation — the markdown file, the
image folder, and the sidebar entry must all be created or the page is orphaned or 404s.
Agent Behavior Rules
- DO complete Phase 1 setup and confirm the summary table before writing anything.
- DO place the file at
docs/<section>/<slug>.md (never at the repo root or docs/ root).
- DO give it exactly two frontmatter fields —
title and description — then a single # H1 on the first line after the frontmatter that matches title.
- DO fix acronym casing in
title/H1: write REST API, FluentCRM, FluentCommunity, CDN, S3, R2, SEO, URL — never Rest Api, Fluentcrm, Cdn.
- DO use house-style blockquote callouts (see Quick Reference), not native
::: containers, unless the user asks otherwise.
- DO reference images as root-absolute
.webp: . Never use <img> tags or filename-as-alt.
- DO write internal cross-links as relative links that keep
.md: [text](./other.md) same-folder, [text](../section/other.md) cross-folder.
- DO add the page to
.vitepress/config.mts under the correct sidebar group; the sidebar link is /<section>/<slug> without .md.
- DO mark Pro-only features
(Pro) in the title/H1, body, and sidebar text; keep the filename/folder lowercase (pro).
- DO end on a green
npm run docs:build.
- DO NOT invent a new section folder or sidebar group without asking the user.
- DO NOT leave
[Screenshot: ...] placeholders unless the user has no image yet — if you must, flag them in the final report.
- DO NOT write inner-whitespace bold (
** term **) — use **term**.
- DO NOT commit, push, or change existing pages' URLs.
Phase 1: Setup (Interactive)
Ask the user for each item. Do not assume.
- Title — becomes the
# H1 and the sidebar label. Record as TITLE.
- Section folder — show the options and pick one:
ls docs/
Record as SECTION.
- Slug — kebab-case; literally keep
&, (pro), () and match the phrasing of sibling files (e.g. add-custom-links-(pro), space-settings-&-privacy). Record as SLUG.
- Sidebar group — open
.vitepress/config.mts and identify the top-level group (and nested collapsed: true sub-group, if any) this page belongs under. Record as GROUP.
- Pro? — is this a Pro-plan feature? If yes, append
(Pro) to TITLE and sidebar text.
- Images / source — does the user have
.webp screenshots and/or raw content to convert? Where from?
Then show a confirmation table and wait for approval:
| Field | Value |
|---|
| File | docs/<SECTION>/<SLUG>.md |
| URL | /<SECTION>/<SLUG> |
| Sidebar | <GROUP> → { text: "<TITLE>", link: "/<SECTION>/<SLUG>" } |
| Images | docs/public/images/<SECTION>/<SLUG>/ |
| Pro | yes / no |
Phase 2: Context
Open a sibling article in the SAME section and mirror its structure and tone before writing —
e.g. docs/community-hub/creating-a-new-space.md. Read the target sidebar group in
.vitepress/config.mts to see exactly where the new entry goes.
Phase 3: Procedure
- Scaffold
docs/<SECTION>/<SLUG>.md:
---
title: <TITLE>
description: <one-sentence, specific, SEO-friendly summary of the page>
---
# <TITLE>
<intro paragraph with **bold** product terms>
> **Use Case:** <when/why a reader needs this>
## <Section heading>
### Step 1: <action>
- Body — task-oriented
## sections; step-driven flows use ### Step N: … then #### sub-details. Use house-style blockquote callouts. Keep paragraphs tight.
- Images — create
docs/public/images/<SECTION>/<SLUG>/ and place .webp files there; reference them root-absolute. If a screenshot is not yet available, insert a clearly-marked [Screenshot: <what it should show>] placeholder and list it in the report.
- Sidebar — in
.vitepress/config.mts, find the GROUP object (or its nested collapsed: true sub-group) and add, in reading order:
{ text: '<TITLE>', link: '/<SECTION>/<SLUG>' },
- Interlink — add a relative
.md link from a related page to this one (prerequisite → next step / "see also"), and link out from this page where it helps.
Phase 4: Verify & Report
npm run docs:build
Must complete with no dead-link warnings. Then report using ✅/⚠️:
- ✅ File, image folder, and sidebar entry created (list the paths).
- ⚠️ Any
[Screenshot: …] placeholders left, or images still needed.
- The live URL:
/<SECTION>/<SLUG>.
Quick Reference
Paths
- Page:
docs/<section>/<slug>.md → URL /<section>/<slug> (cleanUrls, no .md)
- Images:
docs/public/images/<section>/<slug>/*.webp → ref /images/<section>/<slug>/*.webp
- Sidebar:
.vitepress/config.mts → themeConfig.sidebar
Frontmatter (exactly these two)
---
title: <Title Case, acronyms fixed>
description: <specific one-sentence summary>
---
House-style callouts (blockquote — the dominant convention)
> **Use Case:** …
> **✨ Note:** …
> **⚠️ Important:** …
> **💡 Tip:** …
Link forms
- Body → relative WITH
.md: [text](./same-folder.md), [text](../section/other.md)
- Sidebar → root-absolute WITHOUT
.md: link: '/section/slug'
- Image → root-absolute:
/images/section/slug/file.webp
Locate where a page lives
grep -n "<slug>" .vitepress/config.mts
Key principles: acronyms fixed in titles · (Pro) in text, (pro) in filenames · one H1 per page · never orphan a page (3-place operation) · always end on a green build.
