Markdown Title, Heading & Syntax Reference

Headings

Use # symbols to create headings. One # for the largest heading, up to six for the smallest.

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

Markdown document titles and headings

Quick answers for Markdown titles, headings, and headers

Markdown does not define one universal document-title field. In a plain .md file or a GitHub README, start the visible document with one clear H1 heading. The H1 is the title readers see in the rendered document.

# Project name

Some publishing tools also read a title value in YAML front matter. That metadata can set a browser-tab title or generated page title, but it is tool-specific. It does not replace a visible H1 in every Markdown renderer.

---
title: Project name
---

# Project name

Use the H1 to name the document readers see, then use H2 and H3 headings to organize the sections that follow. Choose heading levels for their place in the outline, not only for visual size.

README example: fix the heading structure

This README has a missing space after the H1 marker and skips from the title directly to an H3 section:

#Project name

### Install
npm install example-package

Use a space after the # marker and continue with the next level in the document outline:

# Project name

## Install
npm install example-package

Before publishing, use the Markdown Formatter & Linter to review heading spacing and possible skipped heading levels. It can apply deterministic spacing fixes after you review the diff; choices about a document's structure remain yours.

Want to try the syntax? Open the editor and change the included heading examples to see the rendered outline update locally.

Text Formatting

Lists

Unordered lists use -, *, or +.

- Item 1
- Item 2
  - Nested item

Ordered lists use numbers:

1. First
2. Second
3. Third

Code Blocks

Wrap code in triple backticks with an optional language identifier for syntax highlighting:

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

Links & Images

[Link text](https://example.com)
![Alt text](image-url.jpg)

Blockquotes

> This is a blockquote
> Multiple lines

Tables

Use pipes to separate cells and hyphens to separate the header from the body. Need more rows or alignment controls? Create a table with the generator.

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |

Task Lists

- [x] Completed task
- [ ] Uncompleted task