markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown

"The source is the destination. Readable raw AND rendered."

"源文件即最终产物，原生状态和渲染后均具备可读性。"

What Is It?

什么是Markdown？

Markdown is the plain text format that powers MOOLLM's human-readable files. It's not just formatting — it's a philosophy:

Readable without rendering — Open SESSION.md in any editor, understand it instantly
Readable when rendered — GitHub, Obsidian, browsers enhance but don't transform
LLM-native — Models are trained on billions of Markdown files; they speak it fluently
Git-friendly — Diffs are meaningful, merges work, history is readable
No lock-in — Plain text survives every platform, every decade

Markdown是为MOOLLM的人类可读文件提供支持的纯文本格式。它不只是一种格式——更是一种理念：

无需渲染即可阅读——在任意编辑器中打开SESSION.md，就能立刻理解其内容
渲染后同样易读——GitHub、Obsidian、浏览器会优化显示，但不会改变内容本质
LLM原生适配——模型在数十亿份Markdown文件上训练，能流畅处理这种格式
Git友好——差异对比清晰，合并操作顺畅，历史记录可读性强
无锁定限制——纯文本格式可在任意平台留存，历经数十年仍能使用

Why Markdown Won

Markdown为何脱颖而出

From Anil Dash's "How Markdown Took Over the World" (January 2025):

摘自Anil Dash的《Markdown如何风靡全球》（2025年1月）：

The 10 Technical Reasons

10项技术层面的原因

Reason	Explanation	MOOLLM Parallel
1. Great brand	"Markdown" = opposite of "markup"	YAML Jazz, SOUL-CHAT, K-lines
2. Solved a real problem	HTML too verbose for blogging	YAML too rigid; comments add soul
3. Built on existing behaviors	Email formatting conventions	Indentation, `#` headers already intuitive
4. Mirrored RSS in origin	Curmudgeonly creators, blog platforms	Open source, community-driven
5. Community ready to help	Dean Allen (Textile), Aaron Swartz	Skill contributions, open protocols
6. Flavors for context	GFM, CommonMark, etc.	Adventure YAML vs. session markdown
7. Time of behavior change	Blogging era = new habits	LLM era = new habits
8. Build tool era	Markdown → HTML in pipelines	YAML → JSON → Browser
9. Works with "view source"	Inspectable source	Files as state, transparent
10. No IP encumbrance	Free, no patents	MIT license everywhere

原因	解释	MOOLLM对应实践
1. 绝佳的品牌定位	"Markdown"与"markup（标记语言）"形成鲜明反差	YAML Jazz、SOUL-CHAT、K-lines
2. 解决实际问题	HTML对于博客写作过于冗长	YAML过于刻板；注释为内容注入灵魂
3. 基于已有使用习惯	沿用邮件格式规范	缩进、 `#` 标题等设计本就符合直觉
4. 起源与RSS理念契合	由特立独行的创作者和博客平台推动	开源、社区驱动
5. 社区积极助力	Dean Allen（Textile）、Aaron Swartz等贡献者	Skill贡献、开放协议
6. 针对场景衍生多种变体	GFM、CommonMark等	Adventure YAML与会话Markdown
7. 契合行为习惯变革时机	博客时代催生新的使用习惯	LLM时代带来新的行为模式
8. 适配构建工具时代	Markdown可通过流水线转换为HTML	YAML→JSON→浏览器
9. 支持“查看源代码”	源代码可被直接查看	文件即状态，完全透明
10. 无知识产权限制	免费、无专利约束	全平台采用MIT许可证

The Key Insight

核心洞察

"If markup is complicated, then the opposite of that complexity must be... markdown." — Anil Dash

"如果markup（标记语言）复杂繁琐，那么与之相反的必然是markdown（简化标记）。" — Anil Dash

Markdown in MOOLLM

Markdown在MOOLLM中的应用

Session Logs

会话日志

markdown

undefined

markdown

undefined

Session: Adventure Uplift

📑 Index

概述
决策

1. Overview

1. 概述

<details open> <summary>🎯 Mission</summary>

Build

adventure.py

to compile adventures to web apps.

</details> <details open> <summary>📋 Technical Details</summary>

Architecture decisions go here...

