Authoring Documentation
All project documentation lives in the docs/ directory. The docfront CLI lets both humans and AI agents discover and read documents without leaving the terminal.
Browsing with CLI
Run commands via the project's package manager (e.g.npm run docfront --,pnpm docfront).
docfront # list root docs
docfront --dir topic-a --dir topic-b/sub-topic-c # list subdirectories
docfront --recursive # list everything
docfront --read doc-1.md topic-a/doc-2.md # read documents (frontmatter stripped)
docfront --check # validate all filesWorkflow
- Understand the Subject — clarify what needs to be documented. Ask the user if unclear.
- Determine Placement — scan existing docs (
docfront --recursive). Decide: new file, existing file, which subdirectory. Discuss with the user if unclear. - Write — follow the conventions below.
Writing Guidelines
- Target audience: an experienced newcomer — someone technically capable but unfamiliar with this specific project.
- Be brief and specific — no obvious information, no generic best practices.
- Typical document: 40–80 lines.
- Prefer referencing source files over large code blocks.
- If the title makes the purpose obvious, omit the
summary.
File and Directory Naming
- Use lowercase-with-dashes (kebab-case) for new files and directories.
- Uppercase is allowed by the CLI (e.g.
RELEASING.md). - Names must be shell-safe: no spaces, no quotes, no special characters. The CLI validates this for both files and directories. Use
docfront --checkto verify. - Use
.md(Markdown) for all documents. - Use short, descriptive names.
- Group related documents into subdirectories. Subdirectories can be nested.
YAML Frontmatter
.md files can start with a YAML frontmatter block. Add it when it adds value — especially when the filename or heading alone is not explicit enough. It is not required; when frontmatter is absent, the CLI falls back to the first # heading in the document body for the title. Fields:
| Field | Required | Description |
|---|---|---|
title | No | A human-readable display name shown in listings. Falls back to the first # heading when absent. |
summary | No | One concise sentence. If the title already makes the purpose obvious, omit the summary to avoid redundancy. |
read_when | No | A YAML list of short, action-oriented hints. Each hint completes: *"Read this document when you are…"* |
Document Body
After the closing --- of the frontmatter, write standard Markdown. There are no constraints on the body format — use headings, code blocks, tables, and lists as needed.
---
title: Your Title Here
summary: A one-sentence description of what this document covers.
read_when:
- first situation when this document is useful
- second situation
---
# Your Title Here
Start your content here…References
- Installing Docfront CLI — how to add docfront CLI to a project.
- Bootstrapping Documentation — instructions for creating or extending project documentation by exploring the codebase.
- Migrate Existing Documents — guide for bringing an existing folder of Markdown documents into docfront conventions (naming, frontmatter).
- Migrate Skills to Docfront Documentation — guide for moving internal project documentation from agent skills into
docs/.