Guide

Markdown Format: The Complete Guide to Lightweight Markup

PC By Pablo Cirre • Updated May 7, 2026

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004, designed to be readable as plain text while also converting cleanly to HTML. The core philosophy: the source should look good as plain text, not be cluttered with tags. An .md or .markdown file is plain text that any text editor can open, but that rendering tools convert to formatted HTML, PDF, DOCX, or other formats.

Markdown is now ubiquitous in technical writing:

GitHub, GitLab, Bitbucket: All README files, wikis, and issue comments use Markdown
Static site generators: Jekyll, Hugo, Gatsby, Astro all use Markdown for content
Documentation platforms: ReadTheDocs, GitBook, Docusaurus, MkDocs
Note-taking apps: Obsidian, Logseq, Notion, Bear, iA Writer
Developer tools: Jupyter notebooks, VS Code preview, Slack (subset), Discord

Markdown Syntax

Headings

# Heading 1 (H1) — one # sign
## Heading 2 (H2) — two # signs
### Heading 3 (H3)
#### Heading 4 (H4)

Alternate syntax (Setext style):
Heading 1
=========

Heading 2
---------

Emphasis

**Bold text** or __bold__
*Italic text* or _italic_
***Bold and italic*** or ___triple underscores___
~~Strikethrough~~ (GFM extension)
`Inline code` — monospace, not processed

Lists

Unordered list:
- Item one
- Item two
  - Nested item (2-space or tab indent)
  - Another nested
- Item three

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

Mixed:
1. Ordered top-level
   - Unordered nested
   - Another nested item

Links and Images

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

![Alt text](image.png)
![Alt text](image.png "Image title")
![Reference image][img-id]
[img-id]: image.png "Optional title"

Autolinks: <https://example.com>

Blockquotes and Code

> This is a blockquote.
> It can span multiple lines.
>> Nested blockquote

Fenced code block (specify language for syntax highlighting):
```python
def hello(name):
    return f"Hello, {name}!"

Indented code block (4 spaces): def hello(): pass


### Horizontal Rules
```markdown
--- (three or more hyphens)
*** (three or more asterisks)
___ (three or more underscores)

Markdown Flavors and Specs

The original Markdown spec (2004) was underspecified, leading to inconsistent implementations. Several standardization efforts emerged:

CommonMark

A strict, unambiguous specification (spec.commonmark.org, 2014+) that resolves ambiguities in Gruber's original spec. Defines exactly how edge cases behave. Used by GitHub (as base for GFM), Reddit, Stack Overflow.

GFM (GitHub Flavored Markdown)

A CommonMark superset with GitHub-specific extensions:

Tables (pipe syntax)
Task lists (checkboxes)
Strikethrough (~~text~~)
Autolinks (bare URLs become links)
Fenced code blocks with language specifier

GFM Tables

| Column 1 | Column 2 | Column 3 |
|----------|:--------:|----------:|
| Left     | Center   | Right    |
| Aligned  | Aligned  | Aligned  |

Minimum valid table:
| A | B |
|---|---|
| 1 | 2 |

GFM Task Lists

- [x] Completed task
- [x] Another done item
- [ ] Pending task
- [ ] Another to-do

MultiMarkdown (MMD)

Extended with metadata (frontmatter), footnotes, citations, definition lists, math (LaTeX syntax), file transclusion. Used in academic and technical writing.

Pandoc Markdown

The most feature-rich flavor, adding:

YAML frontmatter metadata
Citations and bibliographies ([@citation-key])
Footnotes ([^1])
Definition lists
Superscript/subscript (H~2~O, x^2^)
Math blocks ( $...$ , $$...$$)
Div and span with attributes

YAML Frontmatter

Many Markdown processors support YAML frontmatter — structured metadata at the top of a file between --- delimiters:

---
title: "My Document"
author: "Jane Smith"
date: 2025-03-15
tags: [programming, documentation]
draft: false
toc: true
---

# First Heading

Document content begins here...

Frontmatter is used by static site generators (Hugo, Jekyll, Gatsby) and Pandoc for document metadata.

Converting Markdown

Pandoc — The Universal Converter

# Markdown to HTML
pandoc input.md -o output.html

# Markdown to standalone HTML (with CSS)
pandoc -s input.md -o output.html --css styles.css

# Markdown to PDF (requires LaTeX)
pandoc input.md -o output.pdf

# Markdown to PDF via HTML (no LaTeX needed, uses wkhtmltopdf)
pandoc input.md -t html | wkhtmltopdf - output.pdf

# Markdown to DOCX
pandoc input.md -o output.docx

# Markdown to DOCX with custom template
pandoc input.md --reference-doc=template.docx -o output.docx

# Markdown to EPUB
pandoc input.md -o output.epub --epub-cover-image=cover.jpg

# Markdown with citations to PDF
pandoc input.md --bibliography refs.bib --csl apa.csl -o output.pdf

# Multiple Markdown files concatenated
pandoc chapter1.md chapter2.md chapter3.md -o book.pdf

