agentic-markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentic Markdown

A simple way to organize and navigate Markdown so humans and agents can quickly find what matters without guesswork. It reveals details step by step, keeps structure clear and connections explicit, and helps you focus only on what’s relevant instead of reading everything.

一种用于组织和导航Markdown的简单方式，让人类和Agent无需猜测就能快速找到重要内容。它逐步展示细节，保持结构清晰、关联明确，帮助你只关注相关内容，而非通读所有内容。

Model

模型

unit: one logical context block with exactly one entrypoint
entrypoint: exactly one of
```
name.md
```
or
```
name/index.md
```
, never both
child unit: a unit reached by one structural
```
Source:
```
link from its parent
external context: non-tree units listed under
```
Dependencies
```
or
```
Related
```
inline section: short content that remains in the current entrypoint
extracted section: content moved to a child unit, leaving heading, description, and
```
Source:
```

No implicit discovery. File proximity, sibling files, directory contents, and backlinks do not define structure.

unit：一个逻辑内容块，恰好包含一个入口点
entrypoint：只能是
```
name.md
```
或
```
name/index.md
```
中的一个，不能同时存在
child unit：通过父单元的结构性
```
Source:
```
链接访问到的单元
external context：在
```
Dependencies
```
或
```
Related
```
下列出的非树形单元
inline section：保留在当前入口点中的简短内容
extracted section：移至子单元的内容，留下标题、描述和
```
Source:
```

无隐式发现机制。文件位置、同级文件、目录内容和反向链接均不定义结构。

Entrypoints

入口点

Every unit entrypoint must use this format:

---
title: Human Title
tags: [tag-a, tag-b]
---

每个单元的入口点必须遵循以下格式：

---
title: Human Title
tags: [tag-a, tag-b]
---

Human Title

Short overview of this unit.

Section Name

One or two lines describing the child content. Source: Readable Title


Frontmatter rules:

- `title` is required, string, human-readable
- `tags` is required, flat list; it may be empty
- frontmatter title and top `#` heading should match unless preserving an existing public title is more important

Child targets are also entrypoints and must follow the same format.

One or two lines describing the child content. Source: Readable Title


前置元数据规则：

- `title`为必填项，字符串类型，需便于人类阅读
- `tags`为必填项，扁平列表；可以为空
- 前置元数据中的title与顶部`#`标题应保持一致，除非保留现有公开标题更为重要

子目标同样是入口点，必须遵循相同格式。

Source Links

Source链接

Source:

is the only structural child directive.

Required form:

undefined

Source:

是唯一的结构性子指令。

必填格式：

undefined

Section Name

One or two lines explaining why this child exists. Source: Readable Title


Rules:

- must be under a section header
- must have a useful one- or two-line description before it
- must use a Markdown link with readable label text
- must use a relative path
- must point to a valid unit entrypoint
- must not point to external units, independent sibling units, URLs, anchors, or unlinked nearby files
- raw paths such as `Source: ./workflow.md` are invalid in v2

Semantics:

- defines the tree hierarchy
- participates in primary traversal
- is eligible for recursive descent when relevant
- order follows the `Source:` line order in the file

One or two lines explaining why this child exists. Source: Readable Title


规则：

- 必须位于章节标题下方
- 之前必须有一行或两行有用的描述
- 必须使用带有可读标签文本的Markdown链接
- 必须使用相对路径
- 必须指向有效的单元入口点
- 不得指向外部单元、独立同级单元、URL、锚点或未关联的邻近文件
- 在v2版本中，`Source: ./workflow.md`这类原始路径是无效的

语义：

- 定义树形层级结构
- 参与主要遍历流程
- 相关时可进行递归遍历
- 顺序遵循文件中`Source:`行的顺序

External Context

外部内容

External context is explicit and not part of the tree.

Use

Dependencies

for external units required for correct interpretation:

undefined

外部内容是明确的，不属于树形结构的一部分。

使用

Dependencies

列出正确理解所需的外部单元：

undefined

Dependencies

Document	Purpose
Glossary	Defines required terms


Use `Related` for optional expansion:

```md

Document	Purpose
Glossary	Defines required terms


使用`Related`列出可选的扩展内容：

```md

Document	Purpose
Patterns	Alternative approaches


Rules for both tables:

- must be Markdown tables with exactly `Document` and `Purpose` columns
- each row must include one relative Markdown link and a short purpose
- links must not be children of the current unit
- links are external context, not structural hierarchy

Read `Dependencies` only when ambiguity, undefined terms, or correctness needs require them. Read `Related` only when more context, comparison, or exploration is useful.

Document	Purpose
Patterns	Alternative approaches


两种表格的规则：