</details> ```

开发

adventure.py

将冒险内容编译为Web应用。

</details> <details open> <summary>📋 技术细节</summary>

架构决策内容置于此处...

</details> ```

READMEs

README文档

markdown

undefined

markdown

undefined

Skill Name

Skill名称

"One-liner that captures the essence"

"一句提炼核心本质的标语"

What Is It?

是什么？

Brief explanation.

When to Use

适用场景

Scenario 1
Scenario 2

场景1
场景2

Dovetails With

GitHub-Flavored Markdown (GFM)

GitHub风格Markdown（GFM）

MOOLLM session logs use GFM extensions:

MOOLLM会话日志使用GFM扩展：

Tables

表格

markdown

| Feature | Status |
|---------|--------|
| Navigation | ✅ Done |
| Inventory | 🚧 WIP |

markdown

| 功能 | 状态 |
|---------|--------|
| 导航 | ✅ 已完成 |
| 物品栏 | 🚧 开发中 |

Task Lists

任务列表

markdown

- [x] Define schema
- [ ] Build linter
- [ ] Compile to JSON

markdown

- [x] 定义数据结构
- [ ] 构建代码检查工具
- [ ] 编译为JSON格式

Collapsible Sections

可折叠区块

html

<details open>
<summary>Click to expand</summary>

Hidden content goes here.

</details>

html

<details open>
<summary>点击展开</summary>

隐藏内容置于此处。

</details>

Syntax Highlighting

语法高亮

markdown

```python
def hello():
    print("Hello, world!")
```

markdown

```python
def hello():
    print("Hello, world!")
```

Alerts (GitHub-specific)

提示框（GitHub专属）

markdown

> [!NOTE]
> Useful information.

> [!WARNING]
> Critical information.

markdown

> [!NOTE]
> 实用信息。

> [!WARNING]
> 关键信息。

Mermaid Diagrams

Mermaid图表

GitHub renders Mermaid diagrams natively! Perfect for:

Flowcharts
Sequence diagrams
State machines
Entity relationships
Architecture diagrams

markdown

```mermaid
flowchart TD
    YAML[YAML Microworld] --> Python[Python Loader]
    Python --> JSON[adventure.json]
    JSON --> Browser[Browser Engine]
    Browser --> Player[Player Experience]
```

Renders as:

mermaid

flowchart TD
    YAML[YAML Microworld] --> Python[Python Loader]
    Python --> JSON[adventure.json]
    JSON --> Browser[Browser Engine]
    Browser --> Player[Player Experience]

GitHub原生支持Mermaid图表渲染！非常适合绘制：

流程图
时序图
状态机
实体关系图
架构图

markdown

```mermaid
flowchart TD
    YAML[YAML Microworld] --> Python[Python Loader]
    Python --> JSON[adventure.json]
    JSON --> Browser[Browser Engine]
    Browser --> Player[Player Experience]
```

渲染效果：

mermaid

flowchart TD
    YAML[YAML Microworld] --> Python[Python Loader]
    Python --> JSON[adventure.json]
    JSON --> Browser[Browser Engine]
    Browser --> Player[Player Experience]

Common Mermaid Patterns

常用Mermaid图表模板

Flowchart (process flow):

mermaid

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Sequence diagram (interactions):

mermaid

sequenceDiagram
    Player->>Room: LOOK
    Room->>Objects: Query visible
    Objects-->>Room: [lamp, key]
    Room-->>Player: Description + objects

State diagram (room states):

mermaid

stateDiagram-v2
    [*] --> start
    start --> maze: GO NORTH
    maze --> end: SOLVE PUZZLE
    maze --> maze: WANDER
    end --> [*]

Entity relationship (data model):

mermaid

