docfront

name	docfront
description	Conventions for writing, organizing, and browsing documentation in a docs/ directory using docfront. Use when creating documents, restructuring documentation, or unsure about frontmatter format and file naming conventions.
license	CC0 1.0
metadata	{"author":"Paleo","version":"0.4.0","repository":"https://github.com/paleo/docfront"}

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 files

Workflow

1. Understand the Subject — clarify what needs to be documented. Ask the user if unclear.
2. Determine Placement — scan existing docs (docfront --recursive). Decide: new file, existing file, which subdirectory. Discuss with the user if unclear.
3. 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 --check to 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/.