Markdown: The Complete Guide for Developers

Published on February 11, 2026 • 20 min read

Table of Contents

Try Our Markdown Tools

Preview your Markdown in real time with our Markdown Preview tool, or convert it to clean HTML with the Markdown to HTML Converter. Write and experiment as you read this guide.

1. What Is Markdown and Its History

Markdown is a lightweight markup language that lets you add formatting to plain text documents using simple, intuitive syntax. Created by John Gruber in 2004, with significant contributions from Aaron Swartz, Markdown was designed with a single guiding principle: the source text should be readable as-is, without looking like it has been tagged or marked up with formatting instructions. The name itself is a play on the concept of "markup" languages like HTML — Markdown is the simpler, more natural counterpart.

Gruber published the original Markdown syntax specification along with a Perl script (Markdown.pl) that converted Markdown text to valid XHTML. The initial release was modest in scope: headings, paragraphs, emphasis, links, images, code, blockquotes, and lists. But the simplicity of the format resonated deeply with writers and developers alike, and adoption spread rapidly.

By 2012, Markdown had become the default writing format on GitHub, Stack Overflow, Reddit, and dozens of other platforms. However, the original specification left certain edge cases ambiguous. Different parsers handled these cases differently, which led to frustrating inconsistencies. To address this, a group of developers including Jeff Atwood (co-founder of Stack Overflow) and John MacFarlane (creator of Pandoc) launched the CommonMark project in 2014, creating a rigorous, unambiguous specification with a comprehensive test suite. CommonMark standardized how Markdown should be parsed, and most modern Markdown implementations now follow CommonMark or build upon it.

Today, Markdown is everywhere. It powers documentation on GitHub and GitLab, note-taking in Obsidian and Notion, static site generators like Hugo and Jekyll, technical documentation platforms like Docusaurus and MkDocs, and communication on platforms like Discord and Slack. The format has become so pervasive that knowing Markdown is considered an essential skill for any developer. According to the 2025 Stack Overflow Developer Survey, Markdown is the most commonly used documentation format among professional developers.

The key milestones in Markdown's history include:

2. Basic Syntax

The basic Markdown syntax covers the elements you will use in virtually every document. These elements are supported universally across all Markdown parsers and platforms.

Headings

Create headings by placing one to six hash symbols (#) before the heading text. The number of hashes determines the heading level:

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

Always include a space between the hash and the heading text. Most parsers require this space, and omitting it can cause the line to be treated as a regular paragraph. Use only one H1 per document (it represents the document title), and never skip heading levels — go from H2 to H3, not from H2 to H4.

There is also an alternative "Setext" style for H1 and H2 only, using underlines:

Heading Level 1
===============

Heading Level 2
---------------

While valid, the ATX style (#) is universally preferred because it supports all six levels and is more visually clear in source text.

Paragraphs

Paragraphs are simply blocks of text separated by one or more blank lines. A single line break within a paragraph does not create a new line in the output — the text continues on the same line. This behavior catches many beginners off guard.

This is the first paragraph. You can write
across multiple lines in the source and it
will render as a single paragraph.

This is the second paragraph. The blank line
above creates the separation.

To create a hard line break within a paragraph (a <br> tag) without starting a new paragraph, end the line with two trailing spaces or a backslash (\):

First line with two trailing spaces
Second line appears below it.

First line with a backslash\
Second line appears below it.

Emphasis (Bold, Italic, Strikethrough)

Markdown provides straightforward syntax for emphasizing text using asterisks or underscores:

*Italic text* or _italic text_

**Bold text** or __bold text__

***Bold and italic*** or ___bold and italic___

**_Bold and italic mixed_** or *__also mixed__*

~~Strikethrough text~~

Best practice is to use asterisks rather than underscores. Underscores in the middle of words can cause problems with some parsers (for example, some_variable_name might be incorrectly treated as emphasis), while asterisks in the middle of words are handled consistently. Strikethrough (~~text~~) is technically a GFM extension, but it is supported by virtually all modern parsers.

Blockquotes

Prefix lines with a greater-than sign (>) to create blockquotes. They are commonly used for quoting text, highlighting notes, or calling attention to important information:

> This is a blockquote. It can span multiple
> lines and will be rendered as a single
> indented block.

> First paragraph of the quote.
>
> Second paragraph of the quote.

> Outer quote
>
> > Nested quote inside the outer quote
>
> Back to the outer quote

> ### Heading inside a blockquote
>
> Blockquotes can contain **any** Markdown:
>
> - Lists work
> - `Code` works
> - [Links](https://example.com) work

Lists

Unordered lists use a dash, asterisk, or plus sign followed by a space. Ordered lists use a number followed by a period and a space:

Unordered:
- First item
- Second item
- Third item

Ordered:
1. First item
2. Second item
3. Third item

Nested:
- Fruits
  - Apples
    - Granny Smith
    - Fuji
  - Oranges
- Vegetables
  - Carrots

Mixed nesting:
1. First step
   - Detail A
   - Detail B
2. Second step
   1. Sub-step 1
   2. Sub-step 2
3. Third step

An interesting detail: the actual numbers in ordered lists do not matter. Markdown always renders them sequentially. Many developers use 1. for every item so they never need to renumber when inserting new items. Either approach is acceptable — pick one and be consistent.

Preview Your Markdown Instantly

Try every syntax example from this guide in real time. Our Markdown Preview tool shows rendered output as you type, making it easy to experiment and learn.

3. Extended Syntax

Extended syntax elements go beyond the original Markdown specification. They were introduced by various Markdown flavors and are now widely supported by most modern parsers, though not universally guaranteed on every platform.

Tables

Tables use pipes (|) and hyphens (-) to define columns and rows. A separator row of hyphens between the header row and data rows is required:

| Feature     | Syntax       | Supported |
|-------------|-------------|-----------|
| Bold        | **text**     | Yes       |
| Italic      | *text*       | Yes       |
| Tables      | pipes + dashes | GFM     |
| Task Lists  | - [x] / - [ ] | GFM     |

Control column alignment with colons in the separator row:

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| left         |    center      |         right |
| text         |     text       |          text |

The leading and trailing pipes are optional, columns do not need to be perfectly aligned in the source, and you can use inline formatting (bold, italic, code, links) inside cells. However, tables cannot contain block-level elements like headings, lists, or code blocks.

Build Tables Visually

Crafting Markdown tables by hand is tedious. Use our Markdown Table Generator to build tables with a spreadsheet-like interface and export perfect Markdown syntax instantly.

Fenced Code Blocks

Wrap code in triple backticks (or triple tildes) to create code blocks. Add a language identifier for syntax highlighting:

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

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
#!/bin/bash
echo "Hello, World!"
for i in {1..5}; do
    echo "Count: $i"
done
```

```sql
SELECT users.name, COUNT(orders.id) AS total
FROM users
LEFT JOIN orders ON users.id = orders.user_id
GROUP BY users.name
HAVING total > 5;
```

Common language identifiers include: javascript (or js), python (or py), typescript (or ts), html, css, bash (or shell), json, yaml, sql, go, rust, java, c, cpp, csharp, ruby, php, markdown (or md), xml, dockerfile, and diff.

There is also an older "indented code block" syntax that uses four spaces of indentation, but fenced code blocks are universally preferred because they support syntax highlighting and are easier to read.

Footnotes

Footnotes add references without cluttering the main text. They are supported by GitHub (since 2021), PHP Markdown Extra, Pandoc, and many other processors:

Markdown was created by John Gruber[^1] in 2004.

The CommonMark specification[^spec] standardized
Markdown parsing in 2014.

[^1]: John Gruber is the author of the Daring Fireball blog.
[^spec]: CommonMark: https://commonmark.org/

Footnote references render as superscript numbers that link to the footnote content collected at the bottom of the page. The footnote definitions can be placed anywhere in the document.

Task Lists

Task lists (checkbox lists) are a GFM extension that is widely supported. They are invaluable for tracking progress in issues, pull requests, and project documentation:

- [x] Write the introduction
- [x] Add code examples
- [ ] Review for typos
- [ ] Publish the article

Nested task lists:
- [ ] Project setup
  - [x] Initialize repository
  - [x] Configure linting
  - [ ] Set up CI/CD
- [ ] Core features
  - [x] Authentication
  - [ ] Dashboard

On GitHub, task lists render as interactive checkboxes. The platform also shows task completion progress (e.g., "3 of 7 tasks completed") in issue list views, making them excellent for project management directly within issues.

Horizontal Rules

Create a horizontal rule (<hr>) using three or more hyphens, asterisks, or underscores on a line by themselves:

---

***

___

All three produce the same output. Always include blank lines before and after a horizontal rule, especially before — because --- directly below text will be interpreted as a Setext-style H2 heading.

Links and images are fundamental elements that make documents interactive and visual. Markdown provides multiple link styles to suit different writing contexts.

Inline Links

[DevToolbox](https://devtoolbox.dedyn.io/)
[Markdown Guide](https://www.markdownguide.org "Optional tooltip title")

The text in square brackets becomes the clickable text. The URL goes in parentheses, followed by an optional title in quotes that appears as a tooltip on hover.

Reference Links

Reference-style links keep the text clean and organize URLs at the bottom, which is especially useful in documents with many links:

Check out [DevToolbox][1] for free developer tools.
Also see the [CommonMark specification][spec].

[1]: https://devtoolbox.dedyn.io/
[spec]: https://commonmark.org/ "CommonMark Spec"

The reference labels are case-insensitive and do not appear in the rendered output. This style is excellent for long documents where the same URL appears multiple times.

Autolinks

<https://devtoolbox.dedyn.io>
<contact@example.com>

Angle brackets create automatic links from bare URLs and email addresses. Most modern parsers (including GFM) also autolink bare URLs without angle brackets, but using angle brackets is more portable.

Section Links (Anchors)

Link to headings within the same document using the heading text converted to lowercase with spaces replaced by hyphens:

[Jump to the Tables section](#tables)
[See Basic Syntax](#basic-syntax)

Most Markdown processors automatically generate anchor IDs from headings. A heading like ## Getting Started becomes an anchor #getting-started.

Images

Images use the same syntax as links but with an exclamation mark (!) prefix:

![Alt text for the image](https://example.com/image.png)
![Logo](./images/logo.png "Optional title")

The alt text is critical for accessibility — screen readers use it to describe images to visually impaired users, and it displays when images fail to load. Always write meaningful, descriptive alt text.

Linked Images

Make an image clickable by wrapping the image syntax inside a link:

[![Project Logo](./logo.png)](https://devtoolbox.dedyn.io/)

Image Sizing

Standard Markdown does not support image dimensions. When you need to control size, use inline HTML:

<img src="screenshot.png" alt="Dashboard" width="600">

Some extended parsers support non-standard attributes like ![alt](url){width=600}, but this is not portable. The HTML approach works everywhere.

5. GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown is the most widely adopted Markdown extension. Built on CommonMark, it adds features specifically designed for software development workflows. Understanding GFM is essential because its conventions have been adopted far beyond GitHub itself — by GitLab, Bitbucket, VS Code, and countless other tools.

GFM Extensions Beyond Standard Markdown

GFM adds the following features to CommonMark:

GitHub Alert Callouts

GitHub added blockquote-based callouts in 2023 that render with colored styling and icons:

> [!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.

Each callout type renders with a distinct color and icon. On platforms that do not support this syntax, they gracefully degrade to regular blockquotes with the label text visible.

Mermaid Diagrams

GitHub renders Mermaid diagrams directly from code blocks, enabling flowcharts, sequence diagrams, Gantt charts, and more without external tools:

```mermaid
graph TD
    A[Write Markdown] --> B{Preview OK?}
    B -->|Yes| C[Commit]
    B -->|No| D[Edit]
    D --> A
    C --> E[Push to GitHub]
```

```mermaid
sequenceDiagram
    Browser->>Server: GET /api/data
    Server->>Database: Query
    Database-->>Server: Results
    Server-->>Browser: JSON Response
```

Math Expressions

GitHub supports LaTeX math notation for inline and block expressions:

Inline math: $E = mc^2$

Block math:
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

6. Markdown in Documentation

Markdown has become the standard authoring format for software documentation. From README files to full documentation sites, developers overwhelmingly choose Markdown for its simplicity, version control compatibility, and tooling ecosystem.

README Files

The README is the front door to any software project. A well-structured README should follow this template:

# Project Name

One-line description of what the project does.

## Features

- Key feature one
- Key feature two
- Key feature three

## Getting Started

### Prerequisites

- Node.js 18+
- npm or yarn

### Installation

```bash
git clone https://github.com/user/project.git
cd project
npm install
```

### Usage

```bash
npm start
```

## Configuration

Describe configuration options with a table:

| Option   | Type    | Default | Description          |
|----------|---------|---------|----------------------|
| port     | number  | 3000    | Server port          |
| debug    | boolean | false   | Enable debug logging |
| timeout  | number  | 30000   | Request timeout (ms) |

## API Reference

Document your API endpoints here.

## Contributing

How to contribute to the project.

## License

MIT License - see [LICENSE](LICENSE) for details.

The best README files lead with the most important information. Do not bury installation instructions below three paragraphs of project history. Developers want to know what the project does, how to install it, and how to use it — in that order.

Wikis

Both GitHub and GitLab provide wiki functionality that uses Markdown. Wikis are excellent for extended documentation that does not belong in the README: architecture decisions, design documents, onboarding guides, and runbooks. Each wiki page is a separate Markdown file, and you can link between pages using [[Page Name]] syntax on GitHub or standard Markdown links on GitLab.

Documentation Sites

Modern documentation platforms use Markdown as the primary authoring format and convert it to polished HTML sites:

These tools add features like navigation sidebars, search, versioning, API reference generation, and custom components while keeping the authoring experience simple Markdown.

Changelogs

Markdown is the standard format for project changelogs. The widely adopted Keep a Changelog convention uses this structure:

# Changelog

## [1.2.0] - 2026-02-11

### Added
- New Markdown preview feature
- Export to PDF support

### Changed
- Improved table rendering performance
- Updated syntax highlighting theme

### Fixed
- Line break handling in nested blockquotes
- Image loading in offline mode

### Removed
- Deprecated legacy parser

## [1.1.0] - 2026-01-15
...

7. Markdown for Technical Writing

Technical writing in Markdown requires discipline and conventions beyond basic syntax knowledge. The following practices distinguish professional technical documentation from casual writing.

Structuring Long Documents

For documents longer than a few screens, include a table of contents at the top. Link each entry to its corresponding heading anchor:

## Table of Contents

- [Installation](#installation)
- [Configuration](#configuration)
- [API Reference](#api-reference)
  - [Authentication](#authentication)
  - [Endpoints](#endpoints)
- [Troubleshooting](#troubleshooting)

Some tools generate tables of contents automatically. GitLab supports [[_TOC_]], Pandoc has a --toc flag, and VS Code extensions can auto-generate TOCs.

Code Documentation Patterns

When documenting code, always provide context before and after code blocks. Explain what the code does, when to use it, and what the expected output looks like:

### Parsing Configuration Files

Use the `loadConfig()` function to parse YAML configuration
files. It returns a validated configuration object:

```javascript
const config = loadConfig('./config.yaml');
console.log(config.port); // 3000
```

If the configuration file is missing or invalid, the function
throws a `ConfigError` with a descriptive message:

```javascript
try {
    const config = loadConfig('./missing.yaml');
} catch (error) {
    console.error(error.message);
    // "Configuration file not found: ./missing.yaml"
}
```

Admonitions and Callouts

Use blockquotes or platform-specific callout syntax to highlight warnings, tips, and important notes:

> **Warning:** This operation deletes all data
> and cannot be undone. Back up your database first.

> **Note:** This feature requires Node.js 18 or later.
> Earlier versions are not supported.

> **Tip:** Use environment variables for sensitive
> configuration values instead of hardcoding them.

API Documentation

Markdown works well for API documentation when structured consistently. Document each endpoint with the HTTP method, path, parameters, request body, and response:

### Create User

`POST /api/users`

**Request Body:**

```json
{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer"
}
```

**Response:** `201 Created`

```json
{
    "id": 42,
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer",
    "createdAt": "2026-02-11T10:30:00Z"
}
```

**Error Response:** `400 Bad Request`

```json
{
    "error": "Validation failed",
    "details": ["Email is required", "Name must be at least 2 characters"]
}
```

Front Matter for Static Sites

Many static site generators and documentation tools support YAML front matter at the start of Markdown files for metadata:

---
title: "API Authentication Guide"
date: 2026-02-11
author: "DevToolbox Team"
tags: [api, authentication, security]
sidebar_position: 3
description: "Learn how to authenticate with our API"
---

# API Authentication Guide

Content starts after the front matter...

Write Markdown Like a Pro

Use our Markdown Editor for a full-featured writing environment with live preview, or generate complex tables effortlessly with the Markdown Table Generator.

8. Markdown vs Alternatives

Markdown is not the only lightweight markup language. Understanding the alternatives helps you choose the right tool for each situation.

Feature Markdown AsciiDoc reStructuredText HTML
Learning Curve Very easy (minutes) Moderate (hours) Moderate (hours) Moderate (days for proficiency)
Readability Excellent as plain text Good as plain text Good as plain text Poor (tags everywhere)
Feature Richness Basic (extensions add more) Very rich (built-in) Very rich (built-in) Complete (web standard)
Tables Basic (GFM extension) Advanced (spans, nesting) Advanced (spans, nesting) Full HTML tables
Cross-References Manual anchor links Built-in cross-refs Built-in cross-refs Manual anchor links
Includes/Imports Not supported natively Built-in includes Built-in includes Not natively (needs SSI/JS)
Admonitions Via extensions only Built-in (NOTE, WARNING, etc.) Built-in directives Custom HTML/CSS needed
Tooling Massive ecosystem Good (Asciidoctor) Good (Sphinx) Massive ecosystem
Platform Support Universal Moderate Primarily Python ecosystem Universal
Best For READMEs, notes, blogs, docs Technical books, manuals Python docs (Sphinx) Web pages, complex layouts

When to Choose Markdown

When to Choose AsciiDoc

When to Choose reStructuredText

When to Choose HTML

Convert Between Markdown and HTML

Need to switch between formats? Our Markdown to HTML Converter generates clean, semantic HTML from Markdown. Then use the HTML Beautifier to format the output for readability.

9. Markdown Editors and Tools

The right editor can dramatically improve your Markdown writing experience. Here are the best options across different categories.

Desktop Editors

Online Editors

Command-Line Tools

Libraries for Developers

When building applications that process Markdown, these libraries handle parsing and rendering:

JavaScript:
  - marked          (fast, lightweight, GFM support)
  - markdown-it     (pluggable, CommonMark-compliant)
  - remark          (AST-based, part of the unified ecosystem)
  - showdown        (bidirectional HTML/Markdown conversion)

Python:
  - Python-Markdown (extensible, reference implementation)
  - mistune         (fast, pure Python parser)
  - markdown2       (fast, supports many extras)
  - Marko           (CommonMark compliant, extensible)

Go:
  - goldmark        (CommonMark compliant, extensible, fast)
  - blackfriday     (popular, GFM support)

Ruby:
  - kramdown        (pure Ruby, many extensions)
  - Redcarpet       (fast C extension, GFM support)

PHP:
  - league/commonmark (CommonMark compliant, extensible)
  - Parsedown        (fast, GFM support)

Rust:
  - pulldown-cmark   (CommonMark, used by rustdoc)
  - comrak           (GFM compliant, fast)

10. Markdown on Different Platforms

While core Markdown syntax is universal, each platform adds its own extensions and sometimes has subtle rendering differences. Understanding these differences is important when you write content for multiple platforms.

GitHub

GitHub uses GFM (covered in detail in section 5). Key platform-specific features include @mentions for users and teams, #123 issue references, commit SHA linking, alert callouts, Mermaid diagrams, and math expressions. GitHub sanitizes HTML in Markdown, stripping <script>, <style>, and other potentially dangerous tags.

GitLab

GitLab supports all GFM features plus some unique additions:

Notion

Notion uses Markdown as a shortcut for creating blocks. When you type Markdown syntax, Notion converts it to its native block format in real time. Supported shortcuts include headings, bold, italic, strikethrough, code, lists, task lists, blockquotes, dividers, and inline code. However, Notion is not a true Markdown editor — it converts Markdown on input but stores content in its own proprietary format. Markdown export is available but may lose some formatting nuances.

Obsidian

Obsidian is a Markdown-first knowledge base application that stores all content as plain .md files on your local filesystem. It extends standard Markdown with:

Stack Overflow

Stack Overflow uses a Markdown variant with some limitations. It supports headings, emphasis, lists, links, images, code (inline and blocks), blockquotes, and horizontal rules. It does not support tables (use HTML tables instead), task lists, or footnotes. Code blocks support syntax highlighting with the <!-- language: lang --> comment syntax or triple-backtick fences.

Discord

Discord supports a subset of Markdown for chat messages: bold, italic, underline (__text__), strikethrough, inline code, code blocks with syntax highlighting, blockquotes, spoiler tags (||text||), and headings (H1-H3). It does not support tables, images via Markdown, footnotes, or task lists. Note that Discord treats __text__ as underline, which conflicts with standard Markdown bold.

Slack

Slack uses its own "mrkdwn" format that is significantly different from standard Markdown. Bold uses single asterisks (*bold*), italic uses underscores (_italic_), strikethrough uses single tildes (~text~), and links use <url|text> syntax. Slack does not support headings, tables, images via markup, or lists. The syntax differences are substantial enough that content does not transfer cleanly between Slack and standard Markdown.

Feature GitHub GitLab Obsidian Discord Slack
Tables Yes Yes Yes No No
Task Lists Yes (interactive) Yes Yes No No
Footnotes Yes Yes Yes No No
Code Highlighting Yes (200+ langs) Yes Yes (via Prism) Yes No
Diagrams Mermaid Mermaid + PlantUML Via plugins No No
Math / LaTeX Yes Yes (KaTeX) Yes (MathJax) No No
Callouts/Alerts Yes (5 types) No (use HTML) Yes (custom types) No No
Spoiler Tags No No No Yes (||text||) No
Headings H1-H6 H1-H6 H1-H6 H1-H3 None

11. Tips and Tricks

These practical tips will help you write cleaner Markdown, avoid common pitfalls, and take advantage of lesser-known features.

Escaping Special Characters

Prefix any Markdown special character with a backslash to display it literally:

\* Not italic \*
\# Not a heading
\[Not a link\](not-a-url)
\`Not code\`
\| Not | a | table |

Characters you can escape:
\   backslash        `   backtick
*   asterisk         _   underscore
{}  curly braces     []  square brackets
()  parentheses      #   hash mark
+   plus sign        -   minus sign
.   dot              !   exclamation mark
|   pipe

Line Breaks and Whitespace

Markdown's line break behavior is one of the most confusing aspects for beginners. Remember these rules:

Nested Lists Done Right

Nested list indentation varies by parser. For maximum compatibility:

- Parent item
  - Child item (2 spaces indent)
    - Grandchild (4 spaces from root)

1. Parent item
   1. Child item (3 spaces indent)
      1. Grandchild (6 spaces from root)

Adding Content Inside List Items

You can include paragraphs, code blocks, and blockquotes inside list items by aligning them with the item text:

1. First step

   This paragraph belongs to item 1.
   Indent it to align with the item text.

   ```bash
   npm install
   ```

   > A blockquote inside a list item.

2. Second step

Collapsible Sections

Use HTML <details> and <summary> tags for collapsible sections. This works on GitHub, GitLab, and most Markdown renderers that allow HTML:

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

This content is hidden by default.

- Markdown works inside!
- **Bold** and `code` too.

```javascript
console.log("Hidden code block");
```

</details>

Collapsible sections are excellent for long log outputs, detailed error messages, or optional supplementary information that would otherwise clutter the main content.

Comments in Markdown

Markdown does not have a native comment syntax, but you can use HTML comments:

<!-- This comment will not appear in the rendered output -->

<!--
Multi-line comments
also work this way
-->

[//]: # "This is another comment technique that works in most parsers"
[//]: # (Parentheses also work for the link-style comment)

The link-style comment ([//]: #) is a clever hack that exploits Markdown's reference link syntax. Since the link is never referenced, it never appears in the output.

Diff Syntax Highlighting

Use the diff language identifier in code blocks to highlight additions and deletions:

```diff
- const greeting = "Hello";
+ const greeting = "Hello, World!";

  function greet(name) {
-     return greeting;
+     return `${greeting} Welcome, ${name}!`;
  }
```

Lines prefixed with + are highlighted in green (additions), and lines prefixed with - are highlighted in red (deletions). This is useful for showing code changes in documentation without requiring a full Git diff.

Markdown Linting

Use markdownlint to enforce consistency across your project:

# Install markdownlint CLI
npm install -g markdownlint-cli

# Lint a file
markdownlint README.md

# Lint all Markdown files
markdownlint "docs/**/*.md"

# Auto-fix issues
markdownlint --fix README.md

Configure rules in a .markdownlint.json file at the root of your project:

{
    "MD013": false,
    "MD033": false,
    "MD041": true,
    "MD024": { "siblings_only": true }
}

12. Converting Markdown to HTML, PDF, and Slides

One of Markdown's greatest strengths is its ability to be converted to virtually any output format. The source stays simple and portable while the output can be rich and polished.

Markdown to HTML

Converting Markdown to HTML is the most common transformation and the one Markdown was originally designed for.

Online tools:

Command line with Pandoc:

# Basic conversion
pandoc input.md -o output.html

# With a standalone HTML file (includes head/body)
pandoc input.md -s -o output.html

# With a CSS stylesheet
pandoc input.md -s --css=style.css -o output.html

# With syntax highlighting
pandoc input.md -s --highlight-style=monokai -o output.html

# With table of contents
pandoc input.md -s --toc -o output.html

Programmatic conversion in JavaScript:

// Using marked.js
import { marked } from 'marked';

const markdown = '# Hello\n\nThis is **bold** text.';
const html = marked.parse(markdown);
console.log(html);
// <h1>Hello</h1>
// <p>This is <strong>bold</strong> text.</p>

// Using markdown-it
import MarkdownIt from 'markdown-it';
const md = new MarkdownIt();

const result = md.render(markdown);
console.log(result);

Programmatic conversion in Python:

import markdown

md_text = "# Hello\n\nThis is **bold** text."
html = markdown.markdown(md_text, extensions=['tables', 'fenced_code'])
print(html)

Markdown to PDF

PDF conversion is essential for distributing documentation, creating reports, and publishing ebooks.

Using Pandoc (recommended):

# Basic PDF (requires LaTeX installed)
pandoc input.md -o output.pdf

# With custom margins and font size
pandoc input.md -o output.pdf \
    -V geometry:margin=1in \
    -V fontsize=12pt

# With table of contents
pandoc input.md -o output.pdf --toc

# Using a LaTeX template
pandoc input.md -o output.pdf --template=custom.tex

# Using wkhtmltopdf instead of LaTeX
pandoc input.md -t html5 | wkhtmltopdf - output.pdf

Using VS Code: Install the "Markdown PDF" extension, then right-click on any Markdown file and select "Markdown PDF: Export (pdf)". This produces polished PDFs with minimal configuration.

Using Node.js (md-to-pdf):

# Install
npm install -g md-to-pdf

# Convert
md-to-pdf input.md

# With options
md-to-pdf input.md --pdf-options '{"format":"A4","margin":"20mm"}'

Markdown to Slides

Writing presentations in Markdown is increasingly popular because it keeps content version-controlled, shareable, and portable. Several tools make this possible:

Marp (Markdown Presentation Ecosystem):

---
marp: true
theme: default
paginate: true
---

# Slide 1: Title Slide

Author Name | February 2026

---

## Slide 2: Key Points

- First point
- Second point
- Third point

---

## Slide 3: Code Example

```javascript
function hello() {
    return "Hello from a Markdown slide!";
}
```

---



# Thank You

Questions?

Marp integrates with VS Code through the Marp extension, provides a CLI for batch conversion, and exports to HTML, PDF, and PowerPoint formats.

reveal.js: A powerful HTML presentation framework that supports Markdown content. You can write entire slides in Markdown within an HTML wrapper, or use Pandoc to convert pure Markdown to reveal.js slides:

# Convert Markdown to reveal.js slides
pandoc slides.md -t revealjs -s -o slides.html

# With a theme
pandoc slides.md -t revealjs -s -V theme=moon -o slides.html

Slidev: A developer-focused slide framework powered by Vue.js. Write slides in Markdown with support for Vue components, code highlighting, recording, and presenter mode:

# Install and create a new presentation
npm init slidev@latest

Pandoc to Beamer (LaTeX): For academic presentations:

# Convert to Beamer PDF slides
pandoc slides.md -t beamer -o slides.pdf

Markdown to Other Formats

Pandoc supports dozens of output formats from Markdown input:

# Markdown to Word document
pandoc input.md -o output.docx

# Markdown to EPUB ebook
pandoc input.md -o output.epub --metadata title="Book Title"

# Markdown to MediaWiki
pandoc input.md -t mediawiki -o output.wiki

# Markdown to reStructuredText
pandoc input.md -t rst -o output.rst

# Markdown to plain text (strips formatting)
pandoc input.md -t plain -o output.txt

# Markdown to LaTeX
pandoc input.md -o output.tex

Convert Your Markdown Now

Transform Markdown to clean HTML with our Markdown to HTML Converter, preview rendered output with Markdown Preview, or build tables visually with the Markdown Table Generator.

Conclusion

Markdown has evolved from a simple text formatting tool into the universal language of developer documentation and content creation. Its genius lies in the balance between simplicity and power — you can learn the basics in five minutes, yet the ecosystem of extensions, tools, and platforms makes it capable of producing everything from a quick README to a complete technical book.

The core skills every developer should master are headings, emphasis, lists, links, code blocks, and tables. These six elements cover the vast majority of everyday Markdown writing. From there, you can gradually adopt extended features like task lists, footnotes, callouts, and diagrams as your projects require them.

The Markdown ecosystem continues to grow. Tools like Marp bring Markdown to presentations, Obsidian has made it the foundation of personal knowledge management, and platforms like Docusaurus and VitePress prove that Markdown is more than adequate for building production documentation sites. As long as developers value simplicity, readability, and portability, Markdown will remain the dominant format for writing on the web.

Start writing Markdown today. Open our Markdown Editor, experiment with the syntax, and discover why millions of developers have made Markdown their primary writing tool.

Frequently Asked Questions

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

Standard Markdown (CommonMark) covers the basics: headings, emphasis, lists, links, images, code, and blockquotes. GitHub Flavored Markdown (GFM) extends this with tables, task lists (checkboxes), strikethrough text, autolinks for bare URLs, fenced code blocks with syntax highlighting, footnotes, alert callouts, emoji shortcodes, @mentions, issue/PR references, and Mermaid diagram rendering. GFM is the most widely adopted Markdown extension and is also supported by many tools outside of GitHub.

How do I convert Markdown to HTML, PDF, or slides?

For Markdown to HTML, you can use online tools like DevToolbox's Markdown to HTML Converter, or libraries such as marked.js, markdown-it, and Python-Markdown. For PDF conversion, Pandoc is the most powerful option (pandoc input.md -o output.pdf), and VS Code with the Markdown PDF extension also works well. For presentation slides, tools like Marp, reveal.js, and Slidev let you write slides entirely in Markdown. Pandoc can also produce slides in multiple formats including reveal.js, Beamer, and PowerPoint.

Should I use Markdown or HTML for documentation?

Markdown is the better choice for most documentation because it is faster to write, easier to read in source form, works seamlessly with version control (Git diffs are clean), and can be converted to HTML, PDF, and other formats automatically. Use HTML only when you need features Markdown does not support, such as complex layouts, custom styling, interactive elements, or precise control over rendering. Many documentation platforms like Docusaurus, MkDocs, and VitePress use Markdown as their primary authoring format and convert it to HTML automatically.

Related Posts and Resources