Markdown to HTML & PDF: A Practical Formatting Cheat Sheet for Developers, Technical Writers, and Note-Takers

Why Markdown Conquered Technical Writing

Created in 2004 by John Gruber and Aaron Swartz, **Markdown** was built on a simple premise: plain text documents should be easily readable as-is, without looking like they are filled with markup tags, while still converting cleanly into valid HTML.

Today, Markdown is the primary syntax for software engineering documentation, technical communication, and personal knowledge management:

**GitHub & GitLab:** README files, pull requests, issue tracking, and GitHub Pages.
**Modern Note Apps:** Obsidian, Notion, Bear, and Logseq.
**Static Site Generators:** Hugo, Astro, Next.js, and Docusaurus.

Writing Markdown efficiently and converting it to clean, client-facing PDF documents or HTML pages is an essential skill for modern developers and technical writers.

GitHub Flavored Markdown (GFM) Cheat Sheet

Standard CommonMark covers basics like headings and italics, but **GitHub Flavored Markdown (GFM)** adds tables, task checklists, strikethrough, and code block language flags.

1. Headings and Visual Hierarchy

# Page Title (H1 - Use only one per document)
## Major Section Heading (H2)
### Subsection Topic (H3)
#### Minor Subtopic (H4)

2. Formatted Tables with Alignment

Colons (`:`) within the delimiter row define column text alignment:

| Left-Aligned Column | Centered Column | Right-Aligned (Numbers) |
|:---|:---:|---:|
| Core Service | Active | $1,200.00 |
| Database Node | Standby | $450.00 |
| Redis Cache | Active | $120.00 |

3. Fenced Code Blocks with Syntax Highlighting

Always specify the programming language tag after the opening backticks to enable colorized syntax:

function calculateSum(a, b) {

return a + b;

}

4. Interactive Task Checklists

- [x] Configure production SSL certificates
- [x] Set up client-side pre-rendering
- [ ] Complete WCAG accessibility audit

Common Formatting Pitfalls to Avoid

**Missing Blank Lines Before Lists:** If you place a bulleted list directly below a paragraph without a blank line between them, many Markdown parsers will render the list as a single continuous paragraph.
**Forgetting Language Identifiers on Code Blocks:** Leaving code blocks unflagged (``` instead of ```bash or ```python) disables syntax highlighting in documentation viewers.
**Inconsistent Tab vs Space Indentation:** Indenting sub-lists with mixed tabs and spaces causes layout issues across different Markdown compilers. Standardize on **2 or 4 spaces**.

Exporting Markdown to Clean HTML & PDF

Need to write notes in Markdown and deliver a formatted PDF to a client, manager, or professor?

Using [ToolInPocket's Markdown Editor & Previewer](/tools/markdown-editor):

Write or paste your Markdown in the left-hand editor.
Preview live rendered HTML on the right in real time.
Click **Export HTML** to download clean web markup, or use **Print to PDF** for a styled print document.

All rendering executes locally inside your browser, keeping your internal technical notes and private documentation secure on your machine.

Frequently Asked Questions

Can I include raw HTML inside a Markdown document?

Yes. Standard Markdown allows inline HTML elements (such as `<span>`, `<kbd>`, or `<details>`) for formatting tasks that native Markdown syntax does not support.

What is the difference between standard Markdown and CommonMark?

Standard original Markdown had ambiguities in how edge cases (like nested lists) should be parsed. CommonMark is a rigorous, standardized specification that ensures your Markdown renders identically across all compliant parsers.