Markdown

Markdown

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

What Is It?

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

Why Markdown Won

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

The 10 Technical Reasons

The Key Insight

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

Markdown in MOOLLM

Session Logs

# Session: Adventure Uplift

## 📑 Index
1. [Overview](#1-overview)
2. [Decisions](#2-decisions)

---

## 1. Overview

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

Build `adventure.py` to compile adventures to web apps.

</details>

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

Architecture decisions go here...

</details>

READMEs

# Skill Name

> *"One-liner that captures the essence"*

## What Is It?
Brief explanation.

## When to Use
- Scenario 1
- Scenario 2

## Dovetails With
- [related-skill/](../related-skill/)

Embedded Data

Markdown + YAML code blocks = structured data in narrative:

Here's the configuration:

​```yaml
rooms:
  - start
  - maze
  - end
​```

And the reasoning behind it...

GitHub-Flavored Markdown (GFM)

MOOLLM session logs use GFM extensions:

Tables

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

Task Lists

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

Collapsible Sections

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

Hidden content goes here.

</details>

Syntax Highlighting

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

Alerts (GitHub-specific)

> [!NOTE]
> Useful information.

> [!WARNING]
> Critical information.

Mermaid Diagrams

GitHub renders Mermaid diagrams natively! Perfect for:

• Flowcharts
• Sequence diagrams
• State machines
• Entity relationships
• Architecture diagrams

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

Renders as:

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

Common Mermaid Patterns

Flowchart (process flow):

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

Sequence diagram (interactions):

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

State diagram (room states):

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

Entity relationship (data model):

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

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

Why LLMs Prefer Markdown

LLM Output Patterns

LLMs naturally output:

• # headers for sections
• - bullets for lists
• **bold** for emphasis
• Tables for structured comparisons

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

The "Source is Destination" Principle

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

This is why YAML Jazz matters:

# This comment is readable in the source
# AND visible to the LLM
# AND preserved in the file
config:
  setting: value

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

Best Practices for MOOLLM

1. Indexes at Top

Long documents need navigation:

## 📑 Index

1. [Section One](#section-one)
2. [Section Two](#section-two)

---

## Section One
...

2. Collapsible Details (CRITICAL!)

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

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

LLM-Generated Summaries in <summary> Tags

Key insight: The <summary> tag should contain a descriptive summary that tells readers what's inside WITHOUT opening. LLMs are great at generating these!

Bad:

<details open>
<summary>Click to see more</summary>
...content...
</details>

Good:

<details open>
<summary><strong>🎤 Gary Drescher's Talk — Schema Mechanism + LLM = Flight</strong></summary>

Full transcript of Gary explaining how LLMs complete what Made-Up Minds started...

</details>

Even better — with key points in summary:

<details open>
<summary><strong>🏗️ Architecture Decisions</strong> — YAML source, JSON compile, SPA output, staged development</summary>

Detailed architecture documentation...

</details>

Nesting Collapsibles

For complex documents, nest sections:

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

When to Use Each Pattern

The Session Log Pattern

MOOLLM session logs use this extensively:

## 5. Free-For-All Q&A

<details open>
<summary><strong>🎤 Highlights from the Chaos</strong> — Scott on 16KB, Will on distributed AI, Hofstadter on strange loops</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!

3. Tables for Structured Data

When you have parallel information:

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

4. Code Blocks for Examples

Always use fenced code blocks with language hints:

​```yaml
name: example
​```

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

5. Blockquotes for Quotes/Emphasis

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

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

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.

Dovetails With

• yaml-jazz/ — YAML is the data; Markdown is the prose
• session-log/ — Session logs are Markdown documents
• plain-text/ — The broader philosophy
• soul-chat/ — Markdown with embedded YAML
• postel/ — Be liberal in accepting Markdown variants

Protocol Symbol

MARKDOWN

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

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