Skip to main content
Image Converter Video Converter Audio Converter Document Converter
Tools Guides Formats Pricing API
Log In
🇪🇸 Español 🇧🇷 Português 🇩🇪 Deutsch
Guide

Markdown: The Complete Guide to .md Format

PC By Pablo Cirre •

Markdown: The Complete Guide to .md Format

In 2004, John Gruber and Aaron Swartz created Markdown with a simple goal: let people write using plain text that is easy to read and easy to convert to HTML. Two decades later, Markdown has become the dominant format for technical documentation, README files, blogging, note-taking, and online writing — used on GitHub, Stack Overflow, Reddit, Discord, Notion, Obsidian, and hundreds of other platforms. Understanding Markdown means understanding how most technical writing on the internet actually works.

What Is Markdown?

Markdown is a lightweight markup language that uses simple punctuation characters to indicate formatting. A Markdown file has the .md extension (sometimes .markdown). The genius of Markdown is that it is already readable as plain text — the formatting characters are intuitive rather than cryptic:

# This is a heading

This is a paragraph with **bold text**, *italic text*, and `inline code`.

- First list item
- Second list item
- Third list item

1. Ordered item one
2. Ordered item two

[Visit GitHub](https://github.com)

![Alt text for image](image.jpg)

> This is a blockquote

---

| Column 1 | Column 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Core Markdown Syntax

Headings

# H1 — Page or document title
## H2 — Major section
### H3 — Subsection
#### H4 — Sub-subsection

Emphasis

**bold text** or __bold text__
*italic text* or _italic text_
***bold and italic***
~~strikethrough~~

Links and Images

[link text](https://url.com)
[link text](https://url.com "Optional title")
[reference link][ref-id]
[ref-id]: https://url.com

![image alt text](image.jpg)
![image alt text](image.jpg "Optional title")

Lists

- Unordered item (use -, *, or +)
  - Nested item (indent with 2 or 4 spaces)
    - Deeper nesting

1. Ordered item
2. Another item
3. Third item

- [x] Completed task (GitHub Flavored Markdown)
- [ ] Incomplete task

Code

`inline code` — single backticks for inline

​```python
# Fenced code block with language specifier
def hello():
    print("Hello, Markdown!")
​```

Blockquotes

> This is a blockquote
>
> It can span multiple paragraphs
>
> > Nested blockquotes work too

Horizontal Rules

---
or
***
or
___

Tables (GFM extension)

| Header 1 | Header 2 | Header 3 |
|----------|:--------:|----------:|
| Left     | Center   | Right     |
| aligned  | aligned  | aligned   |

Markdown Flavors and Specifications

A key source of Markdown confusion: there is no single standard. John Gruber defined core Markdown syntax but left many edge cases ambiguous, leading to a proliferation of variants:

CommonMark: a strict, unambiguous specification (commonmark.org, 2014). Defines how every edge case should be handled. Many platforms have adopted CommonMark as their base.

GitHub Flavored Markdown (GFM): CommonMark plus tables, task lists, strikethrough, autolinks, and fenced code blocks with syntax highlighting. Used everywhere on GitHub.

MultiMarkdown (MMD): adds footnotes, citation support, metadata, definition lists, math (via MathJax), and cross-references. Popular in academic writing.

Pandoc Markdown: Pandoc's extended dialect with footnotes, citations ([@citation-key]), YAML metadata blocks, grid tables, definition lists, and more. The most powerful Markdown flavor for document conversion.

R Markdown (.Rmd): Markdown + embedded R code chunks that execute when rendered. Used in data science and statistical analysis (R/Python).

MDX: Markdown + JSX React components. Used in modern documentation sites and blogs.

How Markdown Is Converted to HTML

Every Markdown renderer parses the .md file and converts the syntax to HTML elements:

Markdown HTML
# Heading <h1>Heading</h1>
**bold** <strong>bold</strong>
*italic* <em>italic</em>
[link](url) <a href="url">link</a>
![alt](img.jpg) <img src="img.jpg" alt="alt">
`code` <code>code</code>

The HTML is then styled by CSS (or a design system) to produce the visual output.

Platform-Specific Markdown

GitHub

GitHub renders Markdown in README files, issues, pull requests, comments, and wikis using GFM. Key GFM extensions: fenced code blocks with syntax highlighting, task lists, tables, emoji shortcodes (:smile:), mentions (@username), issue references (#123), SHA hash references.

Stack Overflow

Uses a modified Markdown with code block formatting and HTML stripping for security. Does not support tables in all contexts.

Reddit

Uses Reddit-flavored Markdown (Old Reddit) or a custom rich text editor (New Reddit). Old Reddit supports standard Markdown; New Reddit converts to a proprietary rich text format internally.

Discord

Uses a subset of Markdown: bold/italic/underline/strikethrough, inline code, code blocks, block quotes, spoiler tags (||spoiler||).

Notion, Obsidian, Bear

Note-taking apps use Markdown as their base with proprietary extensions for backlinks ([[Page Name]]), callouts, and database properties.

Converting Markdown

Markdown → HTML: every Markdown library does this — Marked.js (JavaScript), Python-Markdown, CommonMark parsers in every language.

Markdown → PDF: use Pandoc: pandoc input.md -o output.pdf (requires LaTeX for PDF output) or pandoc input.md --pdf-engine=wkhtmltopdf -o output.pdf

Markdown → Word (.docx): pandoc input.md -o output.docx — produces a properly structured Word document with styles matching Markdown structure

Markdown → Slides: Marp, Reveal.js, or Pandoc with --to revealjs create presentation slides from Markdown

HTML → Markdown: Pandoc: pandoc -f html -t markdown input.html -o output.md; also Turndown (JavaScript), html2text (Python)

Word → Markdown: pandoc input.docx -t markdown -o output.md — useful for migrating content to static site generators

Markdown in Static Site Generators

Markdown is the primary content format for nearly every static site generator:

  • Jekyll (GitHub Pages default): processes .md files with front matter YAML, used by millions of GitHub Pages sites
  • Hugo: exceptionally fast Markdown processor with shortcodes and templating
  • Gatsby, Next.js: React-based, process Markdown via MDX or unified
  • MkDocs: Markdown-first documentation sites (used by FastAPI, Pydantic, and many Python libraries)
  • Docusaurus: Facebook's documentation framework, MDX-based
  • Eleventy (11ty): flexible, supports Markdown, HTML, Liquid, Nunjucks

The static site generator workflow: write content in .md files → generator processes Markdown → outputs static HTML/CSS/JS → deploy to CDN.

Markdown for README Files

The README.md file in a GitHub repository is the face of open-source projects. Best practices:

  1. Start with a clear project description and badges (build status, license, version)
  2. Installation instructions with copy-pasteable code blocks
  3. Quick start example with a code block
  4. Feature list
  5. Link to full documentation
  6. Contributing guidelines and license

Markdown's simplicity — readable as raw text, renders beautifully in browsers — makes it the perfect format for documentation that lives alongside code in version control.

Related conversions

Document conversions that follow this topic naturally:

Related conversions

Put what you just learned into practice — convert your files now in seconds, free and without registration.

md → pdf
Convert →
md → html
Convert →
md → docx
Convert →
md → epub
Convert →
docx → md
Convert →
md → odt
Convert →

Frequently Asked Questions

Markdown is a lightweight markup language that uses simple punctuation to indicate formatting — `**bold**`, `*italic*`, `# Heading`, `[link](url)`. A .md file (or .markdown) is a plain text file written in Markdown syntax. It is readable as-is in any text editor, and can be rendered to styled HTML by any Markdown processor. GitHub, Notion, Obsidian, Reddit, Discord, Stack Overflow, and hundreds of other platforms render Markdown. It is the most widely used format for technical documentation, README files, and online writing.

Markdown is a lightweight markup language that uses simples punctuation to indicate formatoting — `**bold**`, `*italic*`, `# Heading`, `[link](url)`. A .md arquivo (or .markdown) is a plain text arquivo written in Markdown syntax. It is readable as-is in any text editor, e can be rendered to styled HTML by any Markdown processor. GitHub, Notion, Obsidian, Reddit, Discord, Stack Overflow, e hundreds of other plataformas render Markdown. It is the most widely used formato para technical documentation, README files, e online writing.

Markdown is a lightweight markup language that uses einfach punctuation to indicate Formatting — `**bold**`, `*italic*`, `# Heading`, `[link](url)`. A .md Datei (or .markdown) is a plain text Datei written in Markdown syntax. It is readable as-is in any text editor, und can be rendered to styled HTML by any Markdown processor. GitHub, Notion, Obsidian, Reddit, Discord, Stack Overflow, und hundreds von other Plattformen render Markdown. It is the most widely used Format für technical documentation, README files, und online writing.

Markdown is a lightweight markup language that uses simple punctuation to indicate formatoting — `**bold**`, `*italic*`, `# Heading`, `[link](url)`. A .md archivo (or .markdown) is a plain text archivo written in Markdown syntax. It is readable as-is in any text editor, y can be rendered to styled HTML by any Markdown processor. GitHub, Notion, Obsidian, Reddit, Discord, Stack Overflow, y hundreds de other plataformas render Markdown. It is the most widely used formato para technical documentation, README files, y online writing.

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 original Markdown specification by John Gruber (2004) left many edge cases ambiguous, so different platforms created their own variants. CommonMark (2014) is a strict, unambiguous specification that resolves all edge cases — the best "standard" Markdown. GitHub Flavored Markdown (GFM) is CommonMark plus tables, task lists (`- [x]`), strikethrough (`~~text~~`), and fenced code blocks with syntax highlighting. Pandoc Markdown is the most powerful: adds footnotes, citations, YAML metadata, definition lists, and is ideal for converting Markdown to Word/PDF/LaTeX.

The original Markdown specification by John Gruber (2004) left many edge cases ambiguous, so different plataformas created their own variants. CommonMark (2014) is a strict, unambiguous specification that resolves all edge cases — the best "standard" Markdown. GitHub Flavored Markdown (GFM) is CommonMark plus tables, task lists (`- [x]`), strikethrough (`~~text~~`), e fenced code blocks com syntax altalighting. Pandoc Markdown is the most powerful: adds footnotes, citations, YAML metadata, definition lists, e is ideal para convertendo Markdown to Word/PDF/LaTeX.

The original Markdown specification by John Gruber (2004) left many edge cases ambiguous, so different Plattformen created their own variants. CommonMark (2014) is a strict, unambiguous specification that resolves all edge cases — the best "standard" Markdown. GitHub Flavored Markdown (GFM) is CommonMark plus tables, task lists (`- [x]`), strikethrough (`~~text~~`), und fenced code blocks mit syntax hochlighting. Pandoc Markdown is the most powerful: adds footnotes, citations, YAML metadata, definition lists, und is ideal für umwandelnd Markdown to Word/PDF/LaTeX.

The original Markdown specification by John Gruber (2004) left many edge cases ambiguous, so different plataformas created their own variants. CommonMark (2014) is a strict, unambiguous specification that resolves all edge cases — the best "standard" Markdown. GitHub Flavored Markdown (GFM) is CommonMark plus tables, task lists (`- [x]`), strikethrough (`~~text~~`), y fenced code blocks con syntax altalighting. Pandoc Markdown is the most powerful: adds footnotes, citations, YAML metadata, definition lists, y is ideal para convirtiendo Markdown to Word/PDF/LaTeX.

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.

The most powerful tool is Pandoc (pandoc.org, free): `pandoc input.md -o output.pdf`. Pandoc requires a LaTeX engine (install TeX Live or MiKTeX) for PDF output; alternatively use `--pdf-engine=wkhtmltopdf` for HTML-to-PDF conversion which does not require LaTeX. For a simpler option, VS Code with the "Markdown PDF" extension converts .md to PDF directly. GitHub also renders Markdown and you can print any GitHub Markdown page to PDF from the browser.

The most powerful tool is Pandoc (pandoc.org, grátis): `pandoc input.md -o output.pdf`. Pandoc requires a LaTeX engine (install TeX Live ou MiKTeX) para PDF output; alternatively usar `--pdf-engine=wkhtmltopdf` para HTML-to-PDF conversion which does not require LaTeX. para a simplesr option, VS Code com the "Markdown PDF" extension converts .md to PDF directly. GitHub also renders Markdown e you can print any GitHub Markdown page to PDF de o navegador.

The most powerful tool is Pandoc (pandoc.org, kostenlos): `pandoc input.md -o output.pdf`. Pandoc requires a LaTeX engine (install TeX Live oder MiKTeX) für PDF output; alternatively verwenden `--pdf-engine=wkhtmltopdf` für HTML-to-PDF conversion which does not require LaTeX. für a einfachr option, VS Code mit the "Markdown PDF" extension converts .md to PDF directly. GitHub also renders Markdown und you can print any GitHub Markdown page to PDF von der Browser.

The most powerful tool is Pandoc (pandoc.org, gratis): `pandoc input.md -o output.pdf`. Pandoc requires a LaTeX engine (install TeX Live o MiKTeX) para PDF output; alternatively usar `--pdf-engine=wkhtmltopdf` para HTML-to-PDF conversion which does not require LaTeX. para a simpler option, VS Code con the "Markdown PDF" extension converts .md to PDF directly. GitHub also renders Markdown y you can print any GitHub Markdown page to PDF de el navegador.

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.

Yes, with Pandoc: `pandoc input.docx -t markdown -o output.md`. Pandoc converts headings, bold/italic, lists, tables, and images with reasonable fidelity. The result will need some cleanup — especially for complex Word formatting like tracked changes, text boxes, and custom styles that have no Markdown equivalent. For the reverse (Markdown to Word): `pandoc input.md -o output.docx` produces a properly structured Word document with heading styles, which you can then further format in Word.

Sim, com Pandoc: `pandoc input.docx -t markdown -o output.md`. Pandoc converts headings, bold/italic, lists, tables, e images com reasonable fidelity. The result will need some cleanup — especially para complexo Word formatoting like tracked changes, text boxes, e custom styles that have no Markdown equivalent. para the reverse (Markdown to Word): `pandoc input.md -o output.docx` produces a properly structured Word document com heading styles, which you can then further formato in Word.

Ja, mit Pandoc: `pandoc input.docx -t markdown -o output.md`. Pandoc converts headings, bold/italic, lists, tables, und images mit reasonable fidelity. The result will need some cleanup — especially für complex Word Formatting like tracked changes, text boxes, und custom styles that have no Markdown equivalent. für the reverse (Markdown to Word): `pandoc input.md -o output.docx` produces a properly structured Word document mit heading styles, which you can then further Format in Word.

Sí, con Pandoc: `pandoc input.docx -t markdown -o output.md`. Pandoc converts headings, bold/italic, lists, tables, y images con reasonable fidelity. The result will need some cleanup — especially para complex Word formatoting like tracked changes, text boxes, y custom styles that have no Markdown equivalent. para the reverse (Markdown to Word): `pandoc input.md -o output.docx` produces a properly structured Word document con heading styles, which you can then further formato in Word.

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.