Why Notion Markdown Import Loses Specific Heading Hierarchy Levels

When you import a Markdown file into Notion, you may notice that some heading levels do not appear as expected. For example, an H3 in your original file might become plain text or merge into a bullet list. This problem occurs because Notion maps Markdown headings to its own block types, and the mapping is not one-to-one for all six heading levels. This article explains exactly which heading levels are affected, why the loss happens, and how to preserve your document structure during import.

Why Notion Loses Heading Hierarchy During Markdown Import

Notion supports three heading block types: Heading 1, Heading 2, and Heading 3. When you import a Markdown file, Notion maps Markdown H1 to Notion Heading 1, H2 to Heading 2, and H3 to Heading 3. Markdown H4, H5, and H6 have no direct Notion equivalent. During import, Notion demotes H4 to Heading 3, H5 to Heading 3, and H6 to Heading 3. This flattening destroys the document hierarchy. If your original Markdown file uses H4 and H5 to denote sub-sections under an H3, every sub-section becomes another H3, making the outline useless.

Which Heading Levels Are Affected

The affected levels are H4 and H5. H1, H2, H3, and H6 are mapped correctly. H6 is mapped to Notion Heading 3, but because H6 is the deepest level, the loss of hierarchy is less noticeable. H4 and H5 are the levels most commonly used in technical documentation and structured writing, so their loss is the most disruptive.

What Happens to the Demoted Headings

When Notion demotes H4 and H5 to H3, the visual styling changes. The font size and weight become identical to the nearest H3 above them. All sub-sections under a single H3 parent appear as sibling H3 blocks instead of nested children. This breaks outline views and table-of-contents navigation in Notion. The document loses its structural meaning.

Steps to Preserve Heading Hierarchy During Markdown Import

The only reliable way to preserve H4 and H5 hierarchy is to modify your Markdown file before import or after import in Notion. Below are three methods. Method 1 is the most efficient for large documents.

Method 1: Convert H4 and H5 to H3 and H6 Before Import

1. Open the Markdown file in a text editor
   Use Notepad, Visual Studio Code, or any plain-text editor that supports find-and-replace. Do not use a rich text editor like Word.
2. Replace H4 headings with H3 headings
   Search for the pattern #### and replace it with ### . This converts every H4 to an H3. The hierarchy will be flattened, but the text will remain as a heading block.
3. Replace H5 headings with H6 headings
   Search for ##### and replace it with ###### . Notion maps H6 to Heading 3, but the demotion from H5 to H6 preserves one level of depth compared to demoting H5 directly to H3.
4. Save the file and import into Notion
   Use the Import feature in Notion: File menu > Import > Markdown & CSV. Select the modified file. All headings now appear as Notion Heading 3 blocks. You can then manually adjust the heading level using the block type menu.

Method 2: Use Toggle Blocks as Heading Surrogates

1. Import the original Markdown file
   Import the file without any modification. Accept that H4 and H5 will become H3 blocks.
2. Convert demoted H3 blocks to toggle blocks
   Select a block that was originally H4 or H5. Open the block type menu by clicking the six-dot handle on the left. Choose Turn into > Toggle. The heading text becomes a toggle header. You can nest content under it.
3. Apply a custom color or style to the toggle
   Select the toggle block, open the color menu, and choose a color like Gray or Blue. This visually distinguishes toggle headings from actual H3 headings. The outline view still shows only H1, H2, and H3, but the toggle provides a visible hierarchy on the page.

Method 3: Use a Third-Party Markdown Converter

1. Open the Markdown file in Pandoc
   Pandoc is a command-line document converter. Install Pandoc from pandoc.org. Open a terminal or command prompt.
2. Run the conversion command
   Type pandoc input.md -f markdown -t markdown --wrap=none -o output.md. This re-writes the Markdown file without changing heading levels. Then manually edit H4 and H5 as described in Method 1.
3. Import the cleaned file into Notion
   Use the standard Notion import process. The file now contains only H1, H2, H3, and H6 headings, which Notion maps correctly.

Common Issues After Markdown Import in Notion

Demoted Headings Appear as Plain Text Instead of Heading Blocks

If the Markdown file uses a non-standard heading syntax (for example, ## Heading 2 with a space before the hash), Notion may treat the line as plain text. Ensure your Markdown file uses the standard syntax: exactly one hash for H1, two for H2, and so on, with a single space after the hashes. Remove any leading spaces.

Table of Contents Does Not Show All Headings

Notion’s table of contents block displays only H1, H2, and H3 blocks. Demoted H4 and H5 blocks that became H3 will appear, but their original parent-child relationship is lost. Use the toggle block workaround (Method 2) to restore visual hierarchy, even though the TOC will not reflect it.

Headings Inside Code Blocks Are Not Imported

Markdown headings inside fenced code blocks (triple backticks) are treated as code, not headings. Notion imports them as code blocks. If you need those headings to appear as actual headings, extract them from the code block before import.

Notion Heading Block Support vs Markdown Heading Levels

Item	Markdown	Notion
Heading 1	# Text	Heading 1 block
Heading 2	## Text	Heading 2 block
Heading 3	### Text	Heading 3 block
Heading 4	#### Text	Demoted to Heading 3
Heading 5	##### Text	Demoted to Heading 3
Heading 6	###### Text	Heading 3 block

Notion does not support Heading 4 or Heading 5 blocks. The table shows the exact mapping during import. To maintain a four-level hierarchy, you must use the toggle block workaround or manually adjust after import.