| name | writing-new-fluentbooking-doc |
| description | Use this skill when the user asks to write a new FluentBooking documentation page — phrases like "write a doc for X", "add a documentation page for X", "document the X feature", "create a how-to for X", "new doc page for X". Guides Claude to produce a page that matches the existing 60 pages in tone, frontmatter, heading structure, image conventions, and sidebar wiring. |
Writing a new FluentBooking doc page
A new doc page touches three places in the repo:
- A new
.md file under docs/<section>/
- A new screenshot folder under
docs/public/images/<section>/<page-slug>/
- A new sidebar entry in
docs/.vitepress/config.js
Skip any of the three and the page won't be discoverable or won't render properly.
Step 1 — Pick the section folder and archetype
Section folders (docs/<section>/):
| Folder | What lives here |
|---|
getting-started/ | Install/activate, onboarding, intro pages |
host-events/ | Hosts, event types, booking config, notifications |
availability/ | Availability/schedule management |
bookings/ | Booking list, manual create, cancel |
payments/ | Payment gateways, coupons, offline |
integrations/ | External services (Zoom, Google, FluentCRM, etc.) |
global-settings/ | Site-wide email, host, frontend panel settings |
miscellaneous/ | Shortcodes, embedding, URL tricks, import/export |
troubleshooting/ | FAQs, best practices, get help |
Then pick the archetype — the page skeleton differs by type:
- Intro / overview → start with a tagline, "Why X?", benefits, "Get Started in Minutes"
- How-to / feature → numbered task sections, screenshot per step, ends in Save Changes
- Integration → use the dedicated
new-fluentbooking-integration skill instead
- Settings page → enable-the-module section, then sub-settings with bullet descriptions
- Troubleshooting / FAQ → "Frequently Asked Questions" with Q:/A: format
- Reference / list → defined-list style (code item — description), code blocks for examples
Step 2 — Name the file
- Kebab-case, lowercase, no spaces
- Use
how-to-<verb>-<feature>.md for action-focused pages (matches majority)
- Some pages drop the
how-to- prefix (e.g. single-one-off-event.md) — fine
- Integration pages: see the
new-fluentbooking-integration skill
Step 3 — Frontmatter
Exactly two fields. No others.
---
title: <Title-Cased Page Name>
description: <60–100 chars. One sentence. Used for meta tags and search.>
---
Examples from existing pages:
title: Create New Events
description: Define event types (one-to-one or group), duration, and booking flow. Learn how to create new booking events in FluentBooking.
title: Customizing the Coupon Field on Your Booking Form
description: Change the coupon field label, helper text, and visibility on the booking form. Match your brand and reduce booker confusion.
Step 4 — Page skeletons (copy and fill)
How-to / feature page
---
title: <Feature Title>
description: <60–100 char one-liner about what the user achieves>
---
# <Feature Title>
<1–2 sentence opener: what this is + why it matters. Friendly but professional.>
In this guide, we'll walk you through <X>. Let's get started!
::: tip Important
Before <doing this>, make sure you've already <prerequisite> — see [<linked doc title>](/<section>/<linked-slug>).
:::
## <First Task Section>
<1–2 sentence intro to the step.>
To <action>, go to the **<UI Menu Path>** section and click the **<Button Label>** button.
## <Next Task Section>
<Instruction paragraph. Use bold for UI labels:>
A pop-up will appear, giving you the choice between **<Option A>** and **<Option B>**. Select your preferred option.
### <Sub-step if needed (H3)>
<Sub-step instructions.>
Once you've configured <summary>, click the **Save Changes** button.
Intro / overview page
---
title: Introduction to <Feature/Product>
description: <60–100 chars>
---
# <Feature/Product Name>
<Tagline — 1 sentence on what this is.>
## Why <Feature>?
- <Benefit 1>
- <Benefit 2>
- <Benefit 3>
## <Benefit Group H2>
<Paragraph explaining the benefit.>
- <Detail bullet>
- <Detail bullet>
## Get Started in Minutes
New here? Follow this path:
1. **[<Step 1 Title>](/<section>/<slug>)** — short description.
2. **[<Step 2 Title>](/<section>/<slug>)** — short description.
3. **[<Step 3 Title>](/<section>/<slug>)** — short description.
Need help? Check **[<Troubleshooting Title>](/troubleshooting/<slug>)** or reach the team via **[<Support Title>](/troubleshooting/<slug>)**.
Welcome aboard — <enthusiastic 1-line closing>.
Settings page
---
title: <Settings Domain>
description: <60–100 chars>
---
# <Settings Domain>
<1-sentence description of what this settings page controls.>
## Enable the <Feature> Module
Before you can <use feature>, you must first <prerequisite>.
Start by going to the **<Menu Path>** section. Under **<Submenu>**, select **<Option>**, and you will see **<Setting Name>**. Now, switch on **<Toggle>**.
After that, configure the following:
- **<Setting Name>:** Description of what it does.
- **<Setting Name>:** Description.
- **<Setting Name>:** Description.
Once done, click the **Save Settings** button.
## <Next Settings Group>
<Repeat the pattern: intro sentence, instruction, optional bullet list of fields.>
Troubleshooting / FAQ page
---
title: <Troubleshooting Topic>
description: <60–100 chars>
---
# <Topic Title>
<1-sentence meta description of what this page solves.>
## Frequently Asked Questions
**Q: <User question phrased naturally>?**
**A:**
- **<Cause 1>:** <Solution or explanation>.
- **<Cause 2>:** <Solution>. See [<Related Doc>](/<section>/<slug>).
- **<Cause 3>:** <Solution>.
**Q: <Next question>?**
**A:** <Paragraph-form answer.> See [<Related Doc>](/<section>/<slug>).
## General Troubleshooting Tips
- **<Tip 1>:** <Explanation>.
- **<Tip 2>:** <Explanation>.
- **<Tip 3>:** <Explanation>.
For more help, see [<Get Help Title>](/troubleshooting/best-practices-and-get-help).
Reference / list page
---
title: <Reference Topic>
description: <60–100 chars>
---
# <Reference Topic>
<1-sentence purpose statement.>
## <Action Section>
To <use these items>:
Go to **<UI Location>** and <step>.
## Available <Items>
These are the available <items>:
- `<item_1>` — short description.
- `<item_2>` — short description.
Use the following exactly as shown:
\`\`\`
<example_code_1>
\`\`\`
### <Use-Case Subheading>
<Use-case description.>
\`\`\`
<example_code>
\`\`\`
**Parameters:**
- **<param_1>:** Description.
- **<param_2>:** Description.
Step 5 — Tone rules (10 must-follow)
- 2nd person. "you", "your" — never "the user", "one".
- Imperative-first sentences. "To create…, go to X…" (not "You can create…").
- Bold UI labels in exact Title Case.
**New Event Type**, **Save Changes**, **Calendars** — match the UI string letter-for-letter.
- No contractions inside step instructions. "you have to" (not "you've to"). Contractions allowed in introductory and closing prose ("let's get started", "we'll walk you").
- Prerequisites in a
::: tip Important block at the top, with a link to the prior doc.
- Numbered lists for ordered steps; bullets for traits/options/fields.
- One screenshot per task step, embedded immediately after the instruction. Alt text = descriptive sentence, not just the filename.
- Section headings: Title Case, action-oriented. "Choose Events Type", "Configure the Coupon Text" — not "Configuration" alone.
- Closing line: either "Once you've configured X, click the Save Settings button." OR "See ."
- Cross-link phrasing: "See Title" or inline "Click the button" with a link if the button takes you to another doc page.
Step 6 — Screenshots
Create the folder up front (even if empty initially — user will drop files):
docs/public/images/<section>/<page-slug>/
Where <page-slug> = filename without .md. Embed with absolute path:
Rules:
- WebP preferred — match the 80% norm
- Alt text mirrors the surrounding instruction (e.g.
Create a New Event for the button-click screenshot)
- Many existing filenames end
-scaled.webp (WordPress remnant) — fine to keep
If the user hasn't provided screenshots, leave placeholder image links and tell them which files to drop in which folder.
Step 7 — Add the sidebar entry
Open docs/.vitepress/config.js. The sidebar array has 10 groups. Push your new entry into the right group's items array:
{ text: '<Short Sidebar Label>', link: '/<section>/<filename-without-md>' }
Sidebar group ≠ folder name in 4 cases — pick the right group:
| Sidebar group | Folder(s) it pulls from |
|---|
| Getting Started | getting-started/ |
| Hosts & Events | host-events/ |
| Availability | availability/ + 1 from host-events/ |
| Bookings | bookings/ |
| Payments & Coupons | payments/ |
| Integrations | integrations/ |
| Settings | global-settings/ |
| Shortcodes & Embedding | subset of miscellaneous/ |
| Advanced | another subset of miscellaneous/ |
| Troubleshooting & Support | troubleshooting/ |
Sidebar text style: ≤24 chars, Title Case, action-oriented or noun phrase. Don't repeat the section name.
Step 8 — Verify locally
npm run docs:dev
Open http://localhost:5173, navigate to the new page from the sidebar, check:
- Sidebar entry shows up under the right group
- H1 renders, frontmatter title shows in browser tab
- All
 paths resolve (no broken-image icons)
- Internal links work (note: every in-content link opens in a new tab — that's intentional, not a bug)
::: callout blocks render as colored boxes
ignoreDeadLinks: true means the build won't fail on a broken internal link — you have to click through.
Anti-patterns (do NOT do these)
- ❌ Code blocks for prose — this is a user manual, not API reference
- ❌ Raw HTML (
<div>, <br>) except the existing <div class="video-container"> pattern in integration pages
- ❌ Custom Vue components — none registered in the theme
- ❌ More than 3 heading levels
- ❌ Missing H1 in body (frontmatter title alone isn't enough — repeat it as
# Title)
- ❌ Contractions inside numbered step text
- ❌ Generic alt text like "screenshot" or "image1"
- ❌ Adding the page file without a sidebar entry (it'll be orphaned)
- ❌ Adding a sidebar entry without the page file (404 from sidebar)
- ❌ Image path that doesn't mirror
<section>/<page-slug>/
Reference: existing pages to use as templates
- How-to:
docs/host-events/how-to-create-new-events.md
- Intro:
docs/getting-started/introduction-to-fluentbooking.md
- Settings:
docs/payments/how-to-take-payment-in-bookings.md
- Troubleshooting:
docs/troubleshooting/common-issues-and-faqs.md
- Reference:
docs/miscellaneous/fluentbooking-shortcodes.md
When in doubt, read the closest existing page in the same section and mirror its structure.
