Markdown

How to use this topic

The first eight pages teach the syntax: what Markdown is, headings and paragraphs, emphasis, lists, links and images, code, quotes and escaping, and tables. The next four explain why the same text can look different in different places: the flavors, GitHub and GitLab, front matter, and HTML inside Markdown. The last four are about using it well: converting it, writing documentation, keeping a consistent style, and Markdown in chat, notes and AI tools.

Most examples show the Markdown, the HTML it turns into, and the result as your browser displays it. The HTML is produced by markdown-it, a widely used renderer that follows the CommonMark specification; other tools can differ in details, and those differences are explained where they matter. HTML itself is explained in HTML & CSS.

There is no Markdown certification. The pages on Markdown on GitHub and GitLab and on writing documentation are marked GitHub Foundations (exam GH-900), which includes Markdown in issues, pull requests and README files.

Learning path

1. 01What Is Markdown?What Markdown is and why it is everywhere in IT: plain text with light punctuation that stays readable and turns into formatted HTML, where it came from, and where you will meet it.Beginner
2. 02Headings, Paragraphs and Line BreaksThe building blocks of a Markdown document: headings with #, paragraphs separated by blank lines, and the rules for line breaks that surprise almost everyone at first.Beginner
3. 03Emphasis and Inline FormattingFormatting words inside a paragraph: italic and bold with asterisks or underscores, strikethrough, inline code, and the rules that decide when a * or _ counts.Beginner
4. 04Lists and Task ListsBulleted, numbered and nested lists in Markdown, how indentation and blank lines change the result, and task lists with checkboxes on GitHub.Beginner
5. 05Links and ImagesLinking and illustrating in Markdown: inline and reference-style links, autolinks, relative links between files, and images with good alternative text.Beginner
6. 06Code: Inline Code and Fenced Code BlocksShowing commands, file names and code in Markdown: inline code with backticks, fenced code blocks with a language name for syntax highlighting, and indented code blocks.Beginner
7. 07Blockquotes, Horizontal Rules and EscapingQuoting text with >, separating sections with a horizontal rule, and escaping characters with a backslash when you want a literal * or # instead of formatting.Beginner
8. 08TablesTables in Markdown: pipes and the delimiter row, column alignment, what you can and cannot put in a cell, and when a table is the wrong tool.Beginner
9. 09Markdown Flavors: CommonMark, GitHub Flavored Markdown and OthersWhy the same Markdown can look different in two places: the original description, the CommonMark specification, GitHub Flavored Markdown and the other dialects you will meet.Intermediate
10. 10Markdown on GitHub and GitLabMarkdown where developers and operations teams use it most: READMEs, issues and pull requests, alerts, mentions and references, diagrams with Mermaid, and math.IntermediateGitHub Foundations
11. 11Front Matter and MetadataData about a document at the top of the file: YAML front matter between --- lines, what static site generators and note tools do with it, and the mistakes that break it.Intermediate
12. 12HTML in Markdown and SafetyMixing raw HTML into Markdown, why renderers often escape or strip it, and how to render Markdown from users safely without opening the door to cross-site scripting.Intermediate
13. 13Converting MarkdownTurning Markdown into something else: renderers such as markdown-it, Pandoc for HTML, Word and PDF, static site generators, and previews in your editor.Intermediate
14. 14Writing Documentation in MarkdownDocumentation that people actually use: the README, project docs in a docs folder, structure and headings, links between pages, changelogs, and docs-as-code with review and checks.IntermediateGitHub Foundations
15. 15Linting and Consistent StyleKeeping Markdown tidy and consistent: style choices that matter, markdownlint and its rules, formatting with Prettier, checking links, and running the checks in CI.Intermediate
16. 16Markdown in Chat, Notes and AI ToolsMarkdown outside documents: what Slack, Microsoft Teams and Discord understand, note apps such as Obsidian, wiki and ticket tools, and the Markdown in answers from AI assistants.Beginner

Markdown glossary

Short definitions of the terms used in this topic. The full glossary covers every topic.