How Markdown Works

The simple syntax that became the lingua franca between humans and AI

Plain Text, Rich Meaning

Markdown is a lightweight markup language created by John Gruber in 2004, with significant contributions from Aaron Swartz. Its genius lies in its simplicity: the syntax is readable even before rendering.

Unlike HTML, XML, or LaTeX, Markdown was designed for humans first. You can read a .md file in any text editor and immediately understand its structure. No angle brackets. No closing tags. Just intuitive punctuation that mirrors how people naturally format text.

This readability-first design turned out to be prophetic. Two decades later, it's exactly what makes Markdown the perfect format for communicating with AI systems.

# Heading

Some text with **bold** words.

↓

Heading

Some text with bold words.

The Complete Syntax

Markdown's core syntax fits on an index card. That's intentional—constraints breed creativity and ensure universal readability.

# Heading 1Top-level heading

## Heading 2Section heading

**bold text**Strong emphasis

*italic text*Emphasis

`inline code`Code snippet

[link](url)Hyperlink

![alt](image.png)Image

- list itemUnordered list

1. numberedOrdered list

> quoteBlockquote

---Horizontal rule

[[wikilink]]Internal link (extended)

Try It Yourself

Edit the markdown on the left and watch it transform in real-time. Notice how the raw text remains readable even without rendering.

Markdown Input

Rendered Output

Why LLMs Love Markdown

Markdown didn't become the interface layer between humans and AI by accident. Its properties align perfectly with how language models process and generate text.

📐

Structured but Flexible

Markdown provides just enough structure for LLMs to parse intent without being overly rigid. Headings create hierarchy. Lists organize ideas. Code blocks isolate syntax. But there's no schema to validate, no required fields—just natural organization.

⚡

Token Efficient

In a world where context windows are precious, every token matters. Markdown is minimal: a heading is '# Title' not '<h1>Title</h1>'. Bold is '**word**' not '<strong>word</strong>'. This efficiency compounds across long documents.

🧠

Native to Training Data

LLMs learned from the internet, and the internet runs on Markdown. GitHub READMEs, Stack Overflow answers, documentation sites, personal blogs—billions of well-structured Markdown documents in the training corpus.

↔️

Bi-directional Clarity

LLMs can both parse and generate Markdown fluently. When an AI responds with a code block or a bulleted list, it's not fighting the format—it's using the same syntax it learned to recognize as meaningful structure.

The Token Math

HTML (~54 tokens):

<h1>Title</h1><p>Text with <strong>bold</strong>.</p>

Markdown (~12 tokens):

# Title\n\nText with **bold**.

Same semantic meaning, ~4.5x fewer tokens. At scale, this difference is massive.

CLAUDE.md: Teaching AI About Your Code

When you work with Claude Code, it automatically looks for a CLAUDE.md file in your project root. This simple markdown file becomes the AI's understanding of your codebase—a persistent briefing document that survives across sessions.

Think about what you'd tell a new developer on day one:

→ Project overview — what does this code actually do?
→ Key commands — how to run, test, deploy
→ Architecture — where things live and why
→ Conventions — the unwritten rules
→ Current focus — what we're working on now

A well-crafted CLAUDE.md dramatically improves AI assistance because context is everything. The AI doesn't have to guess or infer—you've told it directly.

CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code
when working with this repository.

## Project Overview
A Next.js application for real-time
collaborative document editing.
Built with TypeScript, Prisma, and WebSockets.

## Key Commands
- `npm run dev` - Start development server
- `npm run test` - Run test suite
- `npm run db:migrate` - Run database migrations

## Architecture
- /src/app - Next.js app router pages
- /src/components - React components
- /src/lib - Shared utilities
- /src/hooks - Custom React hooks

## Code Conventions
- Use TypeScript strict mode
- Prefer named exports over default exports
- Use Tailwind CSS for styling

## Current Focus
Implementing real-time cursor presence.
See /docs/cursor-presence.md for spec.

The Context Hierarchy

AI assistants don't just read one file—they build understanding from multiple layers of markdown context. Each layer adds specificity.

CLAUDE.md Project root Global project context, conventions, architecture overview

README.md Any directory Directory-specific documentation, often auto-discovered

