Markdown is the lingua franca of Caffeine's workflow files. READMEs, AGENTS.md, DESIGN.md, project structure docs, app content — almost every text Caffeine reads or writes is Markdown. This section explains where Markdown shows up, how Caffeine processes it, and how to use it effectively.
Markdown is not an afterthought in Caffeine — it is the primary language the agent takes context in and emits output in. Writing Markdown well gets you better builds.
> WHERE MARKDOWN SHOWS UP
Six places Markdown shows up in every Caffeine project — each with its own role:
README.md
Every Caffeine project gets a README.md at the repo root. It describes what the app does, how to start it, and which canister IDs belong to production and staging.
AGENTS.md
The AGENTS.md file gives Caffeine's build agent context about your project — conventions, forbidden patterns, build commands, where tests live. The agent reads it on every build.
DESIGN.md
When a design agent runs before the frontend, it writes a DESIGN.md with tokens, fonts, layout approach, and aesthetic notes. The frontend reads it as reference.
Project structure docs
Caffeine documents the generated structure in Markdown — which file does what, where hooks live, where components live. This helps the next build and the remix.
App content
When your app is text-heavy — a guide, a glossary, an FAQ — Caffeine often stores the content as Markdown files the frontend renders. This keeps text editable without code changes.
CHANGELOG.md
On larger iterations Caffeine writes a CHANGELOG entry in Markdown — what changed, which canisters were upgraded, which migrations ran.
> HOW CAFFEINE HANDLES MARKDOWN
Caffeine reads Markdown two ways. First, as a context file. AGENTS.md, DESIGN.md, and README.md are loaded into the agent's context at build time — the agent sees them as part of its prompt. Second, as app content. When your app renders Markdown files, Caffeine parses them at build time into HTML or React components.
For app content, Caffeine typically uses a Markdown parser like react-markdown or marked, combined with remark-gfm for tables, task lists, and strikethrough. Images in Markdown are copied into the public/assets folder at build time and served with absolute paths.
When your app is text-heavy, Markdown is often the best choice for content — you can edit it without code changes, the agent can read it on the next build, and you can export it without being locked into Caffeine.
> EXAMPLE — AGENTS.MD
A minimal AGENTS.md that gives Caffeine's build agent context. Copy it, adapt it to your project, and drop it at the repo root:
# AGENTS.md
## Project: Token-Gated Community
## Conventions
- Use TypeScript strict mode everywhere.
- Never use `any` — use `unknown` and narrow.
- All API routes return `{ ok: boolean; data?: T; error?: string }`.
## Forbidden patterns
- Do not add `rounded-xl` or `rounded-2xl` — this project uses 0-radius design.
- Do not import from `react-icons` — use `lucide-react` only.
## Build commands
- Frontend: `pnpm build` (run from src/frontend/)
- Backend: `mops build` (run from src/backend/)
- Bindings: `pnpm bindgen` (run from repo root)
## Tests
- Frontend tests: src/frontend/src/**/*.test.tsx
- Run with: `pnpm test`> EXAMPLE — APP CONTENT
When your app renders a glossary entry, the Markdown file looks like this — with YAML frontmatter for metadata and GFM for tables:
---
title: Canister
slug: canister
order: 1
---
# Canister
A **canister** is the Internet Computer's unit of computation and storage.
Think of it as a smart contract that can also hold state, serve HTTP requests,
and run WebAssembly code.
## Key properties
| Property | Value |
| -------------- | ------------------------------ |
| Language | Motoko, Rust, or any Wasm lang |
| Storage | Stable variables (orthogonal) |
| Upgrades | Safe via stable memory |
| Billing | Cycles, prepaid |
## Related terms
- [Actor model](../glossary/actor-model)
- [Stable variables](../glossary/stable-variables)> EXAMPLE — README.md
A compact README.md Caffeine generates for every project. It includes canister IDs, build commands, and a quick start:
# Token-Gated Community
A token-gated community platform running 100% on the Internet Computer.
## Canister IDs
| Environment | Frontend | Backend |
| ----------- | ------------------ | ------------------ |
| Production | ``` to be set ``` | ``` to be set ``` |
| Staging | ``` to be set ``` | ``` to be set ``` |
## Quick start
```bash
pnpm install --prefer-offline
pnpm bindgen
pnpm --filter frontend dev
```
## Build
```bash
pnpm build # builds frontend + backend
mops build # backend only (from src/backend/)
```> EXPORTING & IMPORTING
Markdown is an open standard — you are never locked into Caffeine. Export your Markdown files any time: they live as .md files in the repo, you can copy them, load them into another system, or import them into another build tool. Caffeine writes no proprietary format.
On import the same works in reverse: drop an existing README.md, AGENTS.md, or a collection of Markdown content files into the repo, and Caffeine reads them on the next build. There is no import wizard — Caffeine recognizes Markdown by file extension.
> BEST PRACTICES
Six rules that make Caffeine's Markdown processing most reliable:
STRUCTURE WITH HEADINGS
Use #, ##, ### consistently. Caffeine parses Markdown by headings to detect sections — flat structures confuse the agent.
CODE BLOCKS WITH LANGUAGE
Tag code blocks with the language — ```motoko, ```typescript, ```bash. Caffeine uses this to pick syntax highlighting and the right linter.
FRONTMATTER FOR METADATA
When Caffeine renders Markdown as app content, it often uses YAML frontmatter for title, slug, date. Keep frontmatter slim — only fields the frontend actually reads.
RELATIVE LINKS FOR INTERNAL
Link internal pages with relative paths — ../glossary.md instead of https://your-app.io/glossary. Caffeine rewrites relative links at build time, not absolute ones.
IMAGES IN PUBLIC/ASSETS
Place images Markdown references under src/frontend/public/assets/images/ and link them as /assets/images/filename.png. Caffeine copies them unchanged at build time.
KEEP SHORT, ONE IDEA PER FILE
One Markdown file, one idea. Long files break the agent's context — split them when a file grows past 300 lines.
[AGENTS.MD IS YOUR LEVER ON THE AGENT]
[MARKDOWN IS NOT A DATABASE]
// Markdown & Caffeine Checklist
- I know the six places Markdown shows up in Caffeine (README, AGENTS.md, DESIGN.md, structure docs, app content, CHANGELOG)
- I understand Caffeine reads Markdown two ways — as a context file and as app content
- I have seen the AGENTS.md template and know it is read on every build
- I know the best practices: headings, code blocks with language, frontmatter, relative links, images in public/assets, one idea per file
- I know Markdown is open — I can export any time and import into another system
- I know Markdown is for static content — for dynamic data I use a Motoko Map