Learn Markdown by seeing it
Markdown guides
Practical guides, from your first Markdown document to tables, diagrams and math. See the source beside the finished page, with examples you can open in the reader.
- Guides
- 38
- Topics
- 9
- Hours of reading
- 2
packing.md
## Packing list
- [x] **Passport**
- [ ] Charger, *both* of them
- [ ] Gate `B14` at 9:40The page
Packing list
- Passport
- Charger, both of them
- Gate
B14at 9:40
Nothing matches that yet. Try a shorter word.
Start here
The shortest path from "what is this?" to reading and writing useful Markdown.
- Guide5 min readWhat Is Markdown? A Plain Guide With ExamplesMarkdown is a simple way to format plain text with symbols like # and *. What it is, what a .md file is, where it is used, and examples you can try.
- Guide5 min readMarkdown Tutorial for Beginners in 10 MinutesLearn Markdown in ten minutes by building one real document, step by step. Headings, bold, lists, links, a table and code, each shown as you type it.
- Guide6 min readMarkdown Cheat Sheet With Rendered ExamplesEvery common piece of Markdown syntax beside its rendered result. Headings, emphasis, lists, links, images, code, tables, task lists and footnotes.
- Guide3 min readMarkdown Example File, Explained Line by LineA free Markdown example file that explains itself. Every common feature, with a note on how it is written. Download the .md file or open it in a reader.
- Guide4 min readSample Markdown File to Download and TestA free sample Markdown file that uses every common feature, from tables and footnotes to math, diagrams and unsafe HTML. Download it or open it in a reader.
README files
Project front doors: what belongs in a README, and how to make one quickly.
- Guide3 min readWhat Is a README File? README.md ExplainedA README is the first file people read in a project. What it is for, why it is usually README.md, where GitHub shows it, and what to put in one.
- Guide4 min readHow to Write a Good README, With a TemplateHow to write a README that people actually read. What to put in each section, a full example, common mistakes, and a free README.md template to download.
Syntax how tos
The everyday marks people look up while they are writing.
- Guide4 min readMarkdown Links: Anchors, Sections and Other FilesHow to add a link in Markdown. The link syntax, links to a section in the same file, to a heading, to another Markdown file, email links and reference links.
- Guide4 min readHow to Add an Image in MarkdownHow to add an image in Markdown, with examples. The image syntax, alt text, image size, centring, captions, images as links, and why an image does not show.
- Guide5 min readMarkdown Tables: Syntax, Alignment and ExamplesHow to make a table in Markdown. The syntax, column alignment, a pipe or line break inside a cell, tables without a header, and why cells cannot be merged.
- Guide4 min readMarkdown Code Blocks and Inline CodeHow to add code in Markdown. Inline code, fenced code blocks, naming the language for colors, backticks inside code, diff blocks, and the language names to use.
- Guide4 min readMarkdown New Line and Line Break: Every WayWhy pressing Enter does not start a new line in Markdown, and every way that does: a backslash, two spaces, the <br> tag, and an empty line for a new paragraph.
- Guide4 min readMarkdown Lists: Bullets, Numbers and Nested ListsHow to make lists in Markdown. Bullet lists, numbered lists, nested lists and indentation, starting at any number, and code or paragraphs inside a list item.
- Guide3 min readMarkdown Checkboxes and Task ListsHow to add a checkbox in Markdown. Task list syntax for ticked and unticked boxes, nested tasks, where you can click them, and why a checkbox sometimes does not show.
Formatting and layout
What Markdown can style directly, and where a small amount of HTML helps.
- Guide3 min readMarkdown Bold, Italic, Strikethrough and MoreHow to make text bold, italic or struck through in Markdown, and how to add underline, highlight, superscript, subscript and keyboard keys with a little HTML.
- Guide2 min readHow to Underline Text in MarkdownMarkdown has no underline syntax. How to underline text anyway with the <ins> or <u> HTML tag, where each one works, and why underlined text is best kept rare.
- Guide3 min readHow to Color Text in MarkdownMarkdown cannot color text, and GitHub removes HTML color styles. What does work instead: callouts, emphasis, diff blocks, and a little HTML where the app allows it.
- Guide2 min readHow to Center Text and Images in MarkdownMarkdown cannot center text, but HTML can. How to center text, headings and images with align="center", why it works on GitHub, and where centering is ignored.
- Guide2 min readMarkdown Horizontal Line and Page DividerHow to add a horizontal line in Markdown with three dashes, asterisks or underscores, the empty line it needs, and the trap where dashes turn text into a heading.
- Guide3 min readHow to Escape Characters in MarkdownHow to show a literal *, _, #, | or ` in Markdown with a backslash, which characters can be escaped, escaping inside tables and lists, and dollar signs.
- Guide3 min readEmoji in Markdown: Shortcodes and Typing Them InHow emoji work in Markdown. Typing them directly with your system's emoji picker, :shortcodes: like :rocket:, which apps turn shortcodes into emoji, and which do not.
Structure and extras
The pieces that make longer files easier to scan, fold, and maintain.
- Guide3 min readMarkdown Headings and How to Link to ThemHow to write headings in Markdown with #, the six heading levels, the underline style, heading anchors and links, custom anchors, and why a page needs one title.
- Guide3 min readHow to Make a Table of Contents in MarkdownHow to make a table of contents in Markdown with links to each heading, how heading anchors are made, why [TOC] is not standard, and apps that build one for you.
- Guide3 min readHow to Add Comments in MarkdownHow to write a comment in Markdown that does not show on the page. HTML comments, the [//]: # trick, commenting out a block, and where each one is hidden.
- Guide2 min readCollapsible Sections in Markdown With DetailsHow to make a collapsible section in Markdown with <details> and <summary>, keep Markdown working inside it, start it open, and hide a long code block.
- Guide3 min readMarkdown Footnotes: Syntax and ExamplesHow to add footnotes in Markdown. The [^1] syntax, named notes, notes with several paragraphs, where footnotes appear, and which apps support them.
- Guide3 min readMarkdown Callouts and Alerts: Note, Tip, WarningHow to add a callout or alert box in Markdown with > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION], where they work, and how Obsidian callouts differ.
Diagrams and math
Text-based diagrams and equations that still render as finished page elements.
- Guide4 min readMath in Markdown: Equations With LaTeXHow to write math in Markdown with LaTeX. Inline math with $, display equations with $$, fractions, symbols, matrices, the math fence, and which apps render it.
- Guide3 min readMermaid Diagrams in Markdown: ExamplesHow to draw diagrams in Markdown with Mermaid. Flowcharts, sequence diagrams, Gantt charts and pie charts with live examples, common mistakes, and where Mermaid renders.
Formats
The Markdown-adjacent conventions and flavors that explain why files render differently.
- Guide4 min readMarkdown Frontmatter: YAML at the Top of a FileWhat frontmatter is in a Markdown file, how to write YAML and TOML frontmatter, what static site generators and note apps use it for, and why it is hidden on the page.
- Guide3 min readGitHub Flavored Markdown (GFM) ExplainedWhat GitHub Flavored Markdown is, what it adds to standard Markdown (tables, task lists, strikethrough, autolinks), the extras only GitHub has, and other flavors.
Markdown and AI
The files coding agents read and write, and getting Markdown in and out of a chat.
- Guide5 min readWhat Is AGENTS.md (and CLAUDE.md)? With an ExampleAGENTS.md is a Markdown file of instructions for AI coding agents. What goes in it, how it differs from CLAUDE.md and GEMINI.md, which tools read it, and an example.
- Guide5 min readHow to Read the Markdown Files AI Coding Agents WriteWhere Claude Code, Cursor and Codex leave their plans and notes, how to read a long agent written Markdown file comfortably, and how to review a plan before accepting it.
- Guide4 min readMarkdown for AI Prompts: Why and How, With ExamplesHow to use Markdown to structure a prompt for ChatGPT, Claude or Gemini. Headings, lists and code fences that make a long prompt clear, and how to ask for Markdown back.
- Guide4 min readHow to Copy a ChatGPT or Claude Answer as MarkdownHow to copy an answer from ChatGPT, Claude or Gemini as Markdown rather than formatted text, why it pastes differently in each app, and how to check what you copied.
- Guide4 min readWhat Is llms.txt? Format, Example and How to Write Onellms.txt is a Markdown file at the root of a website that tells AI agents what the site is and where its best pages are. The format, an example, and what it does not do.
Converting
Turning a Markdown file into a web page or a Word document without losing its shape.
- Guide4 min readMarkdown to HTML: How It Converts, With ExamplesHow Markdown converts to HTML, what each symbol becomes, how to save a Markdown document as a self contained HTML file, and the command line tools that do it in bulk.
- Guide4 min readMarkdown to Word: Convert and Keep the FormattingHow to get Markdown into Microsoft Word with headings, lists and tables intact. Copy it as formatted text, or convert whole files to .docx with Pandoc.