Markdown Syntax Guide: Write Better READMEs, Docs, and Technical Content

Why Markdown Still Wins

Markdown was created by John Gruber in 2004 with a simple goal: let people write using a plain-text format that is easy to read as-is and can be converted to structurally valid HTML. Two decades later, it is the default writing format for GitHub, GitLab, Stack Overflow, Reddit, Discord, Notion, Obsidian, and most documentation platforms in existence.

The reason Markdown dominates is not that it is the most powerful markup language. It is that the syntax disappears while you write. You do not need to open and close tags. You do not need a WYSIWYG editor. You type # Title and it becomes a heading. You type **bold** and it becomes bold. The cognitive overhead is almost zero, which means you spend your mental energy on the content instead of the formatting.

Whether you are writing a README for your open-source project, authoring API documentation, taking notes, or publishing blog posts, Markdown is the skill that keeps paying dividends. This guide covers everything from the absolute basics to GitHub-Flavored Markdown extensions and README best practices that separate amateur repositories from professional ones.

Basic Syntax: The Foundation

Headings

Markdown supports six levels of headings using the # symbol. The number of hash characters determines the heading level. Always put a space between the # and the heading text.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

In practice, most documents use H1 for the title, H2 for major sections, and H3 for subsections. Going deeper than H4 usually signals that your document structure needs refactoring.

Text Formatting

Markdown gives you bold, italic, and combined formatting using asterisks or underscores. The convention in most style guides is to use asterisks for consistency.

A common mistake is forgetting that single underscores inside words (like some_variable_name) can trigger italic formatting in some parsers. Asterisks do not have this problem, which is why the Markdown community settled on * over _ for emphasis.

Paragraphs and Line Breaks

To create a new paragraph, leave a blank line between blocks of text. For a line break within the same paragraph (a <br> in HTML), end a line with two or more spaces, or use a backslash \ at the end of the line. Simply pressing Enter once without trailing spaces will not create a visible line break in most renderers.

Links and Images

Inline Links

The link syntax uses square brackets for the visible text and parentheses for the URL. You can optionally add a title attribute in quotes.

