Headings and paragraphs in Markdown

Headings

Headings are used for organizing your document and creating a clear hierarchy of information. Markdown offers two syntax styles for creating headings: ATX-style and Setext-style.

ATX-style headings (recommended)

ATX-style headings use hash symbols (#) at the beginning of the line. The number of hash symbols corresponds to the heading level:

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

These are similar to the heading levels used in HTML (<h1> - <h6>).

Best Practices for ATX Headings:

• Always include a space after the hash symbols.
• Use proper hierarchy, in the correct order. E.g. dont only use level 1 and 3 in a document, skipping level 2.
• Most Markdown processors will only render up to six heading levels.

Setext-style headings (alternative)

Setext-style headings use underlines created with any number of equal signs (=) for level 1 headings, or hyphens (-) for level 2 headings:

Heading Level 1
===============

Heading Level 2
---------------

Limitations of Setext Headings:

• Only supports level 1 and 2 headings.
• Less commonly used.
• Requires extra lines.

Working with paragraphs

Paragraphs of text are simply created by writing text without any formatting. Paragraphs are separated by one or more blank lines:

This is the first paragraph, it can contain multiple sentences.

This is the second paragraph, using a blank line separating it from the first paragraph.

Line breaks

To create a new line (line break) without starting a new paragraph, you have various options:

• Use a backslash (\) at the end of a line:

  This is the first line.\
  This is the second line.
  

• End a line with two or more spaces and then return:

  This is the first line.
  This is the second line.
  

• Use the HTML <br> tag:

  This is the first line.<br>
  This is the second line.
  

The two spaces method is in the original Markdown specification but can be invisible and easy to miss. The backslash method is supported in many flavors of Markdown and is more visible when reading the document. The HTML tag does work universally but mixes Markdown with HTML.

Paragraph formatting

Some important notes about paragraph formatting:

• Consecutive Blank Lines: Typically, using multiple blank lines will be rendered as a single blank line.
• Indentation: Don't use tabs or spaces to indent paragraphs.
• Line Length: There's no need to worry about line length in your source text, Markdown will wrap the text appropriately when rendered.

Combining headings and paragraphs

Headings and paragraphs can be combined to create well-structured documents. Here is an example:

# Project overview

This project aims to create a comprehensive documentation system using Markdown, making
information easy to find and understand.

## Objectives

The primary objectives of this project include:

## Improving readability

By using proper heading hierarchy and paragraph structure, we ensure that documents
are easy to read and understand.

## Better document maintenance

Markdown's simple syntax makes it easy to update and maintain
documentation with minimal training or experience.