Notion Markdown Import: Header Levels Mapping

When you import a Markdown file into Notion, the heading levels from your original document do not always map directly to Notion’s heading styles. You may find that an H1 in Markdown becomes a page title, while H2 and H3 turn into toggle headings or plain text. This mismatch can break the structure of your notes, especially if you rely on a consistent outline. Notion uses its own block-based heading system with three levels: Heading 1, Heading 2, and Heading 3. This article explains exactly how each Markdown heading level maps to Notion headings and how to control the result during import.

How Notion Interprets Markdown Heading Levels

Notion’s import engine reads Markdown files line by line. It detects headings by the hash (#) character at the start of a line. The number of hashes determines the heading level in the original Markdown spec. However, Notion does not preserve the exact level. Instead, it applies a shifting rule to fit its own three-level heading system.

The root cause of confusion is that Notion treats the first H1 as the page title. This is because Notion pages have a single title at the top, not a heading inside the content. After that, every heading level shifts down by one. H2 becomes the highest block heading (Heading 1), H3 becomes Heading 2, and H4 through H6 all collapse into Heading 3. This mapping is not configurable in the standard import dialog. You cannot choose to keep H1 as a Heading 1 block or map H4 to a separate style.

Notion also ignores any indentation or nesting implied by heading levels. A Markdown document with H2 followed by H3 and H4 does not create a collapsible outline. Each heading block sits at the same hierarchical level in the page. To create nested structures, you must use toggle blocks or subpages manually after import.

Steps to Import a Markdown File and Verify Heading Mapping

1. Prepare your Markdown file
   Ensure your file uses standard Markdown heading syntax. Use a single H1 at the top for the page title. Use H2 for major sections, H3 for subsections, and H4–H6 for deeper levels. Save the file with a .md extension.
2. Open Notion and create a new page
   Click the + New Page button in the left sidebar. Name the page anything. You will replace this name during import.
3. Start the import process
   Click the three-dot menu in the top-right corner of the new page. Select Import from the dropdown. Choose Markdown & CSV from the file type list.
4. Select your Markdown file
   Click Choose File and navigate to your .md file. Notion supports files up to 5 MB in size. If your file is larger, split it into multiple files.
5. Review the imported headings
   After import, scroll through the page. The first H1 from your file appears as the page title. Check each heading block in the body. H2 lines should be Heading 1 blocks (large, bold text). H3 lines should be Heading 2 blocks (medium, bold text). H4–H6 lines should be Heading 3 blocks (smaller, bold text).
6. Manually adjust any misaligned headings
   If a heading appears at the wrong level, click on the six-dot icon to the left of the block. Select Turn into and choose the correct heading level. For example, if an H2 became Heading 1 but you want it as Heading 2, use this menu to change it.

Common Import Problems and How to Fix Them

First H1 appears as a Heading 1 block instead of the page title

This happens when the Markdown file has text or blank lines before the first H1. Notion reads the first block-level element as the page title. If the file starts with a paragraph, that paragraph becomes the title. To fix this, edit the Markdown file so the very first line is the H1 heading. Remove any blank lines or text above it.

Multiple H1 headings in the same file

Notion only uses the first H1 as the page title. All subsequent H1 lines become Heading 1 blocks in the body. This can break the intended hierarchy. To avoid this, use only one H1 per file. Convert additional H1 lines to H2 before importing.

Headings lose formatting like bold or italic

Notion does not support inline formatting within heading blocks during import. If your Markdown heading contains bold or italic text, the formatting is lost. After import, manually reapply formatting to the heading text.

Heading levels are shifted incorrectly

If you expected H1 to become Heading 1 and H2 to become Heading 2, the import will seem wrong. This is not a bug. Notion’s mapping is fixed. To achieve the original hierarchy, edit the Markdown file before import. Demote all headings by one level. For example, change H1 to H2, H2 to H3, and H3 to H4. Then after import, promote the page title manually.

Notion Heading Levels vs Markdown Heading Levels

Item	Markdown Syntax	Notion Import Result
Page title	First H1 (# Title)	Page name in the header area
Highest block heading	H2 (## Section)	Heading 1 block (large, bold)
Second block heading	H3 (### Subsection)	Heading 2 block (medium, bold)
Lowest block heading	H4–H6 (#### to ######)	Heading 3 block (small, bold)
Inline formatting in heading	bold or italic	Plain text (formatting lost)

This table shows the exact mapping you can expect. Use it to plan your Markdown file structure before importing into Notion.

You now know how Notion maps Markdown heading levels to its own block headings. The key rule is that H1 becomes the page title, H2 becomes Heading 1, H3 becomes Heading 2, and H4 through H6 become Heading 3. To get the structure you want, edit your Markdown file before import by shifting all headings down one level. If you need deeper nesting, use toggle blocks or subpages after the import. A practical next step is to test this mapping with a small Markdown file containing two H2 headings and three H3 subheadings to see the result firsthand.