Markdown to HTML Guide: Syntax to Advanced Formatting

Documents

Why Markdown?

Markdown is the de facto standard for technical documentation — GitHub, Stack Overflow, Notion, and VS Code all support it natively.

Comparison Markdown Word HTML
Learning curve Low Medium High
Version control ✅ Plain text ❌ Binary ✅ Plain text
Readability ✅ Source reads like a document ❌ ❌
Expressiveness Medium (strong with extensions) Strong Strong
Rendering consistency Medium ❌ Varies by platform ✅

Basic Syntax Cheat Sheet

Headings

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

Emphasis

**bold**      → <strong>bold</strong>
*italic*      → <em>italic</em>
~~strikethrough~~  → <del>strikethrough</del>
`inline code`  → <code>inline code</code>

Lists

- Unordered item 1
- Unordered item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2
   1. Nested ordered item

- [ ] Todo (incomplete)
- [x] Todo (complete)

[Link text](https://example.com)
[Link with title](https://example.com "Title")
![Image alt text](image.png)
![Image with title](image.png "Image title")

Blockquotes and Horizontal Rules

> Quoted text
> > Nested quote

---

GFM Extended Syntax

Tables

| Left-aligned | Centered | Right-aligned |
|:-------------|:--------:|--------------:|
| Content      | Content  | Content       |
| Long content | Short    | Medium        |

Rendered result:

Left-aligned Centered Right-aligned
Content Content Content
Long content Short Medium

Task Lists

- [x] Requirements analysis
- [x] Technical design
- [ ] Implementation
- [ ] Testing and acceptance

Fenced Code Blocks

```javascript
function hello() {
  console.log('Hello, Markdown!');
}
```

```python
def hello():
    print("Hello, Markdown!")
```

Footnotes

Here is a paragraph[^1], and another one[^note].

[^1]: Content of the first footnote.
[^note]: A footnote with a custom ID.

Advanced Formatting Techniques

1. Math Formulas (KaTeX/MathJax)

Inline formula: $E = mc^2$

Block formula:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Matrix:
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$

2. Mermaid Diagrams

```mermaid
graph TD
    A[User request] --> B{Auth check}
    B -->|Authenticated| C[Fetch data]
    B -->|Unauthenticated| D[Return 401]
    C --> E[Render page]
```

Supported diagram types:

Type Syntax Keyword Use Case
Flowchart graph Business processes, decision trees
Sequence diagram sequenceDiagram API calls, interaction flows
Class diagram classDiagram Object-oriented design
State diagram stateDiagram State machines
Gantt chart gantt Project scheduling
Pie chart pie Data proportions

3. Table of Contents (TOC)

<!-- Auto-generated TOC -->
[[toc]]

<!-- Or manually -->
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)

4. Definition Lists

Term 1
: Definition 1

Term 2
: Definition 2

5. Abbreviations

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

HTML is a standard maintained by the W3C.

Converting Markdown with the Toolbox

Steps

  1. Open the Markdown Editor
  2. Type Markdown in the left editing pane
  3. The right pane previews the rendered HTML in real time
  4. Switch to "Source" mode to view the generated HTML
  5. Export as an HTML file

Supported Extensions

Extension Description Example
GFM Tables, task lists, footnotes GitHub style
Math formulas KaTeX rendering $E=mc^2$
Mermaid Diagram rendering Flowcharts, sequence diagrams
Syntax highlighting Prism.js/highlight.js Code block coloring
Emoji :smile: → 😄 Shortcode replacement

How Markdown-to-HTML Conversion Works

The Parsing Pipeline

Markdown text
  ↓
Lexical analysis (Lexer) → Token stream
  ↓
Syntax analysis (Parser) → AST (Abstract Syntax Tree)
  ↓
Renderer → HTML string

Mainstream Parsing Libraries

Library Language Strengths Size
marked JS Fastest, most popular 40KB
markdown-it JS Rich plugins, extensible 60KB
remark JS AST ecosystem, MDX foundation 100KB+
CommonMark JS Strict spec compliance 50KB
pulldown-cmark Rust Extreme performance WASM 200KB

Basic Usage of marked

import { marked } from 'marked';

const html = marked.parse('# Hello **Markdown**');
// <h1>Hello <strong>Markdown</strong></h1>

markdown-it with Plugins

import MarkdownIt from 'markdown-it';
import mk from 'markdown-it-mark';
import footnote from 'markdown-it-footnote';
import tasklist from 'markdown-it-task-lists';

const md = new MarkdownIt({ html: true, linkify: true })
  .use(mk)
  .use(footnote)
  .use(tasklist);

const result = md.render('# Hello Markdown');

MDX: Markdown + JSX

MDX lets you use React components inside Markdown:

---
title: "My Article"
---

import { Chart } from './components/Chart';
import { Callout } from './components/Callout';

# Data Analysis Report

<Callout type="warning">
  The following data is based on Q1 2026 sampling.
</Callout>

## User Growth Trend

<Chart data={growthData} type="line" />

| Month  | Users  | Growth |
|--------|--------|--------|
| Jan    | 10,000 | -      |
| Feb    | 12,500 | 25%    |
| Mar    | 15,000 | 20%    |

Best Practices

1. File Organization

docs/
├── getting-started.md
├── configuration.md
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

2. Writing Conventions

  • One sentence per line: Git-diff friendly and easier to review
  • Don't skip heading levels: H1 → H2 → H3, never H1 → H3
  • Specify the language for code blocks: ````javascript` rather than `````
  • Use reference-style links: In long documents, [text][ref] is tidier than [text](url)
  • Add alt text to images: ![description](image) improves accessibility

3. Lint Tools

# Install markdownlint
npm install -g markdownlint-cli

# Check
markdownlint docs/**/*.md

# Auto-fix
markdownlint docs/**/*.md --fix

FAQ

Raw HTML Not Working in Markdown?

Some parsers disable raw HTML by default — you need to enable the html: true option.

Tables Don't Support Merged Cells?

Standard Markdown tables don't support cell merging. Use an HTML table when needed:

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td rowspan="2">Project A</td>
    <td>Sub-item 1</td>
  </tr>
  <tr>
    <td>Sub-item 2</td>
  </tr>
</table>

Markdown Syntax Inside Code Blocks Gets Parsed?

Use more backticks for nesting:

````markdown
```javascript
console.log('Not parsed by the outer block');
```


---

## Summary

Markdown is the best format for technical writing — concise, version-controllable, and backed by a rich ecosystem. Master the basic syntax plus GFM extensions, math formulas, and Mermaid diagrams, and you can produce professional-grade technical documentation. The toolbox's [Markdown Editor](/en/utils/markdown) offers live preview and export, so you can focus on content instead of formatting.
#Markdown#HTML转换#文档编写#排版#教程