Markdown Guide: From Basics to GitHub Flavored Markdown

Markdown is the standard format for documentation, READMEs, blog posts, and technical writing. It is readable as plain text and converts to HTML everywhere.

Essential Syntax

GitHub Flavored Markdown (GFM) Extensions

• Tables with pipe syntax
• Task lists with checkboxes
• Strikethrough with double tildes
• Autolinks for bare URLs

Worked Example: Documenting an API Endpoint

Suppose you are documenting a POST /users endpoint. Start with a level-2 heading, add a one-line description, then a fenced code block with a language hint:

1. Write ## Create a user as the section heading
2. Add the description: Creates a user and returns the new user object.
3. Open a fenced block with three backticks and json as the language hint
4. Paste the request body: {"name": "Ada", "role": "admin"}
5. Close the block, then add a GFM table listing the response codes (200, 400, 409)

The whole section takes under two minutes to write, and because it is plain text it reviews cleanly in pull requests and diffs. You can iterate on it in the Markdown Preview and Converter before pasting it into your docs.

Common Mistakes

• Using tabs instead of spaces in nested lists — many renderers treat tabs inconsistently, so carefully nested bullets collapse to one level. Use 2 or 4 spaces for indentation.
• Forgetting the blank line before a list or code block — without it, most parsers treat the block as a continuation of the previous paragraph instead of a list or fence.
• Leaving the language hint off fenced code blocks — syntax highlighting disappears and screen readers lose context. Always add the language after the opening backticks.
• Skipping heading levels out of order — jumping from H2 to H4 breaks document structure and hurts both accessibility and SEO. Keep heading levels sequential.
• Pasting rich text from Word or Google Docs — hidden styles and smart quotes survive as garbage characters. Paste as plain text, then re-apply Markdown syntax.

Frequently Asked Questions

Is Markdown the same everywhere?

The core syntax (headings, lists, links, emphasis) is consistent, but flavors differ. GitHub Flavored Markdown adds tables, task lists, and strikethrough, while CommonMark is the stricter reference spec. When in doubt, test your document in the target renderer before publishing.

Can I use HTML inside Markdown?

Most flavors allow inline HTML, but many platforms sanitize it on render, stripping tags like style or script. If you need HTML for something like a form or video embed, check whether the destination permits it before you rely on it.

How do I write a line break?

End a line with two spaces or a backslash, then start a new line. A single press of Enter usually just joins the lines into one paragraph. Blank lines, not single newlines, are what separate paragraphs.

What is the difference between * and _ for emphasis?

They are interchangeable in most flavors, with one exception: asterisks can open emphasis in the middle of a word, while underscores usually cannot. So *in*side renders as italic but _in_side often stays literal.

Do I need a special editor for Markdown?

No — any text editor works because Markdown is plain text. What helps is a live preview pane, which catches syntax mistakes like unclosed emphasis markers or broken table pipes before your readers ever see them.

The Bottom Line

1. Markdown is the universal format for documentation and READMEs
2. GFM adds tables, task lists, and strikethrough
3. Always use fenced code blocks with language hints
4. Preview before publishing to catch formatting issues

Disclaimer: This guide is for informational purposes only.