- 必须是包含`Document`和`Purpose`两列的Markdown表格
- 每行必须包含一个相对Markdown链接和简短用途说明
- 链接不得指向当前单元的子单元
- 链接属于外部内容，而非结构性层级结构

仅当存在歧义、未定义术语或需要确保正确性时，才阅读`Dependencies`。仅当需要更多上下文、对比或探索时，才阅读`Related`。

Traversal

遍历流程

Follow this algorithm:

Open the entrypoint.
Read frontmatter, overview, section headers, descriptions, and link labels.
If sufficient, stop.
For each relevant
```
Source:
```
, open the child entrypoint.
If ambiguity or missing prerequisite remains, open relevant
```
Dependencies
```
.
If still incomplete or expansion is useful, open relevant
```
Related
```
.
Never scan sibling files, directories, or unlinked files.

Choose relevance from section headers, descriptions, link text, target tags, and the current task. Do not auto-expand every child, dependency, or related document.

遵循以下算法：

打开入口点。
阅读前置元数据、概述、章节标题、描述和链接标签。
若信息足够，停止。
对于每个相关的
```
Source:
```
，打开子入口点。
若仍存在歧义或缺少前置条件，打开相关的
```
Dependencies
```
。
若信息仍不完整或需要扩展，打开相关的
```
Related
```
。
绝不浏览同级文件、目录或未关联文件。

根据章节标题、描述、链接文本、目标标签和当前任务判断相关性。不要自动展开每个子单元、依赖项或相关文档。

Transform Procedure

转换流程

Check the user request, explicit local constraints, and current linked graph for contradictions. If a real conflict remains, stop and ask for resolution.
Identify the unit boundary from the requested entrypoint and explicit links only.
Choose the canonical entrypoint; if both
```
name.md
```
and
```
name/index.md
```
exist for one unit, keep one and remove or convert the duplicate.
Add or repair required frontmatter on every unit entrypoint.
Inventory sections in order. Keep short sections inline; extract only coherent topics that improve scanability.
For extracted topics, preserve heading identity, choose descriptive relative paths, move content into child entrypoints, and leave description plus
```
Source:
```
.
Convert external non-child references to
```
Dependencies
```
or
```
Related
```
tables when they are needed.
Validate in the order below and fix failures before finishing.

Do not split for symmetry. Do not invent missing children only to satisfy a broken link; either create the child from real inline content or remove/inline the stub.

检查用户请求、明确的本地约束和当前链接图是否存在矛盾。若仍存在实际冲突，停止并请求解决。
仅根据请求的入口点和明确链接确定单元边界。
选择标准入口点；若一个单元同时存在
```
name.md
```
和
```
name/index.md
```
，保留其中一个，移除或转换重复项。
在每个单元入口点添加或修复所需的前置元数据。
按顺序清点章节。简短章节保留在当前入口点；仅提取能提升可读性的连贯主题。
对于提取的主题，保留标题标识，选择描述性相对路径，将内容移至子入口点，并留下描述和
```
Source:
```
。
当需要时，将外部非子引用转换为
```
Dependencies
```
或
```
Related
```
表格。
按以下顺序进行验证，修复问题后再完成转换。

不要为了对称而拆分。不要仅为了修复断链而创建不存在的子单元；要么从实际内嵌内容创建子单元，要么移除/内嵌存根。

Contradiction Stops

矛盾处理

When step 1 finds mutually exclusive requirements:

make no structural edits
name the conflicting requirements concretely
ask the user which requirement wins
report validation as skipped because the transform intentionally stopped
do not treat later transform steps as ambiguous; they are not applicable until the conflict is resolved

Read an unlinked local constraint file only when the user request, brief, or entrypoint explicitly identifies it. Otherwise, unlinked nearby files remain outside the unit.

当步骤1发现互斥要求时：

不进行任何结构性编辑
具体列出冲突的要求
询问用户应优先满足哪项要求
报告验证已跳过，因为转换已主动停止
不要将后续转换步骤视为歧义；在冲突解决前，这些步骤不适用

仅当用户请求、摘要或入口点明确指定时，才读取未关联的本地约束文件。否则，未关联的邻近文件仍属于单元外部。

Legacy Markdown

遗留Markdown转换

When converting legacy Markdown that uses multiple top-level

headings:

keep or create one document-level
```
#
```
heading from the canonical entrypoint title
convert remaining top-level topic headings to
```
##
```
sections unless they become child entrypoints
preserve the visible heading text when extracting; only sanitize filenames
keep heading order stable unless validation requires moving a child link

转换使用多个顶级

标题的遗留Markdown时：

从标准入口点标题保留或创建一个文档级
```
#
```
标题
将剩余的顶级主题标题转换为
```
##
```
章节，除非它们成为子入口点
提取时保留可见标题文本；仅清理文件名
保持标题顺序稳定，除非验证要求移动子链接