erDiagram
    ROOM ||--o{ OBJECT : contains
    ROOM ||--o{ EXIT : has
    CHARACTER ||--o{ OBJECT : carries
    EXIT }o--|| ROOM : leads_to

流程图（流程展示）：

mermaid

flowchart LR
    A[开始] --> B{决策点}
    B -->|是| C[操作1]
    B -->|否| D[操作2]
    C --> E[结束]
    D --> E

时序图（交互展示）：

mermaid

sequenceDiagram
    Player->>Room: 查看
    Room->>Objects: 查询可见物品
    Objects-->>Room: [灯, 钥匙]
    Room-->>Player: 场景描述 + 物品列表

状态图（房间状态）：

mermaid

stateDiagram-v2
    [*] --> start
    start --> maze: 向北走
    maze --> end: 解开谜题
    maze --> maze: 四处游荡
    end --> [*]

实体关系图（数据模型）：

mermaid

erDiagram
    ROOM ||--o{ OBJECT : 包含
    ROOM ||--o{ EXIT : 拥有
    CHARACTER ||--o{ OBJECT : 携带
    EXIT }o--|| ROOM : 通往

LLMs and Markdown

LLMs与Markdown

From Hacker News discussion (January 2025):

"It's fundamentally text. No format/vendor lock-in and very amenable to living in a git repo. I can tell an LLM to look at the code in this repo and make me an API_documentation.md and it'll grasp that I want a text-based summary." — @Havoc

摘自Hacker News 2025年1月的讨论：

"它本质就是文本。没有格式/供应商锁定问题，非常适合存放在Git仓库中。我可以让LLM查看仓库中的代码，为我生成一份API_documentation.md，它能理解我想要的是一份基于文本的摘要。" — @Havoc

Why LLMs Prefer Markdown

LLMs为何偏好Markdown

Property	Benefit
Training data	Billions of .md files in training corpus
Structure	Headers, lists, code blocks = clear semantics
Low overhead	No bracket matching (unlike JSON)
Comments in code blocks	Context preserved
Human-readable	Model can "think out loud" naturally

特性	优势
训练数据	训练语料中包含数十亿份.md文件
结构化	标题、列表、代码块具备清晰的语义
低学习成本	无需匹配括号（与JSON不同）
代码块中的注释	上下文信息得以保留
人类可读	模型可以自然地“清晰思考”

LLM Output Patterns

LLM输出模式

LLMs naturally output:

```
#
```
headers for sections
```
-
```
bullets for lists
code
```
undefined
```
```
**bold**
```
for emphasis
Tables for structured comparisons

Match this in your prompts — write instructions in Markdown, get Markdown back.

LLMs会自然输出：

```
#
```
标题用于划分章节
```
-
```
项目符号用于列表
```
undefined
```
```
**加粗**
```
用于强调
表格用于结构化对比

在提示词中匹配这种风格——用Markdown编写指令，就能得到Markdown格式的返回结果。

The "Source is Destination" Principle

“源文件即最终产物”原则

Markdown's power: it's both the source AND the readable output.

Format	Source	Destination	Gap
LaTeX	`.tex`	PDF	Large
HTML	`.html`	Browser	Medium
Markdown	`.md`	`.md` (or rendered)	None

This is why YAML Jazz matters:

yaml

undefined

Markdown的强大之处：它既是源文件，也是可读的最终输出。

格式	源文件	最终产物	差距
LaTeX	`.tex`	PDF	巨大
HTML	`.html`	浏览器渲染结果	中等
Markdown	`.md`	`.md` （或渲染后结果）	无

这也是YAML Jazz的重要性所在：

yaml

undefined

This comment is readable in the source

这段注释在源文件中可读

AND visible to the LLM

同时能被LLM识别

AND preserved in the file

并在文件中永久保留

config: setting: value


The source IS the documentation. The documentation IS the source.

---

config: setting: value


源文件即文档，文档即源文件。

---

Best Practices for MOOLLM

MOOLLM最佳实践

1. Indexes at Top

1. 文档顶部添加索引

Long documents need navigation:

markdown

undefined

长文档需要导航功能：

markdown

undefined

📑 Index

📑 索引

Section One
Section Two

第一部分
第二部分

Section One

第一部分

...

undefined

...

undefined

2. Collapsible Details (CRITICAL!)

2. 使用可折叠详情块（至关重要！）

This is one of Markdown's superpowers. Hide complexity, show structure. Let readers scan summaries without drowning in details.

html

<details open>
<summary><strong>🎯 Important Section — Open by Default</strong></summary>

Critical content that readers need to see immediately.

</details>

<details open>
<summary><strong>📋 Technical Details — Collapsed by Default</strong></summary>

Dense content that only some readers need.
Click to expand when curious.

</details>

这是Markdown的超能力之一。隐藏复杂内容，展示结构框架。让读者无需沉浸在细节中，就能快速浏览摘要。

html

<details open>
<summary><strong>🎯 重要章节——默认展开</strong></summary>

读者需要立即查看的关键内容。

</details>

<details>
<summary><strong>📋 技术细节——默认折叠</strong></summary>

仅部分读者需要的密集内容。
感兴趣时点击展开。

</details>

LLM-Generated Summaries in

<summary>

Nesting Collapsibles

嵌套可折叠区块

For complex documents, nest sections:

html

<details open>
<summary><strong>📚 Part 1: The Gathering</strong></summary>

Overview of who attended...

<details open>
<summary>Living Legends (25 people)</summary>

Full list with bios...

</details>

<details open>
<summary>Memorial Candles (10 people)</summary>

Those speaking through memory...

</details>

</details>

对于复杂文档，可使用嵌套结构：

html

<details open>
<summary><strong>📚 第一部分：集合</strong></summary>

参会人员概述...

<details open>
<summary>传奇人物（25人）</summary>

完整名单及简介...

</details>

<details open>
<summary>纪念人物（10人）</summary>

通过回忆分享观点的人物...

</details>

</details>

When to Use Each Pattern

不同模式的适用场景

Pattern	Use When
`<details open>`	Main content, must-read sections
`<details open>` (closed)	Supporting details, optional depth
Nested `<details open>`	Hierarchical information (parts > chapters > sections)
Summary with key points	Reader can decide without opening
Summary with just title	Section is self-explanatory

模式	适用场景
`<details open>`	核心内容、必读章节
`<details>`	辅助细节、可选深度内容
嵌套 `<details>`	层级化信息（部分 > 章节 > 小节）
包含关键点的摘要	读者无需展开即可判断是否感兴趣
仅含标题的摘要	章节内容一目了然

The Session Log Pattern

会话日志模式

MOOLLM session logs use this extensively:

html

undefined

MOOLLM会话日志广泛使用该模式：

html

undefined

5. Free-For-All Q&A

5. 自由问答环节

<details open> <summary>🎤 Highlights from the Chaos — Scott on 16KB, Will on distributed AI, Hofstadter on strange loops</summary>

<details open> <summary>🎤 精彩亮点——Scott谈16KB、Will谈分布式AI、Hofstadter谈怪圈</summary>

On Distributed Intelligence

关于分布式智能

SCOTT ADAMS: "Wait — schemas are literally what I fit in sixteen kilobytes in 1978!"

WILL WRIGHT: "We distributed intelligence INTO THE OBJECTS..."

...full transcript...

</details> ```

The reader sees:

Section title
Key topics covered
Can skip if not interested, or expand for full content

This is why session logs are readable even at 7000+ lines!

SCOTT ADAMS：“等等——我在1978年就把Schema机制塞进了16KB的空间里！”

WILL WRIGHT：“我们把智能分布式到了对象中...”

...完整记录...

</details> ```

读者会看到：

章节标题
涵盖的关键主题
若不感兴趣可直接跳过，或展开查看完整内容

这就是为何即使会话日志长达7000+行，仍具备良好可读性的原因！

3. Tables for Structured Data

3. 使用表格展示结构化数据

When you have parallel information:

markdown

| Room | Objects | Exits |
|------|---------|-------|
| start | lamp, key | north |
| maze | torch | north, south, east |

当存在平行信息时：

markdown

| 房间 | 物品 | 出口 |
|------|---------|-------|
| 起点 | 灯、钥匙 | 北 |
| 迷宫 | 火把 | 北、南、东 |

4. Code Blocks for Examples

4. 使用代码块展示示例

Always use fenced code blocks with language hints:

markdown

```yaml
name: example
```

```python
def example():
    pass
```

始终使用带语言标识的围栏式代码块：

markdown

```yaml
name: example
```

```python
def example():
    pass
```

5. Blockquotes for Quotes/Emphasis

5. 使用块引用展示引用内容/强调信息

markdown

> *"The filesystem IS the microworld."*
> — MOOLLM Constitution

markdown

> *"文件系统即微世界。"*
> — MOOLLM 准则

Anti-Patterns

反模式

❌ Over-nesting headers — More than 4 levels is confusing
❌ Inline HTML everywhere — Defeats plain-text readability
❌ No structure — Wall of text without headers/sections
❌ Proprietary extensions — Stick to GFM for portability
❌ Rendered-only thinking — If it's unreadable raw, rethink it

❌ 过度嵌套标题——超过4级标题会造成混淆
❌ 过度使用内嵌HTML——破坏纯文本可读性
❌ 缺乏结构——无标题/章节的大段文字
❌ 使用专有扩展——为了可移植性，坚持使用GFM
❌ 仅考虑渲染效果——若原生状态下不可读，需重新设计

The Durability Argument

持久性论证

From HN:

"I don't want to worry about whatever cursed format OneNote uses still being something I can extract in 2035." — @Havoc

Markdown files from 2004 are still readable today. They'll be readable in 2045. Plain text is forever.

MOOLLM session logs, skill files, and READMEs will outlive any proprietary format.

摘自HN：

"我不想担心OneNote使用的那种诡异格式，到2035年还能不能提取出内容。" — @Havoc

2004年的Markdown文件至今仍能读取。到2045年也依然可以。纯文本永存。

MOOLLM会话日志、Skill文件和README文档的寿命将远超任何专有格式。

Dovetails With

Protocol Symbol

协议标识

MARKDOWN

Invoke when: Writing documentation, session logs, READMEs, or any human-readable prose.

MARKDOWN

调用场景：编写文档、会话日志、README或任意人类可读的叙事内容时。

Credits

致谢

John Gruber — Creator of Markdown (2004)
Aaron Swartz — Beta tester, helped refine the format
Dean Allen — Textile (prior art, inspiration)
GitHub — GFM, mass adoption
Anil Dash — "How Markdown Took Over the World" (2025)
CommonMark — Standardization effort

"The trillion-dollar AI industry's system for controlling their most advanced platforms is a plain text format one guy made up for his blog and then bounced off of a 17-year-old kid before sharing it with the world for free." — Anil Dash

John Gruber——Markdown创始人（2004年）
Aaron Swartz——测试版参与者，助力完善格式
Dean Allen——Textile（先驱，灵感来源）
GitHub——GFM格式，推动大规模普及
Anil Dash——《Markdown如何风靡全球》（2025年）
CommonMark——标准化组织

"价值万亿美元的AI产业，控制其最先进平台的系统，竟是一个人为自己博客设计、经17岁少年打磨后免费分享给全世界的纯文本格式。" — Anil Dash

markdown

Original

Translation

Markdown

Markdown

What Is It?

什么是Markdown？

Why Markdown Won

Markdown为何脱颖而出

The 10 Technical Reasons

10项技术层面的原因

The Key Insight

核心洞察

Markdown in MOOLLM

Markdown在MOOLLM中的应用

Session Logs

会话日志

Session: Adventure Uplift

Session: Adventure Uplift

📑 Index

📑 索引

1. Overview

1. 概述

READMEs

README文档

Skill Name

Skill名称

What Is It?

是什么？

When to Use

适用场景

Dovetails With

相关关联技能

Embedded Data

嵌入式数据

GitHub-Flavored Markdown (GFM)

GitHub风格Markdown（GFM）

Tables

表格

Task Lists

任务列表

Collapsible Sections

可折叠区块

Syntax Highlighting

语法高亮

Alerts (GitHub-specific)

提示框（GitHub专属）

Mermaid Diagrams

Mermaid图表

Common Mermaid Patterns

常用Mermaid图表模板

LLMs and Markdown

LLMs与Markdown

Why LLMs Prefer Markdown

LLMs为何偏好Markdown

LLM Output Patterns

LLM输出模式

The "Source is Destination" Principle

“源文件即最终产物”原则

This comment is readable in the source

这段注释在源文件中可读

AND visible to the LLM

同时能被LLM识别

AND preserved in the file

并在文件中永久保留

Best Practices for MOOLLM

MOOLLM最佳实践

1. Indexes at Top

1. 文档顶部添加索引

📑 Index

📑 索引

Section One

第一部分

2. Collapsible Details (CRITICAL!)

2. 使用可折叠详情块（至关重要！）

LLM-Generated Summaries in <summary> Tags

在<summary>标签中使用LLM生成的摘要

Nesting Collapsibles

嵌套可折叠区块

When to Use Each Pattern

LLM-Generated Summaries in
`<summary>`
Tags

在
`<summary>`
标签中使用LLM生成的摘要