Markdown Guide for Developers: Write Better Documentation

Markdown is the standard for developer documentation. Simple syntax, readable as plain text, converts to HTML. Here's everything you need to know.

---

Why Markdown?

Benefits

• Readable as plain text - No special software needed

• Easy to learn - Simple syntax

• Portable - Works everywhere

• Version control friendly - Plain text diffs nicely

• Converts to HTML - Publishing ready

Where It's Used

• GitHub README files

• Documentation sites

• Blog posts (like this one)

• Note-taking apps

• Static site generators

• Slack/Discord messages

---

Basic Syntax

Headings

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

Paragraphs

Just write text. Separate paragraphs with blank lines.

This is a paragraph.

This is another paragraph.

Text Formatting

Bold text
Italic text
Bold and italic
~~Strikethrough~~
Inline code

Renders as:

• Bold text

• Italic text

• Bold and italic

• ~~Strikethrough~~

• Inline code

---

Lists

Unordered Lists

- Item one
Item two
  - Nested item
  - Another nested
Item three

• Item one

• Item two

- Nested item

- Another nested

• Item three

Ordered Lists

1. First item
2. Second item
3. Third item
   1. Nested ordered
   2. Another nested

1. First item

2. Second item

3. Third item

1. Nested ordered

2. Another nested

Task Lists (GitHub)

- [x] Completed task
[ ] Incomplete task
[ ] Another task

---

Links and Images

Links

Link text

Link with title

[Reference link][ref]

[ref]: https://example.com

Images

!Alt text

!Alt text

Linked Images

![Alt text](https://example.com)

---

Code

Inline Code

Use npm install to install dependencies.

Use npm install to install dependencies.

Code Blocks

Use three backticks with optional language:

    function hello() {

      console.log("Hello, world!");
    }
    

Renders with syntax highlighting:

function hello() {
  console.log("Hello, world!");
}

Supported Languages

Common ones:

• javascript / js

• typescript / ts

• python

• bash / shell

• html

• css

• json

• yaml

• markdown / md

---

Tables

Column 1
Column 2
Column 3

Row 1
Data
Data
Row 2
Data
Data

Column 1

Column 2

Column 3

Row 1

Data

Data

Row 2

Data

Data

Alignment

Left
Center
Right

L
C
R
L
C
R

Left

Center

Right

L

C

R

L

C

R

---

Blockquotes

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

> Nested quotes
>> Like this

> This is a blockquote.

>

> It can span multiple paragraphs.

> Nested quotes

>> Like this

---

Horizontal Rules

---

*

___

All render as:

---

---

GitHub Flavored Markdown

GitHub adds extra features:

Autolinks

URLs automatically become links:

https://github.com

Emoji

:smile: :rocket: :thumbsup:

:smile: :rocket: :thumbsup:

Footnotes

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Alerts/Admonitions

> [!NOTE]
> This is a note.

> [!WARNING]
> This is a warning.

> [!TIP]
> This is a tip.

---

Extended Markdown (MDX)

MDX lets you use React components in Markdown:

import Button from './Button';

My Post

Here's some content with a component:

 alert('Clicked!')}>Click me

Why MDX?

• Interactive elements in docs

• Reusable components

• Custom styling

• Dynamic content

Popular with:

• Next.js

• Docusaurus

• Astro

---

Best Practices

README Files

Structure your README:

Project Name

Brief description of what this project does.

Installation

\\\bash

npm install my-project
\\\

Usage

\\\javascript

import { something } from 'my-project';
\\\

API

functionName(options)

Description of the function.

Parameters:
option1 (string): Description
option2 (number): Description

Returns: Description

Contributing

How to contribute.

License

MIT

Documentation

• Use clear headings

• Include code examples

• Add tables for options/APIs

• Link to related pages

• Keep paragraphs short

Blog Posts

---
title: "Post Title"
date: 2026-02-05
author: Your Name


Post Title

Introduction paragraph that hooks the reader.

Main Point 1

Content...

Main Point 2

Content...

Conclusion

Wrap up.

---

Tools

Editors

• VS Code - Great Markdown preview

• Typora - Visual Markdown editor

• Obsidian - Note-taking with Markdown

• iA Writer - Clean writing experience

Converters

• Pandoc - Convert between formats

• Marked - Markdown to HTML

• MDX - Markdown + JSX

Linters

Markdown linting
npm install markdownlint-cli --save-dev

---

Common Mistakes

No Blank Lines

Heading
Paragraph without blank line.  ❌

Heading

Paragraph with blank line.  ✅

Inconsistent Formatting

- First item
* Second item  ❌
+ Third item

First item
Second item  ✅
Third item

Broken Links

Check links before publishing. Use tools like markdown-link-check.

Missing Alt Text

![](image.jpg)  ❌

!Description of image  ✅

---

Cheat Sheet

Element

Syntax

Heading

# H1 ## H2 ### H3

Bold

bold

Italic

italic

Code

` code

Link

text

Image

!alt

List	- item or 1. item

Quote

> quote

Line

---

Table

col

col

`

---

Conclusion

Markdown is essential for developers:

1. Learn the basics - Headings, lists, links, code

2. Use GitHub flavored - Tables, task lists

3. Explore MDX - For interactive docs

4. Practice - Write READMEs, documentation

Once you know Markdown, you'll use it everywhere.

Related guides:

• MDX Beginner's Guide

• Build a Blog with Next.js and MDX

• Git for WordPress Developers

Create a blog with Next.js and MDX →