Markdown tutorial

Write clean Markdown that reads well for people, renders the same everywhere, and steers AI agents, then export a Markdown kit for your own repo.

Start the course

Course contents

Markdown Fundamentals

  1. Markdown Basics — See the same note as plain text, rich text and Markdown. Learn the three readers of every Markdown file, why Markdown survives copy and paste and code review, why AI tools use it, and when to use JSON instead.
  2. Headings and Paragraphs — Write headings, paragraphs and line breaks that render the way you expect. Fix a release note whose line breaks disappear, learn the six heading levels, force a new line with a backslash, use bold and italic, and see why headings matter to AI agents.
  3. Lists and Nesting — Write bullet, numbered and task lists that stay together. Repair a setup guide whose nested list collapsed, learn the indent rule, keep notes and code inside a step, and pick the list type an AI agent will read correctly.
  4. Links and Images — Write links and images that work. Fix three broken links, use relative links between project files and links to headings, keep long addresses in reference links, and write alt text that people and AI agents can use.
  5. Code Blocks — Show commands and code exactly as typed. Fix a code block that swallowed the page, write inline code and fenced blocks, add language hints, nest fences safely, and write commands people and agents can copy.
  6. Tables and Quotes — Build tables that render where you need them. See why a table breaks outside GitHub and loses cells, align columns, escape pipes, decide when a list beats a table, and write quotes, dividers and strikethrough.
  7. Escaping and HTML — Stop Markdown from changing text you meant literally. Escape marks with a backslash, find the characters that cause trouble mid-line and at the start of a line, keep angle brackets from vanishing, use HTML tags and comments safely, and test yourself with a predict-the-render quiz.

Markdown for Teams

  1. Markdown Flavors — Render one README as CommonMark, as GitHub Flavored Markdown and on a docs site. Learn the four layers of Markdown, what GFM adds, which features are platform extensions, what each one falls back to, and how to write a file that works everywhere.
  2. Docs as Code — Treat docs like code. Lint a docs page with fourteen problems, lay out a docs folder, write a README that answers the first five questions, write one sentence per line for clean diffs, and add Mermaid diagrams and alerts.
  3. Frontmatter Basics — Write the YAML block at the top of a Markdown file. Fix a title that breaks the parser, learn keys, values, quotes, lists, groups and long text, catch the traps that silently change data, and see why AI skills depend on frontmatter.

AI-Native Markdown

  1. AGENTS.md Files — Write the AGENTS.md file AI coding agents read at the start of every session. Prune a 156-line file to the facts the code cannot say, apply the always-on test, share one file with CLAUDE.md and Cursor rules, and use nested files in bigger repos.
  2. Skills and Subagents — Write a SKILL.md that gets picked for the right tasks. Fix a skill whose vague description never loads, follow the name rules, write a description with what, when and when not, keep the body small with progressive disclosure, and write a reviewer subagent file.
  3. Specs and Plans — Turn a vague ticket into a spec an agent can build from. Write a goal, non-goals, requirements and checkable acceptance criteria, remove vague words and open questions, and write plans, decision records and reusable prompt files.
  4. LLM-Friendly Docs — Write docs that AI tools can find their way through. Fix a page whose answer a chatbot missed, give each section a heading that names its topic, make sections stand alone, and write an llms.txt that maps your docs.
  5. Cleaning AI Output — Fix the Markdown that AI tools write. Clean an answer buried in bold, headings, nested bullets and emoji, repair broken tables, adapt text for email and chat apps, and write style rules that agents follow.
  6. Capstone Project — Build a Markdown kit for your own repo: README, AGENTS.md and tool files, a skill and a subagent, a spec, plan and ADR, docs and llms.txt, and lint settings. Audit your existing files, pass the graded checks and download the kit as a zip.

Reference

  1. Markdown Cheat Sheet — Every syntax rule, GFM extra, platform extension, frontmatter rule, AI-native file and check from the course on one page, with live boxes.
  2. Render Gotchas — Look up what you see, find the cause and the fix: headings, lists, links, code, tables, escaping, frontmatter errors and agent-file problems, each linked to its lesson.