Why Markdown Headings Aren't Converting to Word Styles on Mac

The Problem: When Markdown Headings Become Plain Text

You convert a markdown file to Word, open the document, and your headings look fine — they're bigger, bold, the right size. But when you try to generate a table of contents, nothing appears. When you use Word's Navigation Pane, it's empty. The headings aren't actually headings at all.

This is the most common markdown-to-Word conversion failure on Mac. The text looks like headings (larger font, bold weight), but Word doesn't recognize them as semantic heading elements. They're just formatted text.

What Proper Heading Conversion Should Look Like

When markdown headings convert correctly:

• Your # becomes Word's "Heading 1" style
• Your ## becomes Word's "Heading 2" style
• And so on through ###### (Heading 6)
• Word's Navigation Pane shows your document structure
• You can generate automatic tables of contents
• Screen readers can navigate your document properly

These aren't just visual styles — they're semantic markers that tell Word "this is a section heading" rather than "this is some bold text."

Signs Your Headings Aren't Converting Correctly

The most obvious symptoms:

• Empty Navigation Pane: Open Word's Navigation Pane (View → Sidebar → Document Map Pane). If it's blank or only shows a few headings, your styles didn't map correctly.
• Table of Contents failures: Insert → Table of Contents produces nothing, or only captures some headings.
• Inconsistent formatting: Headings that should be the same level look different.
• Manual style panel check: Click on a heading and open the Styles panel (⌘⌥⇧S). If it shows "Normal + Bold + 18pt" instead of "Heading 1", it's not a real heading.

Understanding How Markdown Headings Should Map to Word Styles

