I write Markdown every day - docs, READMEs, notes. After years of looking up the same syntax, I've distilled it down to what you'll actually use. Skip the fluff.
Why I write everything in Markdown
I switched to Markdown years ago and never looked back. My notes, documentation, blog posts - everything. It's fast to write, readable as plain text, and version control friendly. No fighting with formatting buttons or XML soup.
Once you internalize the basics - and there aren't many - you'll write faster than you ever did in a word processor. Here's exactly what you need to know.
Why use Markdown?
Markdown offers significant advantages over rich text editors and HTML for documentation. Understanding these benefits helps you decide when to use Markdown.
- Readable as plain text—no special software needed to read source files
- Version control friendly—diffs show meaningful changes, not formatting noise
- Portable—works across platforms, editors, and rendering engines
- Fast to write—no reaching for formatting buttons or remembering HTML tags
- Converts to HTML, PDF, and other formats easily
- Supported by GitHub, GitLab, Bitbucket, Stack Overflow, and countless tools
- Future-proof—plain text files remain accessible for decades
Basic syntax: Headings
Headings create document structure and hierarchy. Use hash symbols (#) followed by a space to create headings. The number of hashes determines the heading level.
- # Heading 1 (largest, typically one per document)
- ## Heading 2 (main sections)
- ### Heading 3 (subsections)
- #### Heading 4 (sub-subsections)
- ##### Heading 5 (rarely needed)
- ###### Heading 6 (smallest heading level)
- Always include a space after the hash symbols
- Heading 1 and 2 can alternatively use underlines: === and ---
Basic syntax: Text formatting
Markdown provides simple syntax for emphasizing text. These formatting options work inline within paragraphs and other block elements.
- *italic* or _italic_ for emphasis (renders as <em>)
- **bold** or __bold__ for strong emphasis (renders as <strong>)
- ***bold italic*** or ___bold italic___ for combined emphasis
- ~~strikethrough~~ for deleted text (not standard but widely supported)
- Formatting can span multiple words: **this entire phrase is bold**
- Escape special characters with backslash: \*not italic\*
- Avoid mixing underscore and asterisk styles within a document
Basic syntax: Paragraphs and line breaks
Paragraphs are separated by blank lines. Line breaks within paragraphs require specific syntax that varies slightly between implementations.
- Blank line creates a new paragraph (most important rule)
- Single line break in source may be ignored or converted to space
- Two spaces at end of line forces a line break (<br>)
- Backslash at end of line also forces line break in some parsers
- HTML <br> tag works when you need explicit line breaks
- Consecutive blank lines are collapsed into one paragraph break
- Indented paragraphs are treated as code blocks (4 spaces)
Basic syntax: Lists
Markdown supports both ordered (numbered) and unordered (bulleted) lists. Lists can be nested by indenting with spaces.
- Unordered lists: Start lines with -, *, or + followed by space
- Ordered lists: Start lines with number and period: 1. Item
- Numbers do not need to be sequential: 1. 1. 1. still renders as 1. 2. 3.
- Nest lists by indenting with 2-4 spaces (be consistent)
- Mix ordered and unordered lists by nesting
- List items can contain multiple paragraphs (indent continuation)
- Empty line between items may create loose list (more spacing)
Basic syntax: Links
Links connect your documentation to other resources. Markdown provides multiple link syntax options for different use cases.
- Inline links: [link text](https://example.com)
- With title: [link text](https://example.com "Title on hover")
- Reference links: [link text][ref] with [ref]: https://example.com below
- Automatic links: <https://example.com> renders as clickable URL
- Email links: <[email protected]> creates mailto link
- Relative links: [other page](./other-page.md) for documentation
- Anchor links: [section](#heading-id) links to headings on same page
Basic syntax: Images
Images use similar syntax to links with an exclamation mark prefix. The alt text is important for accessibility.
- Basic image: 
- With title: 
- Reference style: ![alt text][img-ref] with definition below
- Alt text describes image for screen readers and broken images
- Use relative paths for images in the same repository
- Absolute URLs work but may break if content moves
- No native syntax for image sizing—use HTML <img> when needed
Basic syntax: Blockquotes
Blockquotes highlight quoted text or call attention to important information. Use them for citations, callouts, or emphasis.
- Start line with > followed by space for blockquote
- Multiple paragraphs: Use > on blank lines between paragraphs
- Nested quotes: >> creates quote within quote
- Blockquotes can contain other Markdown: headers, lists, code
- Multiple > characters increase nesting depth
- Common use: Quoting external sources, documentation notes
- GitHub uses blockquotes for alerts: > [!NOTE], > [!WARNING]
Basic syntax: Inline code
Inline code formats short code snippets, commands, filenames, and technical terms within sentences.
- Wrap text with single backticks: `code here`
- Renders in monospace font, typically with background
- Use for variable names: The `userId` parameter...
- Use for commands: Run `npm install` to...
- Use for filenames: Edit the `config.json` file...
- To include literal backtick: Use double backticks: `` `code` ``
- Code is not processed for Markdown—special characters are safe
Basic syntax: Horizontal rules
Horizontal rules create visual separation between sections. Use them sparingly to avoid cluttered appearance.
- Three or more hyphens: ---
- Three or more asterisks: ***
- Three or more underscores: ___
- Spaces between characters allowed: - - -
- Creates <hr> HTML element
- Useful for separating major document sections
- Avoid overuse—headings usually provide better structure
Extended syntax: Code blocks
Fenced code blocks display multi-line code with optional syntax highlighting. This is essential for technical documentation and tutorials.
- Use triple backticks (```) to start and end code block
- Add language identifier after opening backticks for highlighting: ```javascript
- Common languages: javascript, typescript, python, bash, json, yaml, sql
- Indented code blocks (4 spaces) work but lack language highlighting
- Code inside blocks is not processed for Markdown formatting
- Some renderers support line highlighting: ```js {1,3-5}
- Use ```diff for showing code changes with + and - prefixes
Extended syntax: Tables
Tables organize data in rows and columns. Markdown tables are simple but effective for documentation.
- Use pipes (|) to separate columns
- Header row is separated from body by dashes: |---|---|
- Alignment: :--- left, :---: center, ---: right
- Cells do not need to align in source—pipes define columns
- Tables must have header row (required by most parsers)
- Escape pipes in cell content with backslash: \|
- For complex tables, consider HTML or external tools
Extended syntax: Task lists
Task lists (checkboxes) track to-do items directly in documentation. GitHub renders these as interactive checkboxes in issues and pull requests.
- Unchecked: - [ ] Task to do
- Checked: - [x] Completed task
- Space inside brackets is required for unchecked items
- x or X marks item as complete (lowercase preferred)
- Works within ordered lists too: 1. [ ] First task
- GitHub allows clicking checkboxes to toggle state
- Useful for issue templates, pull request checklists, project planning
Extended syntax: Footnotes
Footnotes add references or tangential information without interrupting the main text flow. Support varies by renderer.
- Reference footnote in text: This needs clarification[^1]
- Define footnote anywhere: [^1]: The clarification text
- Footnotes are numbered automatically regardless of label used
- Multi-paragraph footnotes: Indent continuation with 4 spaces
- Footnote definitions can appear anywhere in document
- Rendered footnotes typically appear at document end
- Not part of original Markdown—check renderer support
Extended syntax: Definition lists
Definition lists pair terms with their definitions. Support is inconsistent—verify your target platform supports them.
- Term on its own line, followed by : and definition
- Multiple definitions per term supported
- Not widely supported—GitHub does not render definition lists
- Use regular lists with bold terms as fallback
- Supported by PHP Markdown Extra, Pandoc, and some others
- HTML <dl>, <dt>, <dd> work everywhere if needed
- Consider if your audience will see proper rendering
GitHub Flavored Markdown: Overview
GitHub Flavored Markdown (GFM) extends standard Markdown with features specific to GitHub. These extensions are widely adopted beyond GitHub itself.
- Autolinks: URLs become clickable without angle brackets
- Strikethrough: ~~deleted text~~ with double tildes
- Tables: Pipe-based table syntax described earlier
- Task lists: Checkbox syntax described earlier
- Emoji shortcodes: :smile: :rocket: :+1:
- Username mentions: @username links to profiles
- Issue/PR references: #123 links to issues, org/repo#123 cross-repo
GitHub Flavored Markdown: Alerts
GitHub supports special blockquote syntax for callout boxes that highlight important information. These render as colored boxes with icons.
- > [!NOTE] for general information (blue)
- > [!TIP] for helpful suggestions (green)
- > [!IMPORTANT] for crucial information (purple)
- > [!WARNING] for potential problems (yellow)
- > [!CAUTION] for dangerous actions (red)
- Content follows on next line(s), still within blockquote
- Only works in GitHub—other renderers show raw text
GitHub Flavored Markdown: Syntax highlighting
GitHub automatically highlights code blocks based on the language identifier. Over 500 languages are supported.
- Common languages: js, ts, python, ruby, go, rust, java, c, cpp, csharp
- Shell languages: bash, sh, zsh, powershell, console
- Data formats: json, yaml, toml, xml, csv
- Markup: html, css, scss, markdown, latex
- Config files: dockerfile, nginx, apache, gitignore
- Use diff for showing changes: ```diff with +/- prefixes
- Language aliases work: js for javascript, py for python
GitHub Flavored Markdown: Diagrams
GitHub renders Mermaid diagrams in Markdown files. This enables flowcharts, sequence diagrams, and more without external tools.
- Use ```mermaid code block to define diagrams
- Flowcharts: graph TD; A-->B; B-->C;
- Sequence diagrams: sequenceDiagram with participant definitions
- Class diagrams: classDiagram with class definitions
- State diagrams: stateDiagram-v2 for state machines
- Gantt charts: gantt for project timelines
- Entity relationship: erDiagram for database schemas
GitHub Flavored Markdown: Mathematical expressions
GitHub supports LaTeX-style math expressions for technical and scientific documentation.
- Inline math: $E = mc^2$ with single dollar signs
- Block math: $$ on separate lines for display math
- Uses MathJax for rendering
- Supports standard LaTeX math commands
- Fractions: \frac{numerator}{denominator}
- Greek letters: \alpha \beta \gamma \pi
- Complex expressions: integrals, matrices, summations all work
Writing effective README files
README files are the front page of your project. A well-structured README helps users understand and use your project.
- Project title and brief description at the top
- Badges for build status, version, license, etc.
- Installation instructions—copy-paste ready commands
- Usage examples with code blocks
- Configuration options and environment variables
- Contributing guidelines (or link to CONTRIBUTING.md)
- License information
Documentation best practices
Good documentation requires more than correct syntax. Follow these practices to create documentation that helps your readers.
- Use consistent heading hierarchy—do not skip levels
- Keep paragraphs short—long blocks of text are hard to scan
- Use lists for steps, options, and multiple items
- Include code examples for technical documentation
- Add alt text to all images for accessibility
- Link related documentation—help readers find more information
- Update documentation when code changes—stale docs cause confusion
Common Markdown mistakes
These frequent mistakes cause rendering issues. Knowing them helps you write correct Markdown the first time.
- Missing blank line before lists—list may not render correctly
- Missing space after list marker—text not recognized as list item
- Missing space after heading hash—treated as plain text
- Incorrect indentation in nested lists—breaks list structure
- Forgetting to escape special characters when needed
- Using tabs instead of spaces inconsistently—rendering varies
- Not testing in target renderer—syntax support varies
Markdown tools and editors
The right tools make writing Markdown faster and help catch errors before publishing.
- VS Code: Built-in preview, excellent extension ecosystem
- Typora: WYSIWYG editor that saves as Markdown
- Obsidian: Note-taking with powerful linking and plugins
- Mark Text: Open-source focused Markdown editor
- GitHub: Edit files directly with preview tab
- Prettier: Automatic Markdown formatting in build pipelines
- markdownlint: Linting for consistent style
Converting Markdown to other formats
Markdown converts to many formats, making it ideal for content that needs multiple output formats.
- Pandoc: Universal document converter—Markdown to PDF, DOCX, HTML, EPUB
- Static site generators: Jekyll, Hugo, Astro, Next.js render Markdown to HTML
- mdBook: Rust tool for creating books from Markdown
- Docusaurus, GitBook: Documentation platforms using Markdown
- GitHub Actions: Automate conversion in CI/CD pipelines
- Prince, WeasyPrint: High-quality PDF generation from HTML/Markdown
- Slidev, Marp: Create presentations from Markdown
Markdown vs other formats
Understanding when Markdown is the right choice helps you pick the best format for your needs.
- Markdown vs HTML: Markdown is faster to write, HTML offers more control
- Markdown vs reStructuredText: rST is more powerful but complex
- Markdown vs AsciiDoc: AsciiDoc handles books and complex docs better
- Markdown vs Word/Docs: Markdown is portable, version-control friendly
- Markdown vs LaTeX: LaTeX for academic papers and complex math
- Markdown vs WYSIWYG: Markdown separates content from presentation
- Markdown wins for: READMEs, docs, notes, blogs, simple content
Conclusion: Master Markdown for effective documentation
Markdown is an essential skill for developers, technical writers, and anyone creating documentation. Its simple syntax produces clean, readable content that works across countless platforms.
Start with basic syntax—headings, lists, links, and code blocks cover most needs. Add extended features like tables and task lists as your documentation requires. Use a Markdown preview tool to verify rendering, especially when using GitHub-specific features.
FAQ
What is the difference between Markdown and GitHub Flavored Markdown?
GFM adds tables, task lists, strikethrough, and auto-linking. Most places use GFM now. The GitHub-specific stuff like alerts and Mermaid won't work elsewhere.
How do I create a table in Markdown?
Pipes for columns, dashes for the header separator. | Header | Another | then |---|---| then | data | here |. Colons control alignment: :--- left, ---: right.
Why is my Markdown list not rendering correctly?
Usually: no blank line before the list, or no space after the dash/asterisk. Also check your indentation is consistent - 2 or 4 spaces, never mix.
How do I add syntax highlighting to code blocks?
Put the language right after the opening backticks: ```javascript. No space. Common ones: js, ts, python, bash, json, yaml. GitHub supports hundreds.
Can I use HTML inside Markdown?
Yes, for things Markdown can't do - like image sizing or complex tables. But some platforms strip it for security. Always test.
How do I escape special characters in Markdown?
Backslash before the character: \\* \\# \\[ \\`. Inside code blocks you do not need to escape anything.
What is the best way to include images in GitHub README?
Store in your repo, use relative paths: . Version-controlled and won't break. GitHub Issue CDN URLs can disappear.
How do I create a collapsible section in GitHub Markdown?
Use <details><summary>Click here</summary> then your content, then </details>. Add a blank line after summary for proper Markdown parsing inside.