[NexTool](https://nextool.app)
[NexTool](https://nextool.app "Free developer tools")

// Autolinked URL (GitHub-Flavored Markdown)
https://nextool.app

Reference-Style Links

For documents with many links, reference-style links keep your text cleaner. You define the URL separately, usually at the bottom of the document.

Check out [NexTool][1] for free developer tools.
Also see the [Markdown Preview][md-preview] tool.

[1]: https://nextool.app
[md-preview]: https://nextool.app/free-tools/markdown-preview.html

Images

Images use the same syntax as links but with an exclamation mark prefix. The text in brackets becomes the alt attribute, which is critical for accessibility and SEO.

![Alt text describing the image](image-url.png)
![Screenshot of the dashboard](./assets/dashboard.png "Dashboard overview")

On GitHub, you can also drag and drop images directly into the issue or PR editor, and it will generate the Markdown syntax for you automatically.

Lists: Ordered, Unordered, and Nested

Unordered Lists

Use -, *, or + followed by a space. The convention used by most style guides (including the Google Markdown style guide) is the hyphen -.

- First item
- Second item
  - Nested item (indent with 2 spaces)
  - Another nested item
- Third item

Ordered Lists

Use numbers followed by a period. A widely misunderstood detail: the actual numbers do not matter. The Markdown renderer generates sequential numbers regardless of what you type. This means you can use 1. for every item, making reordering easy.

1. First step
1. Second step
1. Third step
   1. Sub-step A
   1. Sub-step B

This renders as 1, 2, 3, 3.1, 3.2 even though every line says 1.. It is a deliberate design choice that makes maintenance painless.

Code Blocks and Inline Code

Inline Code

Wrap text in single backticks to format it as inline code. This is how you reference function names, variables, file paths, CLI commands, or any short code snippet within a sentence.

Run `npm install` to install dependencies.
The `useState` hook returns a state variable and a setter.
Open the file at `src/components/App.tsx`.

If you need a literal backtick inside inline code, use double backticks as the delimiter: ``code with ` backtick``.

Fenced Code Blocks

Use triple backticks to create a multi-line code block. Add the language identifier immediately after the opening backticks for syntax highlighting. This works on GitHub, GitLab, VS Code preview, and nearly every Markdown renderer.

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet('World'));
```

Common language identifiers: javascript (or js), typescript (or ts), python, bash (or shell), html, css, json, yaml, sql, go, rust, java, c, cpp, ruby, php, swift, kotlin, diff, markdown (or md).

Diff Syntax Highlighting

A hidden gem for code reviews and changelogs: use the diff language to highlight added and removed lines.

```diff
- const oldFunction = () => { /* old */ };
+ const newFunction = () => { /* improved */ };

  // unchanged line stays as-is
- removed line shows in red
+ added line shows in green
```

Tables: The Syntax Developers Always Forget

Tables are the one piece of Markdown syntax that almost nobody can write from memory. Here is the definitive reference.

Basic Table

| Feature     | Free  | Pro   |
| ----------- | ----- | ----- |
| Tool Access | 150+  | 150+  |
| Ads         | Yes   | No    |
| Export      | Basic | Full  |

The separator row (the one with hyphens) is required. You need at least three hyphens per column. The pipes at the beginning and end of each row are technically optional in some parsers, but always include them for compatibility.

Column Alignment

Add colons to the separator row to control text alignment. This is the part most people forget exists.

| Left Aligned | Centered    | Right Aligned |
| :----------- | :---------: | ------------: |
| text         | text        |          text |
| longer text  | longer text |   longer text |

Table Tips

• Columns do not need to be perfectly aligned in your source text. Renderers handle alignment automatically. But aligning them makes the raw Markdown much easier to read.
• You can use inline formatting inside table cells: **bold**, `code`, [links](url).
• You cannot use block-level elements (headings, multi-line code blocks, lists) inside standard Markdown table cells.
• For complex tables, consider using HTML directly or generating the Markdown with a tool.

Blockquotes and Horizontal Rules

Blockquotes

Use > at the start of a line to create a blockquote. You can nest them and include other Markdown elements inside.

> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > And you can nest blockquotes.
> >
> > Like this.

Blockquotes are useful for quoting external sources, highlighting important notes, and in GitHub issues and PRs for quoting previous comments. Many documentation systems also use them as the basis for admonition/callout blocks.

Horizontal Rules

Create a horizontal rule (a thematic break) with three or more hyphens, asterisks, or underscores on their own line. Always put a blank line above and below.

Content above the rule.

---

Content below the rule.

GitHub-Flavored Markdown Extensions

GitHub-Flavored Markdown (GFM) is a superset of CommonMark used by GitHub, and largely adopted by GitLab, VS Code, and most modern platforms. These extensions add powerful features on top of standard Markdown.

Task Lists (Checkboxes)

Create interactive checkboxes with - [ ] for unchecked and - [x] for checked. On GitHub, these are actually clickable in issues and PRs.

- [x] Set up project repository
- [x] Write initial README
- [ ] Add CI/CD pipeline
- [ ] Write contributing guidelines
- [ ] Publish v1.0 release

Strikethrough

Wrap text in double tildes to strike it through. Useful for showing completed items, deprecated options, or corrections.

~~This feature has been removed in v2.0.~~
The API endpoint is ~~`/api/v1/users`~~ `/api/v2/users`.

Footnotes

GitHub supports footnotes with a bracket-caret syntax. The footnote content can be placed anywhere in the document and will be rendered at the bottom.

Markdown was created in 2004[^1] and has become the de facto
standard for developer documentation[^2].

[^1]: By John Gruber, with contributions from Aaron Swartz.
[^2]: According to the 2025 Stack Overflow Developer Survey.

Alerts / Admonitions

GitHub introduced blockquote-based alerts in 2023. These render as colored callout boxes and are extremely useful for documentation.

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

These five alert types cover most documentation needs. They render with distinct colors and icons on GitHub, making your docs much more scannable.

Autolinked References

GFM automatically converts certain patterns into links:

• https://example.com becomes a clickable link
• #123 links to issue or PR number 123
• @username links to a GitHub user profile
• SHA references (full or 7+ characters) link to commits
• org/repo#123 links to issues in other repositories

Mermaid Diagrams

GitHub renders Mermaid diagrams in fenced code blocks. This lets you embed flowcharts, sequence diagrams, and more directly in your Markdown files.

```mermaid
graph LR
    A[Write Markdown] --> B[Preview]
    B --> C{Looks good?}
    C -->|Yes| D[Commit]
    C -->|No| A
```

README Best Practices

A README is the front door of your project. It is the first thing people see on GitHub, the first thing they read on npm, and often the only documentation a casual visitor will check. A great README converts visitors into users and users into contributors. Here is the structure that works.

The README Template

# Project Name

> One-line description of what this project does.

[![Build Status](badge-url)](link)
[![License](badge-url)](link)
[![npm version](badge-url)](link)

## Overview

2-3 sentences explaining the problem this project solves
and who it is for. Include a screenshot or GIF if visual.

## Quick Start

```bash
npm install your-package
```

```javascript
import { something } from 'your-package';
something.doThing();
```

## Features

- Feature one with brief explanation
- Feature two with brief explanation
- Feature three with brief explanation

## Installation

Detailed installation instructions, prerequisites,
environment variables, configuration options.

## Usage

### Basic Usage
Code examples with explanations.

### Advanced Usage
More complex scenarios.

## API Reference

| Method | Parameters | Returns | Description |
| ------ | ---------- | ------- | ----------- |
| `init()` | `config: Object` | `void` | Initialize |
| `run()`  | `options?: Object` | `Promise` | Execute |

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/name`)
3. Commit your changes (`git commit -m 'Add feature'`)
4. Push to the branch (`git push origin feature/name`)
5. Open a Pull Request

## License

MIT © [Your Name](https://yoursite.com)

README Rules That Matter

1. Answer "what and why" in 10 seconds. The title and first paragraph must tell a reader what the project does and why they should care. If someone has to scroll to understand the purpose, you have already lost them.
2. Show, do not tell. A code example is worth a thousand words of description. Put a working Quick Start example above the fold.
3. Add badges. Build status, version, license, and download count badges provide instant credibility signals. Use shields.io to generate them.
4. Include a screenshot or GIF. If your project has any visual component, show it. A 3-second GIF of the tool in action converts better than any paragraph.
5. Document the non-obvious. Everyone documents the happy path. Great READMEs also document common gotchas, known limitations, and environment requirements (Node version, OS support, etc.).
6. Keep it current. An outdated README is worse than no README. If the install command no longer works, users will leave and never come back. Treat README maintenance as part of your release process.

Tips for Technical Writing in Markdown

Knowing the syntax is half the battle. Using it well is the other half. These principles apply whether you are writing a README, API docs, a blog post, or internal documentation.

1. One Sentence Per Line

In your source Markdown, put each sentence on its own line. This makes version control diffs meaningful (you see which sentence changed, not which paragraph), makes reordering easy, and makes it trivial to spot overly long sentences.

This is the first sentence.
This is the second sentence.
Each one gets its own line in the source.

The rendered output is identical — a single paragraph.
But your git diffs become clean and useful.

2. Use Descriptive Link Text

Never use "click here" or "this link" as link text. The link text should describe the destination. This improves accessibility (screen readers list links by their text), SEO, and readability.

// Bad
For more information, click [here](url).

// Good
See the [installation guide](url) for detailed setup instructions.

3. Front-Load Important Information

Put the most critical information first in every document, section, and paragraph. Readers scan before they read. If the answer is buried in the third paragraph of section four, most people will never find it. This is especially true for README files where developers are looking for specific information quickly.

4. Use Tables for Structured Data

If you find yourself writing a list where each item has multiple attributes (name, type, default value, description), convert it to a table. Tables are denser and more scannable than lists for structured data.

5. Be Consistent

Pick conventions and stick to them throughout the document. If you use - for unordered lists, do not switch to * halfway through. If you use ATX-style headings (#), do not mix in Setext-style (underlined). Consistency reduces cognitive load for the reader.

6. Use HTML When Markdown Falls Short

Markdown allows inline HTML. If you need a collapsible section, centered text, or a complex layout, use HTML directly. The <details> and <summary> elements are particularly useful for long content that should be hidden by default.

<details>
<summary>Click to expand full error log</summary>

```
Error: Cannot find module 'express'
    at Function.Module._resolveFilename
    at Function.Module._load
    at Module.require
```

</details>

This is a standard pattern in GitHub issues for sharing long logs, stack traces, or configuration files without flooding the conversation.

Get NexTool Pro

No banners, clean output, enhanced features on all 150+ tools. One-time payment.

Frequently Asked Questions

What is the difference between Markdown and GitHub-Flavored Markdown (GFM)?

Standard Markdown (CommonMark) covers the basics: headings, bold, italic, links, images, lists, code blocks, and blockquotes. GitHub-Flavored Markdown is a superset that adds task lists (checkboxes), strikethrough text, tables, autolinked URLs, footnotes, and alert/admonition blocks. GFM is the default on GitHub, GitLab, and most modern documentation platforms. If you are writing for GitHub, you are writing GFM by default.

How do I create a table in Markdown?

Use pipes (|) to separate columns and hyphens (-) for the header row separator. The minimum is three hyphens per column. Add colons for alignment: :--- for left, :---: for center, ---: for right. If you find the syntax tedious, use a visual tool like the NexTool Markdown Table Generator to build the table interactively and copy the Markdown output.

What should a good README include?

At minimum: a project title and one-line description, installation instructions, a quick-start code example, and a license. For professional projects, add badges (build status, version, license), a features list, detailed usage examples, an API reference or configuration section, contributing guidelines, and a changelog or link to releases. The key principle is to answer "what does this do and how do I use it?" within the first 30 seconds of reading.

How do I add syntax-highlighted code blocks?

Use triple backticks (```) followed immediately by the language name. For example, ```python starts a Python-highlighted block. Close it with another ``` on its own line. This works on GitHub, GitLab, VS Code, and most Markdown renderers. For inline code within a sentence, use single backticks: `code here`.

Wrapping Up

Markdown is deceptively simple. The basic syntax takes five minutes to learn, but writing truly effective Markdown documents takes practice and intentionality. The difference between a README that attracts contributors and one that gets ignored often comes down to structure, examples, and attention to detail.

Bookmark this guide as your reference. Use the syntax examples as your cheat sheet. And when you are writing your next README, documentation page, or technical blog post, remember that great documentation is not about showing off formatting tricks. It is about making complex information accessible to the people who need it. Clear structure, working code examples, and honest communication will always beat fancy formatting.

Start writing. Preview as you go. Ship docs you would want to read yourself.