Why Write in Markdown
Markdown is a lightweight markup language that uses simple symbols to represent formatting. Writers don't need to touch the mouse—they focus on content while formatting is generated automatically.
Advantages:
- Plain text—openable in any editor
- Version-control friendly (Git can diff)
- Convertible to HTML, PDF, Word, and other formats
- Low learning curve—10 minutes to get started
Basic Syntax
Headings
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
Recommend using only one level-1 heading per article.
Paragraphs
Separate paragraphs with a blank line. Lines without a blank line between them belong to the same paragraph.
Emphasis
**bold**
*italic*
~~strikethrough~~
Lists
Unordered:
- Item
- Item
- Sub-item (indented)
Ordered:
1. First item
2. Second item
Links and Images
[link text](https://example.com)
Code
Inline: code
Code block:
```javascript
const x = 1;
### Blockquotes
Quoted content Second line
### Horizontal Rule
## Extended Syntax
### Tables
| Name | Age |
|---|---|
| Tom | 25 |
### Task Lists
- Completed
- Not completed
### Footnotes
Body text[^1]
[^1]: Footnote description
### Strikethrough
deleted
### Auto Links
URLs are automatically converted to links.
## Writing Tips
### Clear Heading Hierarchy
- Heading 1: Article title
- Heading 2: Major sections
- Heading 3: Subsections
- Don't skip levels (jumping from H1 directly to H3)
### Concise Paragraphs
- One idea per paragraph
- Keep paragraphs short (3-5 lines is ideal)
- Use lists instead of long paragraphs
### Use Lists Effectively
Use lists for parallel content—clearer than paragraphs:
- Ordered lists for steps
- Unordered lists for parallel items
- Tables for comparisons
### Label Code with Language
Label code blocks with a language to trigger syntax highlighting:
Add Image Descriptions
The description in  is important:
- Shows when the image fails to load
- Screen readers read it to visually impaired users
- Helps with SEO
Clear Links
- Link text should describe the target—don't use "click here"
- Use full URLs for external links
- Use relative paths for internal links
Document Organization
Add a Table of Contents at the Beginning
For long documents, add a table of contents at the beginning with links to each section. Makes navigation easier.
Separate Sections with Headings
Use headings to separate sections, not horizontal rules. Headings have hierarchy; horizontal rules don't.
Separate Code from Text
Leave blank lines before and after code blocks to separate them from body text. Makes reading clearer.
Place Images Appropriately
Place images right after the related text, not all at the end. Readers see the image in context when reading sequentially.
Editor Choices
VS Code
- Free and powerful
- Install Markdown plugins (e.g., Markdown All in One)
- Live preview
- Suitable for developers
Typora
- WYSIWYG
- No preview window—edit the rendered result directly
- Paid but affordable
- Suitable for focused writing
Obsidian
- Local knowledge base
- Bidirectional links
- Rich plugins
- Suitable for notes and knowledge management
Online Editors
- StackEdit: Online Markdown editor
- JianShu: Chinese writing platform
- Suitable for quick writing
Convert Markdown to HTML
After writing Markdown, convert it to HTML for web display. Use the Markdown to HTML tool for one-click conversion.
Common Mistakes
No Space After Heading
#Heading won't be recognized. Use # Heading (space after #).
Wrong List Indentation
Sub-lists must be indented 2 or 4 spaces (depending on the parser). Wrong indentation means sub-lists won't display.
Unclosed Code Block
Both opening and closing ``` are required. Missing the closing one turns everything after into a code block.
Special Characters Not Escaped
To display * # and similar symbols, escape them with a backslash: * displays *.
Table Syntax Errors
Tables need a header separator row (| --- |). Without it, the table won't be recognized.
Mismatched Link Brackets
[link](url missing the closing parenthesis—the link won't be recognized.
Best Practices
One Document, One Topic
One article covers one topic. Split multiple topics into multiple articles and link them together.
Write Content First, Format Later
Write plain text content first, then add Markdown markup. Avoid formatting while writing—it interrupts your flow.
Unified Style
Teams should standardize writing style:
- How many heading levels to use
- Use - or * for lists
- Code block language labels
- Maximum list nesting depth
Keep Source Files
Markdown is the source file; HTML/PDF are generated outputs. Keep the Markdown for easy editing and regenerate output formats each time.
Summary
The core of Markdown writing: clear heading hierarchy, concise paragraphs, effective use of lists, code labeled with language, and image descriptions. Choose a suitable editor, maintain a unified style, and keep source files. For display, use the DocsAll Markdown to HTML tool—runs in the browser.