Python Markdown Processing

import markdown

# Basic Markdown to HTML
with open('input.md') as f:
    text = f.read()

html = markdown.markdown(text, extensions=[
    'tables',
    'fenced_code',
    'codehilite',
    'toc',
    'footnotes',
])

print(html)

Node.js (marked, remark)

import { marked } from 'marked';
import { readFileSync } from 'fs';

const md = readFileSync('input.md', 'utf-8');
const html = marked.parse(md);
console.log(html);

// With custom renderer
const renderer = new marked.Renderer();
renderer.heading = (text, level) => `<h${level} class="heading-${level}">${text}</h${level}>`;
marked.setOptions({ renderer });

CLI tools

# markdown-it (Node.js)
npx markdown-it input.md > output.html

# cmark (CommonMark reference implementation in C)
cmark input.md > output.html
cmark --to latex input.md > output.tex

# mdBook (Rust, for book-like output)
mdbook build --dest-dir ./book ./

Markdown Linting and Validation

Markdown linting catches style inconsistencies:

# markdownlint (Node.js)
npm install -g markdownlint-cli
markdownlint **/*.md

# Common rules:
# MD013: Line length (default 80 chars)
# MD022: Headings should be surrounded by blank lines
# MD032: Lists should be surrounded by blank lines
# MD041: First line should be a top-level heading

Markdown vs Alternative Lightweight Markup Languages

Feature	Markdown	reStructuredText (RST)	AsciiDoc	Org-mode
Learning curve	Lowest	Medium	Medium	High
Spec conformance	GFM/CommonMark	Docutils spec	AsciiDoc spec	Emacs Org spec
Math support	Via MathJax/KaTeX	Decent	Good	Excellent
Cross-references	Limited	Full (RST roles)	Full	Full
Output targets	HTML, PDF, DOCX	HTML, PDF, EPUB	HTML, PDF, EPUB, DocBook	HTML, PDF, LaTeX
Primary use	Dev docs, GitHub	Python docs (Sphinx)	Technical books, docs	Emacs power users
Table support	GFM only	Full	Full	Full

Markdown Best Practices

For documentation:

Use ATX headings (#) rather than Setext headings
Keep lines under 100 characters (easier diffs in version control)
Always add alt text to images
Use reference-style links for readability in dense documents
Add blank lines before and after headings and code blocks
Use sentence-case for headings (not Title Case) in technical docs

For maintainability:

Validate frontmatter schema (YAML linting)
Use a linter (markdownlint) in CI pipelines
Pin the Pandoc/remark version to avoid behavior changes
Store images near the Markdown files they reference (relative paths)

Markdown's enduring appeal lies in its balance: enough structure to enable automation, enough simplicity to remain readable as source code. That balance has made it the de facto standard for developer-facing documentation in a remarkably short time.

Related conversions

Document conversions that follow this topic naturally:

Frequently Asked Questions

CommonMark is a strict, unambiguous specification of Markdown that resolves the many edge cases the original 2004 spec left undefined. Original Markdown was underspecified — different tools handled the same input differently. CommonMark defines exact behavior for every case, enabling consistent rendering across parsers. GitHub uses CommonMark as the base for GFM (GitHub Flavored Markdown), adding tables, task lists, and strikethrough on top. If you write standard CommonMark, it renders consistently everywhere; original Markdown syntax may vary.

CommonMark is a strict, unambiguous specification of Markdown that resolves the many edge cases the original 2004 spec left undefined. Original Markdown was underspecified — different ferramentas handled the same input differently. CommonMark defines exact behavior para every case, enabling consistent rendering across parsers. GitHub uses CommonMark como o base para GFM (GitHub Flavored Markdown), adding tables, task lists, e strikethrough on top. If you write padrão CommonMark, it renders consistently everywhere; original Markdown syntax may vary.

CommonMark is a strict, unambiguous specification von Markdown that resolves the many edge cases the original 2004 spec left undefined. Original Markdown was underspecified — different Werkzeuge handled the same input differently. CommonMark defines exact behavior für every case, enabling consistent rendering across parsers. GitHub uses CommonMark als das base für GFM (GitHub Flavored Markdown), adding tables, task lists, und strikethrough on top. If you write Standard CommonMark, it renders consistently everywhere; original Markdown syntax may vary.

CommonMark is a strict, unambiguous specification de Markdown that resolves the many edge cases the original 2004 spec left undefined. Original Markdown was underspecified — different herramientas handled the same input differently. CommonMark defines exact behavior para every case, enabling consistent rendering across parsers. GitHub uses CommonMark como el base para GFM (GitHub Flavored Markdown), adding tables, task lists, y strikethrough on top. If you write estándar CommonMark, it renders consistently everywhere; original Markdown syntax may vary.

Send <strong>PDF</strong> when the document is final and the layout must be preserved exactly (contracts, invoices, certificates). Send <strong>DOCX</strong> when reviewers need to edit, comment, or track changes. Many teams send both: PDF as the canonical version + DOCX for editable feedback. PDF/A is the right pick for legal archival (ISO 19005).

The easiest approach is Pandoc: `pandoc input.md -o output.pdf` (requires LaTeX installed, like TeX Live or MiKTeX). For a route without LaTeX, pipe through HTML first: `pandoc input.md -t html | wkhtmltopdf - output.pdf`. VS Code with the "Markdown PDF" extension can also export directly. For professional typesetting, Pandoc with a LaTeX template gives the best results. For quick PDFs, browser print from a rendered preview (GitHub, Typora, or any Markdown editor) works well.

The easiest approach is Pandoc: `pandoc input.md -o output.pdf` (requires LaTeX installed, like TeX Live ou MiKTeX). para a route sem LaTeX, pipe através de HTML first: `pandoc input.md -t html | wkhtmltopdf - output.pdf`. VS Code com the "Markdown PDF" extension can also export directly. para profissional typesetting, Pandoc com a LaTeX template gives the best results. para quick PDFs, browser print de a rendered preview (GitHub, Typora, ou any Markdown editor) funciona well.

The easiest approach is Pandoc: `pandoc input.md -o output.pdf` (requires LaTeX installed, like TeX Live oder MiKTeX). für a route ohne LaTeX, pipe durch HTML first: `pandoc input.md -t html | wkhtmltopdf - output.pdf`. VS Code mit the "Markdown PDF" extension can also export directly. für professionell typesetting, Pandoc mit a LaTeX template gives the best results. für quick PDFs, browser print von a rendered preview (GitHub, Typora, oder any Markdown editor) works well.

The easiest approach is Pandoc: `pandoc input.md -o output.pdf` (requires LaTeX installed, like TeX Live o MiKTeX). para a route sin LaTeX, pipe a través de HTML first: `pandoc input.md -t html | wkhtmltopdf - output.pdf`. VS Code con the "Markdown PDF" extension can also export directly. para profesional typesetting, Pandoc con a LaTeX template gives the best results. para quick PDFs, browser print de a rendered preview (GitHub, Typora, o any Markdown editor) works well.

Round-tripping between similar formats (DOCX ↔ ODT, DOCX → PDF) is generally safe. Round-tripping with format-specific features (Word macros, complex tables, footnotes) often loses fidelity. Embedded fonts survive only if both source and target support font embedding (PDF yes, DOCX yes, plain HTML no). Always preview the result before deleting the original.

YAML frontmatter is a block of YAML metadata at the very start of a Markdown file, delimited by triple dashes (---). It stores structured data about the document: title, author, date, tags, categories, draft status, etc. Static site generators (Hugo, Jekyll, Gatsby) and Pandoc read frontmatter to populate templates and document metadata. Example: `---\ntitle: "My Post"\ndate: 2025-03-15\ntags: [web, tutorial]\n---` followed by the Markdown content. Frontmatter is not rendered as content — it's pure metadata.

YAML frontmatter is a block von YAML metadata at the very start eines Markdown file, delimited by triple dashes (---). It stores structured data about the document: title, author, date, tags, categories, draft status, etc. Static site generators (Hugo, Jekyll, Gatsby) und Pandoc read frontmatter to populate templates und document metadata. Example: `---\ntitle: "My Post"\ndate: 2025-03-15\ntags: [web, tutorial]\n---` followed by the Markdown content. Frontmatter is not rendered as content — it's pure metadata.

YAML frontmatter is a block de YAML metadata at the very start de un Markdown file, delimited by triple dashes (---). It stores structured data about the document: title, author, date, tags, categories, draft status, etc. Static site generators (Hugo, Jekyll, Gatsby) y Pandoc read frontmatter to populate templates y document metadata. Example: `---\ntitle: "My Post"\ndate: 2025-03-15\ntags: [web, tutorial]\n---` followed by the Markdown content. Frontmatter is not rendered as content — it's pure metadata.

If the PDF contains real text (not scanned images), <code>pdftotext</code> from poppler-utils or <a href="/convert/pdf-to-txt">PDF to TXT</a> works in seconds. If the PDF is a scanned image, you need OCR — Tesseract is the open-source standard. KaijuConverter's PDF tools auto-detect text-vs-image PDFs and route accordingly.

Not natively, but many Markdown environments support LaTeX math through JavaScript rendering libraries (MathJax or KaTeX). GitHub renders inline math with single dollar signs `$x^2 + y^2 = r^2$` and display math with double dollars `$$\int_0^\infty f(x)\,dx$$` in Markdown since 2022. Pandoc supports LaTeX math natively. Jupyter notebooks render LaTeX math in Markdown cells. reStructuredText (RST) and AsciiDoc have better built-in math support if math is central to your content.

Light edits (annotations, signatures, form fields) are fine in any PDF reader. Structural edits (changing paragraphs, replacing images) are awkward — PDF is a presentation format, not an editing format. The robust workflow is: keep the source DOCX/MD/HTML as the master, regenerate the PDF when changes are needed. Tools that "edit PDFs" reverse-engineer the layout and frequently break it.