Documentation Authoring Guide

This guide explains how to write, update, and maintain documentation pages in Magic's doc/ directory so they stay accurate, consistently formatted, and correctly rendered on fluttersdk.com.

• Page Template
• Folder Taxonomy
• Downstream Rendering
• API Accuracy Rule
• Per-Feature Doc-Sync Checklist
• Code Samples
• What Not to Add

Page Template

Every page (new and rewritten) must conform to this structure exactly:

# Page Title

One-line description sentence (plain prose, feeds the downstream page description).

- [Section One](#section-one)
- [Section Two](#section-two)


## Section One

Content.


## Section Two

Content.

Rules derived from this template:

• H1 title: the bare # Title line, no YAML frontmatter above or below it.
• Lead sentence: a single plain-prose sentence immediately after the H1, before the TOC bullets. fluttersdk.com's DocsScaffolder extracts this paragraph as the page description (truncated at 160 characters); omitting it leaves the page with an empty description.
• Anchor-TOC: a bulleted - [Label](#anchor) list before the first section. Every TOC entry must have a matching in the body, and every in the body must appear in the TOC. Mismatches break in-page navigation.
• Section anchors: on the line immediately before the ## or ### heading. Use the same kebab-case slug in both the TOC link and the anchor.
• No YAML frontmatter: do not add --- blocks, title:, description:, or any ordering metadata. The downstream site derives all of this from the page itself (see Downstream Rendering).

Folder Taxonomy

Pages live under doc/ in one of these subdirectories. Do not create new subdirectories; place new pages in the closest existing folder.

Downstream Rendering

fluttersdk.com syncs doc/ via its DocsScaffolder (triggered by the POST /api/v1/docs/magic/sync endpoint or the DocsSync command). The scaffolder reads:

• H1 to set the page title.
• Lead paragraph (the single sentence after H1, before the TOC) to set the page description.
• Directory name to determine the section label (converted via Str::headline).

Navigation order and menu labels live in the doc_pages database table, curated by the site admin in Filament. The doc/ directory needs no nav manifest, no ordering file, and no frontmatter. Adding any of these would have no effect on the rendered site.

API Accuracy Rule

Every documented method, signature, and parameter must exist in the current lib/src/ code. This is the backbone of the overhaul that produced these docs, and it must stay the backbone going forward.

Before writing or updating a code sample:

1. Open the relevant facade in lib/src/facades/.dart (or the concrete class under lib/src/) and read the actual method signatures.
2. Copy the method name and parameter list verbatim into the example. Do not invent parameters or default values that are not in the source.
3. If a method you expected to find is absent, do not document it. File a separate issue or add it to the framework first.

Corollary: when a facade or class is renamed or a method is removed, update the matching doc page in the same change set. The CLAUDE.md Post-change sync rule (doc/ item) mandates this; see the Per-Feature Doc-Sync Checklist below for the detailed steps.

Per-Feature Doc-Sync Checklist

When a facade or framework feature changes, apply this checklist before marking the work done. This checklist is the doc-layer expansion of the Post-change sync rule in CLAUDE.md (section "Post-change sync").

1. Identify the matching doc page.

2. Update the page.

• Add, rename, or remove the section(s) that cover the changed surface.
• For a renamed method: update every occurrence in prose, code samples, and the TOC.
• For a removed method: delete its section and its TOC entry.
• For a new method: add a section with a dart code example (see Code Samples), add a TOC entry, and add the matching anchor.

Every - [Label](#anchor) in the TOC must have a corresponding in the body. Every in the body must appear in the TOC. Fix any orphaned entry on either side.

Choose the correct folder from the Folder Taxonomy, create the file, and write it according to the Page Template. H1, lead sentence, TOC, then sections with anchors.

Code Samples

Use fenced dart blocks for all Dart/Flutter code:

```dart
final value = Config.get('app.name', 'Magic');
```

Import the public barrel at the top of samples that need it:

import 'package:magic/magic.dart';

For test samples, use the testing barrel:

import 'package:magic/testing.dart';

For CLI-related samples, use the CLI barrel:

import 'package:magic/cli.dart';

Keep samples minimal: show the method call and its most common parameters. Omit boilerplate (main(), MaterialApp, widget scaffolding) unless the scaffolding is the point of the example.

What Not to Add

• No YAML frontmatter. The --- block adds no downstream value and is explicitly excluded.
• No nav manifest or ordering file. Navigation is DB-curated on fluttersdk.com; a repo-side manifest would be ignored.
• No invented version attribution such as "Added in v1.2". Use CHANGELOG.md and release notes for that.
• No live-preview tags. Magic's preview_url is null (no preview app is configured), so the tag renders a "not available" placeholder.
• No new subdirectories. The folder taxonomy is locked; place pages in the closest existing folder.
• No em-dash or en-dash. Use comma, colon, semicolon, period, or parentheses instead.