docs/*.md Documentation folder Deep dives on specific topics, technical specs

~/.claude/config.md User home Personal preferences that apply across all projects

meeting-notes.md

# Meeting Notes - Jan 2026

## Attendees
- [[Alice Chen]] - Engineering Lead
- [[Bob Martinez]] - Product Manager
- [[Carol Wu]] - Design Lead

## Context
Follow-up to [[2026-01-15 Planning Session]].
Reviewing progress on [[Project Atlas]].

## Discussion Topics

### 1. Authentication Overhaul
We need to migrate from [[Legacy Auth]]
to [[OAuth 2.0]].
- Timeline: 2 weeks
- Owner: [[Alice Chen]]

### 2. Q1 Priorities
Finalized in [[Q1 2026 Roadmap]]:
- [ ] Complete [[Feature: Real-time Sync]]
- [ ] Launch [[Feature: Export to PDF]]

## Related Notes
- [[Previous Meeting - Jan 8]]
- [[Technical Debt Register]]

Obsidian: Markdown as Knowledge Graph

Obsidian demonstrates what happens when you treat markdown files as nodes in a graph. The magic ingredient? [[wikilinks]].

Every [[link]] creates a bidirectional connection. Link to a page that doesn't exist? Obsidian creates it. Rename a file? All links update automatically. Your notes become an interconnected web—a second brain built from plain text.

The graph emerges from syntax:

[[Alice Chen]] → links to Alice Chen.md

[[Project Atlas]] → links to Project Atlas.md

[[2026-01-15 Planning]] → links to dated note

This is the same principle that makes markdown powerful for AI: relationships are explicit in the text itself. No external database. No proprietary format. Just text files with meaningful connections.

From Files to Networks

When every link is a connection, your file system becomes a queryable knowledge graph.

📄

Files as Nodes

Each .md file is a node. Its filename is its identity. Its content is its knowledge.

🔗

Links as Edges

[[wikilinks]] create edges between nodes. Bidirectional by default. Traversable both ways.

🌐

Folders as Clusters

Directory structure provides natural clustering. /projects/, /people/, /meetings/ become semantic groupings.

Your File System Is Already a Context Graph

Here's the insight most people miss: a folder structure is already a knowledge graph. Directories are categories. Files are entities. Paths encode hierarchical relationships.

When an AI reads your project, it's not just seeing code—it's building a mental model of how everything connects. The .md files are the semantic layer that explains the structure.

README.md → project entry point, first thing anyone reads

CLAUDE.md → AI-specific context, how to work here

CONTRIBUTING.md → how to participate, code standards

docs/*.md → deep knowledge, specs, guides

📂 my-project

📄 CLAUDE.md

📄 README.md

📄 CONTRIBUTING.md

📂 docs

📄 architecture.md

📄 api-reference.md

📄 deployment.md

📂 src

📄 index.ts

📄 utils.ts

📄 types.ts

📄 package.json

.md Files as the Semantic Layer

Code files tell you what the system does. Markdown files tell you why and how to think about it. This distinction matters enormously for AI.

Code tells you:

Function signatures and implementations
Data structures and types
Control flow and logic
Dependencies and imports

Markdown tells you:

Why this architecture was chosen
What problems this solves
How to extend or modify safely
What conventions to follow

.md Files Are the Lifeblood

In the age of AI-assisted development, markdown files aren't just documentation—they're the interface between human intent and machine understanding.

For Humans

Readable without special software
Version control shows meaningful diffs
Works in any editor on any platform
No vendor lock-in, ever
Searchable with simple grep
Portable across decades

For AI

Structured yet natural language
Semantic hierarchy from headers
Links express relationships explicitly
Token efficient for context windows
Familiar from training data
Easy to generate and parse

"The best format for human-AI collaboration is one that both can read, write, and understand without translation."

That format is Markdown.

Practical Tips

How to write markdown that works well for both humans and AI systems.

Use headers for hierarchy

✗ Write everything in paragraphs without structure

✓ Use # for main topics, ## for subtopics, ### for details

Be explicit about context

✗ Assume the reader knows the background

✓ Include a brief overview section explaining what and why

Link related concepts

✗ Mention related files without linking

✓ Use [[wikilinks]] or [relative links](./path.md) to connect

Keep it current

✗ Let documentation drift from reality

✓ Update docs when code changes; outdated context hurts more than none

Start Writing

The best way to understand markdown is to use it. Create a CLAUDE.md for your next project. Let your file system tell a story. Build your second brain.

# Your turn

View this page as plain markdown →