Write documentation
Write a page around a reader task: what they need, what they do, what success looks like and what to check when it fails. Markdown is source; routes, sidebar, headings and search are generated from that source and metadata.
Build one complete page
| Content decision | Guide |
|---|---|
| Metadata and title routes | Frontmatter |
| Text, headings and code | Markdown syntax |
| Folders and navigation | Content structure |
| Public assets and links | Links and media |
| Diagram source and output | Mermaid diagrams |
| Review and retirement | Content lifecycle |
Start with Frontmatter and metadata to write the header and understand title-derived routes. Then use Markdown for headings, paragraphs, lists, code and links.
For Field Guide, a Workstation check page should identify the required tools, show commands using fictional/safe paths, explain expected output and distinguish a missing tool from an unsupported version. A code block without interpretation is not a complete task.
Use one clear H1 and stable H2-H4 task headings. Keep route/title changes deliberate and explain important code terms in prose so search can find them. Verify commands before labelling an example tested; otherwise describe the actual inspection level.
Organize without breaking navigation
Files, folders and URLs covers source paths, section landings, ordering and generated routes. A filename helps source management but does not preserve a page URL if its title changes.
Choose sections around audiences/tasks. Write useful _index.md landings with learning paths. Hidden sidebar metadata changes discoverability, not build/search/privacy. Keep sensitive material out of public build inputs.
Add media only where it helps
Images and downloads covers static paths, useful alt text, deployment and file checks. The optional editor is not a media-upload service; maintain assets through the project filesystem/workflow.
Diagrams covers Mermaid source, rendering and reader controls. Prefer a diagram when relationships are easier to understand visually, and explain its conclusions in ordinary text. Check the actual generated image/diagram and narrow-screen behavior.
Keep content correct over time
Content lifecycle covers review, renames, retirement and release checks. An updated date should represent a real content review. A successful build does not prove an external command, vendor policy or deployment instruction remains current.
Coordinate writers before changing paths or deleting files. Keep source history and a recovery plan. The browser editor does not provide general per-page revisions or realtime merging.
Before release
Confirm metadata/route, task completeness, links/anchors, local assets, code safety, diagram rendering, mobile readability and search. Save intended source, then build/publish and deploy separately. Save, publish and deploy names each state so a missing step can be diagnosed without repeating the wrong action.