Headers in Markdown
Learn how to create headings and structure your Markdown documents
What are Markdown Headers?
Headers (or headings) in Markdown are used to create titles and subtitles in your document. They help organize your content and create a hierarchical structure, similar to HTML heading tags (h1, h2, h3, etc.). Headers are often used with other elements like paragraphs, lists, and tables to structure your document. For more complex document structure, you might also want to explore advanced Markdown features like HTML in Markdown.
Markdown supports six levels of headers, from level 1 (the largest) to level 6 (the smallest), allowing you to create a well-structured document with clear sections and subsections. You can try creating headers in our Markdown Editor to see how they appear in the preview.
Header Syntax
There are two ways to create headers in Markdown:
1. ATX Style (Hash Syntax)
The most common way to create headers is by using hash (#) symbols at the beginning of a line. The number of hash symbols indicates the heading level:
# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6It's recommended to include a space between the hash symbols and the heading text for better compatibility across different Markdown processors.
2. Setext Style (Underline Syntax)
For heading levels 1 and 2 only, you can also use an alternative "e;underline"e; style:
Heading Level 1
=============
Heading Level 2
-------------In this style, you use equal signs (=) for level 1 headings and hyphens (-) for level 2 headings. The number of characters doesn't matter as long as there are at least one, but it's common to use multiple characters for better readability.
Note: The ATX style (hash syntax) is more commonly used and supports all six heading levels, while the Setext style only supports two levels.
Header Examples
Document Structure
Headers are essential for organizing your document into a logical structure. Here's an example of how you might structure a document about climate change:
# Climate Change: A Global Challenge
## Introduction
Climate change refers to long-term shifts in temperatures and weather patterns...
## Causes of Climate Change
### Human Activities
Human activities have been the main driver of climate change...
### Natural Factors
Some natural factors also contribute to climate change...
## Effects of Climate Change
### Environmental Impact
Climate change affects various ecosystems...
### Social and Economic Impact
Beyond environmental effects, climate change also impacts societies...
## Solutions
### Policy Measures
Governments around the world are implementing policies...
### Individual Actions
Individuals can also contribute to fighting climate change...This structure uses three levels of headers to organize content in a hierarchical manner, making it easy for readers to navigate and understand the document.
Headers with IDs
Some Markdown processors (like GitHub) allow you to add custom IDs to your headers, which can be used for linking to specific sections:
## Project Overview [#overview]
This section provides a brief overview of the project.
## Installation [#installation]
Follow these steps to install the software.
[Go to Installation](#installation)The {#id} syntax adds a custom ID to the header, which can then be used as an anchor link target. This is particularly useful for creating table of contents or internal document navigation.
Note: Custom header IDs are not part of standard Markdown but are supported by many extended Markdown flavors like GitHub Flavored Markdown.
Best Practices for Headers
1. Start with H1
Begin your document with a single level 1 header (# or ===== underline) that describes the overall topic. This acts as the main title of your document and helps establish the document's primary subject.
2. Maintain Hierarchy
Follow a logical hierarchy and don't skip levels. For example, an H3 should be used as a subsection of an H2, not directly under an H1. This maintains a clear document structure that's easier to follow and navigate.
3. Be Concise
Keep headers short and descriptive. They should clearly indicate the content of the section but don't need to be complete sentences. Think of them as signposts that guide the reader through your document.
4. Add Spacing
Include blank lines before and after headers for better readability in the raw Markdown. This also helps ensure that the headers are correctly parsed by Markdown processors.
5. Be Consistent
Choose one style of headers (either ATX or Setext) and stick with it throughout your document. Mixing styles can make your document look inconsistent and unprofessional.
6. Consider Accessibility
Headers are important for accessibility as they provide structure for screen readers. Using headers properly helps users with disabilities navigate your document more effectively.
7. Use for Structure, Not Styling
Headers should be used to indicate the structure of your content, not for styling text. Don't use headers just to make text bigger or bolder—use appropriate styling elements instead.
Interactive Header Generator
Markdown
## Your Header TextPreview
Your Header Text
Adjust the slider to change the header level, and edit the text to see how different headers appear in Markdown. The preview will update automatically to show how your header will appear when rendered.
Additional Resources
Related Markdown Elements
Explore other Markdown elements that work well with headers:
- Paragraphs in Markdown(for content under headers)
- Lists in Markdown(for organizing content in sections)
- Emphasis in Markdown(for styling text in headers)
- Links in Markdown(for creating anchor links to headers)
- Advanced Markdown Features(for HTML and complex document structure)
- Markdown Editor(practice creating headers)
External Resources
Learn more about headers from these resources: