# Docs > Write, extend, and validate Flexprice documentation pages in Mintlify MDX format. Use this skill whenever the user asks to write a new doc, add a section to existing docs, create a guide, document a feature, or update the Flexprice docs site. Trigger when the user mentions "write a doc", "add docs", "documentation for", "create a guide", "update the docs", "add to docs", "document this feature", "threshold notifications", "alerts doc", or any request to produce or modify an .mdx file in the docs repo. This skill knows the Mintlify MDX component set, the docs.json navigation schema, the repo layout, the editorial voice, validation commands, and the dev server setup. - Skill: `flexprice/docs-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add flexprice/docs-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/flexprice/docs-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: flexprice (https://skillmd.com/u/flexprice) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/flexprice/docs-2 --- # Flexprice Docs — Writing and Validation Skill Write new documentation pages and validate them against the live Mintlify build. Always follow the existing style of the repo — read nearby docs before writing to match tone and component usage. --- ## Repo Layout ``` flexprice-docs/ ├── docs/ ← All documentation pages (.mdx) │ ├── customers/ ← Customer-related docs │ ├── wallet/ ← Wallet docs │ ├── product-catalogue/ ← Plans, Features, Coupons │ ├── subscriptions/ ← Subscription workflows │ ├── webhook/ ← Webhook reference │ ├── event-ingestion/ ← Event & metering docs │ └── ... ├── images/docs/ ← Screenshots referenced from docs ├── docs.json ← Navigation config (Mintlify v2) └── .claude/skills/ ← This skills directory ``` The docs site is at `https://docs.flexprice.io`. The `docs.json` at repo root controls all navigation. --- ## Step-by-Step: Writing a New Doc ### 1. Read Before Writing Always read at least two nearby docs before writing — pick pages in the same section or covering similar topics. This ensures consistent tone, component choices, and structure. ```bash # E.g. if writing a wallet doc: cat docs/wallet/auto-top-up.mdx cat docs/wallet/low-balance-alert.mdx ``` Also check `docs/webhook/webhooks.mdx` if the doc involves webhooks, and `docs/product-catalogue/features/wallet-balance-alert.mdx` for alert-related docs. ### 2. Pick the Right File Location | Topic | Directory | |-------|-----------| | Customer management | `docs/customers/` | | Wallet features | `docs/wallet/` | | Plans, Features, Coupons | `docs/product-catalogue/` | | Subscription workflows | `docs/subscriptions/` | | Integrations | `integrations//` | | Webhooks / events | `docs/webhook/` or `docs/event-ingestion/` | | Alerts & notifications | `docs/customers/` (customer-scoped) or nearest feature section | ### 3. Frontmatter Every `.mdx` file starts with: ```mdx --- title: "Page Title" description: "One sentence describing what this page covers." --- ``` - `title`: Short noun phrase, title case - `description`: Shown in search results and page meta — one sentence, no period ### 4. Opening Paragraph Start with a plain prose paragraph (no heading) that explains what the feature is and why it matters. Keep it to 2–4 sentences. Do not repeat the `description` verbatim. ### 5. Benefits List (Optional) For feature docs, a bold-bullet benefits list after the opening paragraph is conventional: ```mdx **Benefits:** - **Proactive management** — Description of why this matters - **Granular control** — Description - **Flexible conditions** — Description ``` ### 6. Section Structure Use `##` for top-level sections and `###` for subsections. Never use `#` (reserved for the page title) or go deeper than `###` in most docs. --- ## Mintlify MDX Components ### Callouts ```mdx Informational note — use for helpful context or clarifications. Similar to Note but for more prominent informational content. Use for gotchas, required conditions, or things that will break if ignored. Use for best practices, recommendations, or "do this" guidance. ``` ### Steps (for configuration workflows) ```mdx Instructions here. More instructions. ``` ### Code Blocks Single language: ```mdx ```json { "key": "value" } ``` ``` Multiple languages side by side: ```mdx ```bash cURL curl ... ``` ```javascript JavaScript fetch(...) ``` ```python Python import requests ``` ``` ### Tables ```mdx | Column | Column | |--------|--------| | Value | Value | ``` Pipe-align all columns. Use bold (`**text**`) in first column when listing settings or fields. ### Cards and Links ```mdx ``` Use `horizontal={true}` for inline card links at the bottom of a page. ### Frames (screenshots) ```mdx ![Alt text](/images/docs/Section/Page/image.png) ``` Only include `` blocks when actual screenshots exist in the repo at the referenced path. **Do not include placeholder image references** — broken image links will fail the `mint broken-links` check. --- ## Webhook Payload Sections When documenting a feature that emits webhooks, follow this structure: ```mdx ### Webhook Payload **Event type:** `event.name.here` ```json { "event_type": "event.name.here", "alert_type": "descriptor", "alert_status": "warning", ... } ``` ### Webhook Fields | Field | Description | |-------|-------------| | `field_name` | What it contains | | `nested.field` | Description | ``` Model new webhook events on existing ones — see `docs/wallet/low-balance-alert.mdx` (event: `wallet.alert`) and `docs/product-catalogue/features/wallet-balance-alert.mdx` (event: `feature.wallet_balance.alert`). For usage-based alerts, follow the `customer.usage.alert` / `feature.usage.alert` pattern established in `docs/customers/threshold-notifications.mdx`. --- ## Navigation: docs.json After writing a new file, **always add it to `docs.json`**. The navigation lives in `navigation.tabs[0].groups` (the Documentation tab). Structure: ```json { "group": "Group Name", "icon": "icon-name", "pages": [ "docs/path/to/page", { "group": "Sub-group Name", "pages": [ "docs/path/to/nested-page" ] } ] } ``` **Rules:** - Flat page paths are relative to repo root, no `.mdx` extension - Sub-groups use the same `{ "group": "...", "pages": [...] }` shape — no `icon` on sub-groups - Always add new pages immediately after the most relevant existing page in the same section - Never create a new top-level group without checking if an existing group is the right home **Common icon names:** `users`, `wallet`, `webhook`, `layer-group`, `refresh`, `file-text`, `gear`, `bell`, `shield`, `code`, `book-open`, `plug` --- ## Validation Commands Run these **before opening a PR**. Both use Node 22 (mintlify does not support Node 25+). ### Check for broken links ```bash PATH="/opt/homebrew/opt/node@22/bin:$PATH" \ /opt/homebrew/opt/node@22/bin/node \ /opt/homebrew/lib/node_modules/mint/index.js \ broken-links ``` - **Pass**: no broken links in your new file — proceed to PR - **Fail**: fix every broken link reported in your file; pre-existing broken links in other files are not your responsibility - The most common cause: referencing a screenshot path in `` that doesn't exist in `images/` ### Validate build structure ```bash PATH="/opt/homebrew/opt/node@22/bin:$PATH" \ /opt/homebrew/opt/node@22/bin/node \ /opt/homebrew/lib/node_modules/mint/index.js \ validate ``` - Confirms `docs.json` is valid, all referenced pages exist, and no structural errors - Pre-existing warning: `Invalid import path react in /components/Callout.tsx` — this is a known upstream issue, ignore it ### Dev server (visual check) ```bash PATH="/opt/homebrew/opt/node@22/bin:$PATH" \ /opt/homebrew/opt/node@22/bin/node \ /opt/homebrew/lib/node_modules/mint/index.js \ dev --port 3333 ``` The `.claude/launch.json` in this repo is configured to use this exact path. Use `preview_start` with the `"docs"` configuration. **Node version note:** The system has Node 25 as default (`/opt/homebrew/bin/node`), which is unsupported by mintlify. Always prefix with `PATH="/opt/homebrew/opt/node@22/bin:$PATH"` or use the absolute node@22 binary path. --- ## Editorial Voice | Do | Don't | |----|-------| | "Wallet balance alerts fire when…" | "We've added exciting new alerts that…" | | "Configure thresholds per wallet" | "Powerful per-wallet configuration" | | "Set `alert_enabled: true` to activate" | "Simply toggle the switch to enable" | | Present tense: "Alerts trigger on…" | Future: "Alerts will trigger on…" | | Second-person: "You can configure…" | First-person: "We allow you to…" | - **No em dashes**: never use `—` in docs content. Split the sentence, or use a comma, colon, or parentheses instead. Applies to prose, callouts, tables, and bullet lists. - **No marketing adjectives**: skip "powerful", "flexible", "seamless", "robust", "easy" - **Name the mechanism**: say what the API field or UI element is called - **One idea per sentence**: split compound sentences - **No trailing summaries**: don't end with "In summary, …" or "By using X, you can…" --- ## Checklist Before Opening a PR - [ ] File is in the right directory (`docs/
/`) - [ ] Frontmatter has `title` and `description` - [ ] Page is added to `docs.json` in the correct group - [ ] No em dashes: `grep -n "—" docs/path/to/page.mdx` returns nothing - [ ] No `` blocks reference images that don't exist in the repo - [ ] `mint broken-links` passes with no new errors - [ ] `mint validate` passes (the pre-existing `Callout.tsx` warning is acceptable) - [ ] Dev server renders the page correctly (check heading hierarchy, code block syntax, table alignment) - [ ] Internal links use `/docs/...` paths (not relative `../` paths) --- ## Known Pre-Existing Issues (Do Not Fix Unless Asked) - **`components/Callout.tsx` react import warning** — flagged by `mint validate`, pre-existing, not fixable from docs content.