# Markdown (/academy/markdown)



Markdown is a script with stage directions.

The words stay readable in any editor. A few marks tell the lights what to do. `#` is the scene title. `**bold**` is the shout. `-` is a prop list. You can open the file in Notepad and still follow the plot.

[GitHub](/academy/github) READMEs speak it. This Academy speaks it. [Pull requests](/academy/pull-request) speak it. [CLAUDE.md](/academy/claude-md) is a `.md` because agents and humans both eat scripts, not slide decks.

**You type the marks. The stage does the rest**

No toolbar. No "heading 2" dropdown. You leave the marks in the text, so [Git](/academy/git) can diff a heading the same way it diffs a function. A Word file is a sealed crate. Markdown is the crate unpacked on the table.

That is why an agent via [MCP](/academy/mcp) or the plugin wants `.md` over a PDF. Less junk around the words. More room for the actual note.

Three marks cover a hackathon README: a title, a bold claim, a bullet list of how to run `npx create-hackhaton-space-stack@latest`. You do not need a design tool. You need a keyboard.

**Docs that travel**

Ship the README with the repo. The next laptop — teammate, judge, agent — should be able to start the show from the script. The [builder](/builder) will not write your story. The `.md` in the root will.

**What this unlocks**

Notes that survive a copy-paste into chat, a PR, and a repo.

Mark the scene. The lights will follow.