Splitting

拆分规则

keep one file by default
split when the entrypoint becomes hard to scan or a section is a coherent reusable topic
keep short residual sections inline when they are easy to scan and not reusable
prefer
```
./topic.md
```
for one coherent topic
use
```
./topic/index.md
```
only when that topic has multiple substantial subtopics that should be explicit children
never create vague files like
```
part-1.md
```
sanitize filenames, not headings;
```
FAQ / Edge Cases
```
may become
```
faq-edge-cases.md
```
preserve source order and meaning
never keep substantial duplicate truth inline and in a child

Folder-backed topics are just units whose entrypoint is

index.md

; directories are never traversed implicitly.

Shared reference files that are needed for interpretation but are not owned by the current tree should stay outside the tree and be listed in

Dependencies

. Do not absorb or duplicate them only to avoid an external context table.

默认保留为单个文件
当入口点难以浏览或某个章节是连贯的可复用主题时，进行拆分
简短的剩余章节若易于浏览且不可复用，保留在当前入口点
单个连贯主题优先使用
```
./topic.md
```
仅当该主题包含多个应明确为子单元的实质性子主题时，才使用
```
./topic/index.md
```
绝不创建
```
part-1.md
```
这类模糊命名的文件
清理文件名而非标题；
```
FAQ / Edge Cases
```
可转换为
```
faq-edge-cases.md
```
保留源顺序和含义
绝不保留大量重复内容同时存在于当前入口点和子单元中

文件夹支持的主题只是入口点为

index.md

的单元；绝不隐式遍历目录。

正确理解所需但不属于当前树形结构的共享参考文件应保留在树形结构外部，并在

Dependencies

中列出。不要仅为了避免外部内容表格而吸收或复制它们。

Validation

验证步骤

Before finishing, check:

exactly one entrypoint per unit:
```
name.md
```
or
```
name/index.md
```
every entrypoint has valid frontmatter with
```
title
```
and
```
tags
```
each entrypoint has one top
```
#
```
heading and a short overview
every
```
Source:
```
sits under a section header, has a description, and uses readable Markdown-link syntax
every
```
Source:
```
target is relative, exists, and points to a valid entrypoint
resolve every relative link from the file that contains the link, not from the root entrypoint
no
```
Source:
```
target points to
```
Dependencies
```
,
```
Related
```
, URLs, anchors, independent sibling units, or unrelated nearby docs
the
```
Source:
```
graph is acyclic
all
```
Dependencies
```
and
```
Related
```
sections are valid two-column tables with
```
Document
```
and
```
Purpose
```
every dependency/related row has a relative Markdown link and purpose text
no broken links in structural or external-context sections
no implicit filesystem discovery is required to understand the unit

Fix in this order:

duplicate entrypoints
missing or invalid frontmatter
malformed
```
Source:
```
broken links
graph cycles or wrong hierarchy
malformed external-context tables
duplicate inline/extracted truth
vague names or needless depth

完成前检查：

每个单元恰好有一个入口点：
```
name.md
```
或
```
name/index.md
```
每个入口点都包含带有
```
title
```
和
```
tags
```
的有效前置元数据
每个入口点有一个顶级
```
#
```
标题和简短概述
每个
```
Source:
```
位于章节标题下方，带有描述，并使用可读的Markdown链接语法
每个
```
Source:
```
目标为相对路径，存在且指向有效的单元入口点
从包含链接的文件解析每个相对链接，而非从根入口点
没有
```
Source:
```
目标指向
```
Dependencies
```
、
```
Related
```
、URL、锚点、独立同级单元或无关的邻近文档
```
Source:
```
图是无环的
所有
```
Dependencies
```
和
```
Related
```
章节都是包含
```
Document
```
和
```
Purpose
```
的有效两列表格
每个依赖项/相关项行都包含相对Markdown链接和用途文本
结构性或外部内容章节中无断链
理解单元无需依赖隐式文件系统发现

按以下顺序修复问题：

重复入口点
缺失或无效的前置元数据
格式错误的
```
Source:
```
断链
图循环或错误层级
格式错误的外部内容表格
当前入口点与子单元中的重复内容
模糊命名或不必要的层级深度

Backlinks

反向链接

Backlinks are optional and non-canonical. If needed, generate them outside source files. They must never affect traversal or validation.

反向链接是可选的，且非标准。若需要，在源文件外部生成。它们绝不能影响遍历或验证。

Output

输出内容

Report:

final tree
external context sections touched
validation result
files changed
any intentionally inline large section and why it stayed inline

报告：

最终树形结构
涉及的外部内容章节
验证结果
已更改的文件
任何有意保留在当前入口点的大型章节及其原因