Markdown Heading Syntax

Headings are an important part of Markdown document structure, used to create hierarchical organization. Markdown supports two ways to create headings.

1. Heading Syntax

Method 1: Using Hash Symbols (#)

Add one or more hash symbols (#) before text to create headings. The number of hash symbols indicates the heading level.

Method 2: Using Underlines (H1 and H2 only)

Add equals signs (=) or hyphens (-) below text to create headings. Less commonly used.

2. Syntax Rules

Basic Rules

1. Space required between hash and text

   • ✅ Correct: # Heading
   • ❌ Wrong: #Heading

2. Number of hashes determines heading level

   • Supports up to 6 heading levels
   • More than 6 hashes will be treated as regular text

3. Headings can contain inline formatting

   • Bold: ## This is **bold** heading
   • Italic: ### This is *italic* heading
   • Inline code: #### This is \code` heading`

3. Best Practices

Document Structure Recommendations

1. Use clear hierarchical structure

   • Start with H1
   • Don't skip heading levels
   • Maintain logical hierarchy

2. Heading naming conventions

   • Use concise and clear headings
   • Avoid overly long headings
   • Maintain consistency in headings

3. Appropriate use of heading levels

   • H1: Document main title
   • H2: Major sections
   • H3: Subsections
   • H4 and below: Detailed content grouping

Important Notes

1. Avoid excessive nesting

   • Don't use too many heading levels
   • Recommend maximum 4-5 heading levels

2. Maintain consistency

   • Use the same heading style throughout the document
   • Recommend using hash symbol method consistently

3. Match headings with content

   • Ensure headings accurately describe the content below
   • Avoid mismatched headings and content

4. SEO friendly

   • Use descriptive headings
   • Include keywords but avoid keyword stuffing

4. Common Questions

Q: Why isn't my heading rendering correctly?

A: Check the following:

• Is there a space between the hash and text?
• Are you using correct Markdown syntax?
• Does your editor support Markdown rendering?

Q: Can I use multiple headings on one line?

A: Not recommended. Each heading should be on its own line for better readability.

Q: Can headings contain special characters?

A: Yes, but avoid special characters that might affect rendering, such as HTML tags.

Q: How do I create headings without numbers?

A: Simply use the heading syntax directly. Markdown headings don't have numbers by default. Add numbers manually if needed.

---

Tip: Headings are the foundation of document structure. Proper use of headings makes documents clearer and more readable, and helps generate table of contents and navigation.