Documentation

For the index.md of a module folder, or a module that has a single file. The front matter description says what the module is for in one sentence, not a feature list.

1. No heading. Two to four plain sentences: what the module does for the host app and its users, when to use it, and when to use something else (one link). The package name does not appear before the second sentence.
2. ## What you get. Bullets in reader terms, grouped as Pages (paths), Admin area (screens), Server routes, Composables and helpers, and Emails. Mark each item as on by default or opt-in.
3. :module-runtime{…}. The badge row, unchanged.
4. ::note with requirements. Exactly three lines: Installed for you:, You add: and Optional:. Put nothing else in this note. When requirements differ by mode, a line may name it, as in You add (server mode):.
5. ## Quick setup. A ::steps block: install, then nuxt.config.ts, then a migration if the module adds tables, then the role grants if it has staff permissions. A ::warning comes before the migration step and before the grants step ("without this nobody can …"). A config-key gotcha such as "authentication, not auth" gets its own ::warning here. End with a What you should see success callout.
6. ## Options. The lead sentence "Options go under the x key.", then a table of option (full path), type, default and purpose. Long explanations follow as paragraphs led by the option name in bold. Runtime config and environment variables go under ### Runtime config.
7. Module with a single file: ## Server, ## App, ## Hooks, ## Routes, ## Database and ## Translations, in that order. Each opens with one sentence, as on a sub-page. Module with a folder: ## Module pages, a table of page, what it covers and who it is for or which auth mode. It sits after Options. Module with a single file and one sub-page: Options, the single-file sections, ## Module pages, then ## Next steps.
8. ## Next steps. See the closing rule below.

For any other page in a module folder. Files are not renamed just to fit a role: set the page's role through navigation.title and its opening paragraph.

1. No heading. One or two sentences: what the page covers, who it is for (app developer or module author) and which auth mode it applies to ("Server mode only", "Both modes"). Then: "Set up the module first: [Overview](…)."
2. H2s in the order of the page's role (table below). Every H2 opens with one sentence before any table or code:
   • Hooks: "Your app answers these Nitro hooks from a server plugin (server/plugins/*.ts)."
   • Routes: "Routes the module registers, and who may call them."
   • Database: "Tables the module adds. Generate and commit a [migration](…) after installing." A module that adds only columns opens with "Tables or columns the module adds."
   • Translations: "Override any string in your app's i18n/locales/<code>.json."
3. ## Next steps. See the closing rule below.

How the existing module folders map to these roles:

For pages under /guide/concepts.

1. No heading. The problem in one or two sentences, then "After this page you can decide …".
2. ::callout{icon="i-lucide-users"}. One line: For: app developers, module authors or both.
3. ## Which one do I use? A table of what you are building, what to use and a link. It comes before any mechanism.
4. ## Terms. One bullet per glossary term this page owns (usually three to six), each defined in one sentence.
5. ## How it works. The mechanism, with an H3 per mechanism. Add a text diagram where a flow crosses apps.
6. ## Common mistakes (optional). One ::warning per mistake, each saying what breaks.
7. ## Next steps. See the closing rule below.

For pages under /examples/tasks.

1. Bold lead, no heading. **What you'll build:** and one or two sentences.
2. ## Prerequisites. Links only, no explanations. For the toolchain: "See Requirements."
3. ## 1. …, ## 2. …. One numbered H2 per step, such as ## 1. Require a signed-in user. Only task, starter and get-started pages use numbered headings, and sub-numbering such as 1.A is never used. Each step gives one sentence of why, then the code. A ::warning goes before the step it protects, and a ::caution before an irreversible or security-relevant step.
4. Success callout. ::callout{color="success" icon="i-lucide-check"} with What you should see: and an observable result, such as a URL, a status code or a screen.
5. ## Troubleshooting (optional). A table of symptom, cause and fix.
6. ## Next steps. See the closing rule below.

A numbered heading gets an anchor that starts with _ and its number. For example, ## 1. Require a signed-in user becomes #_1-require-a-signed-in-user. Check links explains the rule.

For the starter guides under /examples/starters and the pages under /get-started.

1. Bold lead, no heading. **What you'll have afterwards:** and one to three bullets: a running app, signed in as staff, and which screens you can open. Introduction is not a procedure and skips this lead.
2. ## Prerequisites. A link to Requirements. List only the extra tools here, such as Xcode or Android Studio.
3. ## 1. …, ## 2. …. Numbered step headings, as on a task page, with the success callout after the step that runs the app. Procedures are numbered; reference pages, such as Project structure or Database, keep descriptive headings.
4. ## What is in the starter. Starter pages only: a table of path and what it does.
5. ## Next steps. See the closing rule below.

The requirements table exists only on Installation. Local development lists only the tools this repository needs beyond those.