docfront

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

所有项目文档都存放在

docs/

目录下。

docfront

CLI 支持人类和 AI Agent 无需离开终端即可查找和阅读文档。

Browsing with CLI

使用CLI浏览

Run commands via the project's package manager (e.g.
npm run docfront --
,
pnpm docfront
).

bash

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

通过项目的包管理器运行命令（例如
npm run docfront --
、
pnpm docfront
）。

bash

docfront                                          # 列出根目录文档
docfront --dir topic-a --dir topic-b/sub-topic-c  # 列出子目录内容
docfront --recursive                              # 列出所有内容
docfront --read doc-1.md topic-a/doc-2.md         # 读取文档（已去除frontmatter）
docfront --check                                  # 校验所有文件

Workflow

工作流

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.

明确主题 — 梳理需要记录的内容。如果有疑问可向用户确认。
确定存放位置 — 扫描现有文档（执行
```
docfront --recursive
```
），决定存放到新文件、已有文件还是对应子目录。如果不确定可与用户沟通。
编写内容 — 遵循以下规范。

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
```
.

目标受众： 有经验的新成员 — 具备技术能力但不熟悉当前项目的人员。
内容简洁明确 — 不要添加常识性内容，也不要写通用最佳实践。
单篇文档长度建议：40–80行。
优先引用源文件，避免大段粘贴代码块。
如果标题已经能明确说明文档用途，可以省略
```
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.

新建文件和目录使用全小写加短横线（kebab-case）格式。
CLI 支持大写命名（例如
```
RELEASING.md
```
）。
名称必须符合Shell安全规范：无空格、无引号、无特殊字符。CLI会对文件和目录名称做校验，可执行
```
docfront --check
```
验证。
所有文档使用
```
.md
```
（Markdown）格式。
使用简短、表意清晰的名称。
相关文档归类到子目录中，子目录支持嵌套。

YAML Frontmatter

Every

.md

file must start with a YAML frontmatter block with these fields:

Field	Required	Description
`title`	Yes	A human-readable display name shown in listings.
`summary`	Recommended	One concise sentence. If the title already makes the purpose obvious, omit the summary to avoid redundancy.
`read_when`	Recommended	A YAML list of short, action-oriented hints. Each hint completes: "Read this document when you are…"

每个

.md

文件必须以包含以下字段的 YAML frontmatter 块开头：

字段	是否必填	描述
`title`	是	列表中展示的人类可读显示名称。
`summary`	推荐填写	一句简洁的说明。如果标题已经能明确体现文档用途，可省略该字段避免冗余。
`read_when`	推荐填写	YAML格式的列表，包含简短的面向操作的提示，每条提示可补全为：“当你……时阅读本文档”。

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.

markdown

---
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
---

在frontmatter的闭合

---

之后编写标准Markdown内容，正文格式没有限制 — 可按需使用标题、代码块、表格、列表等元素。

markdown

---
title: 你的标题
summary: 一句说明本文档涵盖内容的描述。
read_when:
  - 本文档适用的第一个场景
  - 第二个场景
---

Your Title Here

你的标题

Start your content here…

undefined

从这里开始编写内容…

undefined

References

参考

Installing Docfront — how to add docfront to a project.
Bootstrapping a docs/ Directory — instructions for creating a
```
docs/
```
directory from scratch by exploring the project structure.
Migrate Skills to Docfront Documentation — guide for moving internal project documentation from agent skills into
```
docs/
```
.

安装Docfront — 如何在项目中接入docfront。
初始化docs/目录 — 通过探索项目结构从零创建
```
docs/
```
目录的操作指南。
将Skill迁移到Docfront文档体系 — 将项目内部文档从Agent技能迁移到
```
docs/
```
目录的指引。