Markdown uses hash symbols (#) to denote heading levels. Word uses semantic styles called Heading 1, Heading 2, etc. Proper conversion requires mapping one to the other, not just applying visual formatting.

Markdown Heading Syntax Basics

Markdown supports two heading formats, but ATX-style (hash symbols) is the standard:

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

The critical syntax rules:

• One space required between the # and the heading text
• Hash symbols must be at the start of a line
• Blank line before and after (recommended for parser compatibility)

There's also Setext-style for H1 and H2 (underlines with = or -), but it's less common and some converters handle it inconsistently. Stick with ATX-style for reliable conversion.

Word's Built-in Heading Styles Explained

Word documents have a style system. Every paragraph has a style applied — "Normal" by default. Heading styles (Heading 1 through Heading 9) are special:

• They create document structure that Word understands semantically
• They're used to build tables of contents
• They enable document navigation features
• They cascade — modify Heading 1, and all H1s update

When you see "Normal + Bold + 18pt" in the Styles panel, that's not a heading style — it's the Normal paragraph style with manual formatting applied on top. That manual formatting won't work with Word's structural features.

The Semantic Structure Connection

Visual formatting is easy: make text bigger and bold. Semantic structure requires the converter to:

1. Parse the markdown and identify heading elements
2. Map each heading level to Word's corresponding style
3. Write the .docx XML with proper style references

Many quick converters skip step 2 and 3 — they just apply visual formatting. The result looks right on screen but fails when you try to use Word's structural features.

5 Common Reasons Your Headings Aren't Converting Properly

1. Syntax Errors That Break Heading Recognition

The most common mistake: no space after the hash symbols.

Wrong:

#Heading 1
##Heading 2

Correct:

# Heading 1
## Heading 2

Most markdown parsers require that space. Without it, they treat #Heading as literal text, not a heading marker.

Other syntax issues:

• Bold instead of headings: Using **Heading** creates bold text, not a heading
• Mixed formats: Combining Setext and ATX styles confuses some parsers
• Indentation: Leading spaces before # can break heading recognition
• Unicode hash symbols: Using similar-looking characters (＃) instead of ASCII #

2. Converter Configuration Problems

Not all conversion tools map headings to Word styles by default.

Pandoc (the most common command-line converter) requires specific flags to preserve heading styles. A basic command like this won't create proper styles:

pandoc input.md -o output.docx

You need to use a reference document that defines the heading styles, or configure Pandoc to use Word's default styles explicitly. Many users run Pandoc without understanding these options, getting visual-only output.

Online converters are worse — most use basic markdown-to-HTML-to-Word pipelines that apply formatting but ignore semantic structure. They're designed for speed, not accuracy.

3. Template and Style Conflicts

If you're using a custom Word template (reference.docx in Pandoc), style name mismatches can break heading conversion:

• Your template uses "Header 1" instead of "Heading 1"
• Heading styles have been deleted or renamed
• Custom styles conflict with Word's built-in heading hierarchy

Word is specific about style names. If your converter is trying to apply "Heading 1" but your template doesn't have a style with that exact name, Word falls back to Normal + formatting.

4. Character Encoding Issues

Less common but frustrating: encoding problems can corrupt heading markers during conversion.

If your markdown file is saved with the wrong encoding (not UTF-8), or if the converter assumes the wrong encoding, hash symbols might get mangled or interpreted as different characters. This is more common when:

• Converting files from Windows machines
• Dealing with legacy text editors
• Copy-pasting markdown between applications

Always save markdown files as UTF-8 without BOM (byte order mark).

How to Diagnose Your Heading Conversion Issue on Mac

Quick Diagnostic Checklist

Follow these steps in order:

1. Open your markdown file in a text editor (TextEdit, VS Code, BBEdit) and verify heading syntax — confirm space after #, no indentation before #
2. Create a minimal test file with just three headings and one paragraph under each — this isolates syntax vs converter issues
3. Convert the test file with the same tool/method you normally use
4. Open the Word document and check the Styles panel — click on each heading and press ⌘⌥⇧S to see what style is applied

If the test file works but your real file doesn't, the problem is in your markdown syntax. If the test file also fails, the problem is your conversion method.

Testing with a Sample Document

Save this as test.md:

# First Level Heading

This is a paragraph under H1.

## Second Level Heading

This is a paragraph under H2.

### Third Level Heading

This is a paragraph under H3.

Convert it to Word using your normal method. Open the result and:

1. Go to View → Sidebar → Document Map Pane (or Navigation Pane in newer Word versions)
2. You should see all three headings listed hierarchically
3. Click on "First Level Heading" in the document
4. Press ⌘⌥⇧S (or Format → Style)
5. The style should show "Heading 1", not "Normal + Bold + [size]"

If the Navigation Pane is empty, your converter isn't mapping styles correctly.

Checking Word Styles Panel

The Styles panel is your definitive test. On Mac Word (tested on Word for Mac 16.x):

1. Click on a heading in your document
2. Press ⌘⌥⇧S (or go to Format → Style)
3. Look at the style name in the panel that appears

What you want to see:

• "Heading 1" (or "Title" for your document title)
• "Heading 2"
• "Heading 3"
• And so on

What indicates failure:

• "Normal" with a + sign and additional formatting listed
• Custom style names that aren't part of Word's default set
• Multiple headings showing different styles when they should be the same level

The MarkDrop Solution: Reliable Heading Conversion on Mac

MarkDrop (mark-drop.app) handles markdown-to-Word conversion with proper heading style mapping. It's built specifically for Mac and designed to work without configuration.

Converting with Right-Click in Finder

The fastest workflow:

1. Locate your .md file in Finder
2. Right-click (or Control-click) the file
3. Select "Convert with MarkDrop" → "To Word Document"
4. MarkDrop creates a .docx file in the same directory with proper heading styles applied

MarkDrop maps # → Heading 1, ## → Heading 2, etc. automatically. No command-line flags, no reference templates, no configuration files.

Drag-and-Drop Conversion

Alternative method:

1. Open MarkDrop
2. Drag your .md file onto the MarkDrop window
3. Select output format (Word, PDF, or Rich Text)
4. Choose save location

Same result — headings map to proper Word styles, preserving document structure.

Limitation: MarkDrop is macOS-only. Free tier allows 5 conversions per month; Pro version ($9.99 one-time) is unlimited. If you're on Windows or Linux, you'll need Pandoc with proper configuration.

Verifying Your Heading Styles After Conversion

After converting with MarkDrop (or any tool), always verify:

1. Open the .docx file in Word
2. Open the Navigation Pane (View → Sidebar → Document Map Pane)
3. Confirm all headings appear in the pane with proper hierarchy
4. Click on a few headings and check the Styles panel (⌘⌥⇧S)
5. Try inserting a table of contents (Insert → Table of Contents) — it should populate correctly

Alternative Fixes: Other Tools and Methods

Pandoc Command-Line Solutions

Pandoc (pandoc.org) is the most powerful open-source markdown converter, but it requires specific flags for proper heading conversion.

Basic command that preserves heading styles:

pandoc input.md -o output.docx --standalone

The --standalone flag tells Pandoc to create a complete document with proper structure, not just convert content.

Using a custom reference document:

pandoc input.md -o output.docx --reference-doc=custom-template.docx

This uses your custom-template.docx file as a style template. To create one:

1. Convert any markdown file with Pandoc's default settings
2. Open the output in Word
3. Modify the Heading 1, Heading 2, etc. styles to match your preferences
4. Save as custom-template.docx
5. Use it as your --reference-doc for all future conversions

Tradeoffs: Pandoc is free and extremely flexible, but requires Homebrew installation (brew install pandoc), terminal comfort, and understanding of command-line flags. Not suitable for non-technical users or quick one-off conversions.

Creating Custom Reference Templates

If you're using Pandoc regularly, a well-configured reference document saves time.

Create your template:

1. Generate a basic Word file: pandoc --print-default-data-file reference.docx > reference.docx
2. Open reference.docx in Word
3. Modify styles: Format → Style → Modify → [select Heading 1, etc.]
4. Set fonts, sizes, spacing, colors for each heading level
5. Save the file
6. Place it in ~/.pandoc/ or reference it explicitly in your commands

Now all conversions use your custom styles automatically (if placed in ~/.pandoc/) or when you specify --reference-doc.

When Online Converters Fall Short

Online markdown-to-Word converters (Convertio, CloudConvert, Aspose, etc.) are convenient but unreliable for heading styles.

Problems with online converters:

• Files leave your machine — privacy/security concern for sensitive documents
• Most don't map semantic styles — they apply visual formatting only
• No configuration options — you get whatever their default pipeline produces
• File size limits — many cap free conversions at 1-2 MB
• Rate limiting — restricting daily conversions on free tiers

Use online converters only for:

• Non-sensitive documents
• Quick tests where you don't care about perfect structure
• Situations where you can't install local software

For reliable heading conversion, use Pandoc or MarkDrop instead.

Best Practices for Markdown Headings That Convert Cleanly

Syntax Best Practices

Write headings that any parser can handle:

• Always use ATX-style headings (# symbols), not Setext underlines
• Include one space between # and text: # Heading not #Heading
• Start headings at column 1 — no leading spaces or tabs
• Add blank lines before and after headings for maximum parser compatibility
• Use closing hashes optionally — # Heading # is valid but not required

Structural Best Practices

Maintain logical heading hierarchy:

• Start with H1 — your document should have exactly one # heading (the title)
• Don't skip levels — don't jump from H1 to H3 without an H2 in between
• Use H2 for main sections, H3 for subsections under those, H4 for sub-subsections
• Rarely go beyond H3 — if you're nesting deeper than three levels, your document structure may be too complex

This matters because:

• Screen readers rely on proper heading hierarchy
• Word's Navigation Pane displays hierarchy visually
• Some converters break if heading levels skip around illogically

Avoiding Common Pitfalls

Things that break heading conversion:

• Using bold as headings: **This looks like a heading** creates bold text, not a semantic heading
• Mixing heading formats: ATX-style for some headings, Setext underlines for others
• Special characters in headings: Emoji, unusual punctuation, or Unicode can confuse some converters (though most handle this correctly now)
• Inline code in headings: # Heading with `code` works in most parsers but can cause issues with less robust converters
• Trailing punctuation: Avoid # Heading: or # Heading. — keep heading text clean

Verifying and Fixing Headings in Your Word Document

If you've already converted a document and suspect heading style issues, here's how to verify and fix them on Mac.

Checking the Styles Panel

The Styles panel tells you exactly what style is applied to selected text.

1. Open your Word document
2. Click on a heading that should be Heading 1
3. Press ⌘⌥⇧S (Command-Option-Shift-S) to open the Styles panel
4. Look at the highlighted style name

If it says "Normal" or shows "Normal +" with additional formatting, your heading isn't using a proper heading style.

To see all instances of incorrect heading styles:

1. Open the Styles panel (⌘⌥⇧S)
2. Hover over "Normal" in the list
3. Click the dropdown arrow → Select All [number] Instance(s)
4. This highlights all text using the Normal style
5. Manually review the selections — any that should be headings need fixing

Using Navigation Pane for Verification

The Navigation Pane (called Document Map Pane in some Word versions) shows your document's heading structure.

To open it:

1. Go to View → Sidebar → Document Map Pane
2. Or View → Navigation Pane (depending on your Word version)

What you should see:

• All your headings listed hierarchically
• Proper indentation showing heading levels (H1 at the left, H2 indented under H1, etc.)
• Click on any heading in the pane to jump to that section in the document

If the pane is empty or missing headings, those headings don't have proper styles applied.

Manual Style Corrections

If headings didn't convert correctly, you can fix them manually:

1. Click on the text that should be a heading
2. Open the Styles panel (⌘⌥⇧S)
3. Click on the appropriate heading style (Heading 1, Heading 2, etc.)
4. The text now uses that heading style

For bulk corrections:

1. Use Find and Replace (⌘F) to search for text you know is a heading
2. When Word highlights it, apply the heading style
3. Click "Find Next" and repeat

Or use Word's style-based find and replace:

1. Edit → Find → Advanced Find and Replace
2. Click Format → Style → Normal (to find all text using Normal style)
3. In "Replace with", click Format → Style → Heading 1 (or whichever level)
4. Review each match before replacing to avoid applying heading styles to body paragraphs

Creating a table of contents to test:

1. Place cursor where you want the TOC (usually near the top of the document)
2. Go to Insert → Table of Contents → Automatic Table 1
3. Word generates a TOC based on all properly styled headings

If headings are missing from the TOC, they don't have heading styles applied correctly.