Markdown Guide for Developers: Syntax, GitHub Flavors, and Best Practices

Markdown is the lingua franca of developer documentation. README files, GitHub issues, pull request descriptions, wikis, blog posts, and technical specs are all written in Markdown. Mastering the syntax takes 20 minutes. Doing it well takes slightly longer.

Core Markdown Syntax

Headings

# H1 — Page Title (one per document)
## H2 — Major Section
### H3 — Subsection
#### H4 — Minor subsection

Use headings to create a logical hierarchy. Screen readers and document parsers rely on heading levels to understand structure.

Emphasis

**bold text**
*italic text*
~~strikethrough~~

Lists

- Unordered item
- Another item
  - Nested item (indent with 2 spaces)

1. Ordered item
2. Second item
   1. Nested ordered

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")

![Alt text](image.png)
![Alt text](image.png "Image title")

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And multiple paragraphs.

Horizontal Rules

---

Three or more hyphens, asterisks, or underscores.

Code in Markdown

Inline Code

Use the `npm install` command to install dependencies.

Fenced Code Blocks

Use triple backticks with an optional language identifier:

```javascript
const greet = (name) => `Hello, ${name}!`;

Most Markdown renderers support syntax highlighting for: `javascript`, `typescript`, `python`, `bash`, `sql`, `yaml`, `json`, `go`, `rust`, `css`, `html`, and dozens more.

## GitHub-Flavored Markdown (GFM)

GitHub extends standard Markdown with several features:

### Task Lists

```markdown
- [x] Set up CI pipeline
- [x] Write unit tests
- [ ] Deploy to production
- [ ] Update documentation

Tables

| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Cell | Cell | Cell |
| Left-align | Center | Right |

Column alignment with colons:

| Left | Center | Right |
|:---|:---:|---:|
| text | text | text |

Mentions and References

In GitHub specifically:

• @username — mentions a user
• #123 — links to an issue or PR
• SHA — links to a commit

Footnotes

This is a claim that needs a citation.[^1]

[^1]: The source of this claim.

Collapsible Sections

GitHub renders <details> HTML tags:

<details>
<summary>Click to expand</summary>

Hidden content here. Standard Markdown works inside.

</details>

Documentation Best Practices

README Structure

A well-structured README follows this pattern:

# Project Name

Brief one-sentence description.

## Installation
## Usage
## Configuration
## Contributing
## License

Code Examples Over Prose

Show, don't tell. A ten-line code example communicates more precisely than three paragraphs of description.

Keep Code Examples Runnable

Test every code snippet in your documentation. Outdated examples are worse than no examples — they waste developer time and erode trust.

Use Relative Links for Internal Documentation

See [Configuration Guide](./docs/config.md) for details.

Relative links work across forks, local clones, and GitHub rendering.

One Sentence Per Line

In source-controlled Markdown, writing one sentence per line makes diffs much cleaner:

This approach has two benefits.
First, diffs show which sentences changed.
Second, it prevents horizontal scrolling in editors.

Preview Before Committing

The Markdown Previewer on InfraHub renders Markdown in real time with GitHub-flavored Markdown support. Paste your content, see exactly how it will look, and catch formatting issues before pushing. It handles tables, task lists, fenced code blocks with syntax highlighting, and HTML passthrough — all in your browser with no server processing.