Complete Guide to Markdown Syntax: Essential Writing for Developers

Trying to edit a README on GitHub but cannot remember the exact syntax? If you are a developer, this has probably happened to you at least once. Markdown takes about 10 minutes to learn, but the details tend to slip from memory when you only use it occasionally. This guide covers everything from the most common syntax to GitHub-specific extensions, all in one place.

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It was designed to let you write structured documents using plain text. It is far faster than writing HTML directly, and the raw text itself remains highly readable -- which is a major advantage.

Initially created for blog writing, Markdown has become the standard documentation format across platforms like GitHub, GitLab, Notion, Slack, and Reddit. For developers, it is practically a required skill.

Why Use Markdown?

Works everywhere: Markdown files (.md) can be opened in any text editor, even Notepad. They are not locked to any specific software, so your documents will be readable a decade from now. Word files have version compatibility headaches -- Markdown does not.

Perfect for version control: When tracking changes with Git, binary files like Word documents cannot show meaningful diffs. Markdown is text-based, so you can see exactly which lines changed at a glance.

Writing speed: Instead of clicking through menus to apply formatting, you keep your hands on the keyboard. For developers who live in the terminal, this makes a real difference in productivity.

Core Syntax Reference

Headings: Use # symbols to create headings. One # gives you the largest heading (h1), six gives the smallest (h6). Convention is to use only one h1 per document and start body sections at h2.

Bold and italic: Wrap text in ** for bold, * for italic. Using *** gives you bold italic. Standard Markdown does not include underline formatting.

Strikethrough: Wrap text in ~~ for strikethrough. Useful for marking corrections or outdated information.

Line breaks: A single Enter in Markdown continues the same paragraph. For a forced line break, add two spaces at the end of a line, or insert a blank line to start a new paragraph.

Creating Lists

Unordered lists: Use -, *, or + interchangeably. Pick one for consistency. Indenting with 2-4 spaces creates sub-items.

Ordered lists: Use numbers followed by periods: 1., 2., 3. Interestingly, Markdown auto-numbers regardless of what numbers you write. You could use 1. for every item and the output would still show 1, 2, 3. However, using correct numbers improves source readability.

Links and Images

Links: The format is [display text](URL). Write [Google](https://google.com) and you get a clickable link. For URLs used multiple times, reference-style links keep things clean.

Images: Add ! before the link syntax: . The alt text shows when the image fails to load, so write meaningful descriptions for accessibility.

Writing Code

Inline code: Wrap with backticks (`). Use it for code within sentences, like mentioning `console.log()` in a paragraph.

Code blocks: Start with three backticks (```) and specify the language name for syntax highlighting. Use ```javascript for JavaScript, ```python for Python. Close with another set of three backticks.

Tables

Build tables using pipes (|) and hyphens (-). Place a separator line below the header row. Control alignment with colons: :--- for left, :---: for center, ---: for right alignment. Column widths do not need to match in the source -- rendering handles alignment automatically.

Blockquotes and Horizontal Rules

Blockquotes: Start lines with >. They can span multiple lines, and >> creates nested quotes. Great for citing sources or highlighting important notes.

Horizontal rules: Use ---, ***, or ___ on their own line between blank lines. Useful for visually separating document sections.

GitHub Flavored Markdown (GFM)

GitHub extends standard Markdown with several useful features.

Checkboxes: - [ ] creates an empty checkbox, - [x] creates a checked one. Extremely handy for TODO lists and issue tracking. PR review checklists rely on these heavily.

Auto-linking: URLs typed directly become clickable links automatically, without needing the [text](URL) format.

Issue/PR references: Writing #123 automatically links to the corresponding issue or pull request. Cross-repository references work with the user/repo#123 format.

Practical Markdown Tips

README files: These shape first impressions of your project. Include project description, installation instructions, usage examples, and license information. Adding badges gives an at-a-glance status overview.

Document structure: Using h2 for top-level sections and h3 for subsections creates the most readable two-tier structure. Build a table of contents with internal links using [Section Name](#section-name).

Live preview: Editors like VS Code and Typora offer real-time preview while writing, letting you catch mistakes instantly. Online Markdown preview tools let you check formatting from any browser without installing software.