Markdown: Complete Syntax Guide and Conversion
Markdown is a lightweight markup language created by John Gruber in 2004. Its goal: write formatted text using simple ASCII characters that produce well-structured HTML. Today it's the documentation standard on GitHub, GitLab, Notion, Obsidian, Reddit and thousands of tools.
Basic Syntax
Headings
# H1 — Main title
## H2 — Section
### H3 — Subsection
#### H4
##### H5
###### H6
Emphasis and Bold
*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~
Lists
# Unordered
- Item A
- Item B
- Sub-item B1
# Ordered
1. First
2. Second
3. Third
# Task list (GFM)
- [x] Completed task
- [ ] Pending task
Code
Inline: `const x = 42;`
Code block:
```javascript
function greet(name) {
return 'Hello, ' + name + '!';
}
```
```python
def greet(name: str) -> str:
return f"Hello, {name}!"
```
```bash
echo "Hello world"
grep -r "pattern" ./directory/
```
Quotes, Rules and Links
> Block quote with **formatting**.
> > Nested quote.
---
[Link text](https://example.com "Optional tooltip")
Tables (GFM)
| Column A | Column B | Column C |
|:----------|:--------:|---------:|
| Left | Center | Right |
| Cell 1 | Cell 2 | Cell 3 |
Footnotes and Math
Text with footnote[^1].
[^1]: Footnote content.
Inline formula: $E = mc^2$
Block:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
Embedded HTML
<details>
<summary>Click to expand</summary>
Hidden content with **Markdown** inside.
</details>
<kbd>Ctrl</kbd> + <kbd>C</kbd>
<mark>Highlighted text</mark>
Convert with Pandoc
# Install
sudo apt-get install pandoc # Ubuntu
brew install pandoc # macOS
winget install pandoc # Windows
# Conversions
pandoc README.md -o README.html
pandoc README.md -s -o README.html # Standalone HTML
pandoc article.md -o article.pdf # Requires LaTeX
pandoc article.md -o article.docx # Word
pandoc book.md --metadata title="My Book" -o book.epub
pandoc slides.md -t revealjs -s -o slides.html
pandoc ch01.md ch02.md ch03.md -o book.pdf
pandoc doc.md --reference-doc=template.docx -o doc.docx
Python with markdown-it-py
from markdown_it import MarkdownIt
md = MarkdownIt()
text = """
# Hello World
Paragraph with **bold** and *italic*.
- Item 1
- Item 2
"""
html = md.render(text)
print(html)
python-markdown with Extensions
import markdown
text_md = """
# Title
| Col A | Col B |
|-------|-------|
| 1 | 2 |
Footnote[^1].
[^1]: Content.
"""
html = markdown.markdown(text_md, extensions=[
'tables', 'footnotes', 'codehilite',
'fenced_code', 'toc', 'nl2br',
])
print(html)
Markdown to PDF with Python
import markdown
from weasyprint import HTML
def md_to_pdf(md_file, pdf_file):
with open(md_file, 'r', encoding='utf-8') as f:
md_content = f.read()
html_content = markdown.markdown(md_content, extensions=[
'tables', 'fenced_code', 'toc'
])
css = """<style>
body { font-family: Georgia, serif; max-width: 700px; margin: 40px auto; line-height: 1.6; }
h1, h2, h3 { font-family: Arial, sans-serif; color: #1a202c; }
code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; }
pre { background: #f4f4f4; padding: 16px; overflow-x: auto; }
table { border-collapse: collapse; width: 100%; }
th, td { border: 1px solid #ddd; padding: 8px; }
</style>"""
final_html = "<!DOCTYPE html><html><head>" + css + "</head><body>" + html_content + "</body></html>"
HTML(string=final_html).write_pdf(pdf_file)
print(f"PDF generated: {pdf_file}")
md_to_pdf("README.md", "README.pdf")
Editors and Tools
| Tool | Type | Description |
|---|---|---|
| markdownlint | CLI/VS Code | Style linting |
| Prettier | CLI/editor | Auto-format |
| Typora | Editor | Native WYSIWYG |
| Obsidian | Notes app | Knowledge graph |
| VS Code | IDE | Preview + extensions |
| HackMD | Online | Real-time collaborative |
Convert Online
To convert Markdown to HTML, PDF, DOCX or EPUB without installing software, KaijuConverter offers the conversion directly in your browser.
Related conversions
Document conversions that follow this topic naturally: