Common DOCX → Markdown Formatting Issues (and How to Fix Them)

DOCX → Markdown conversion should be quick. But Word documents often contain “visual formatting” (bold, spacing, font sizes) instead of semantic structure (real headings, real lists). That’s why converted Markdown can look broken even when the original DOCX looks perfect.

Below are the most common formatting issues you’ll see after converting a Word file—and exactly how to fix each one. If you’re using Lexon, you can do most of this cleanup in a few minutes and keep your file clean for export.

1) Headings that convert as plain bold text

If your Heading 1 / Heading 2 in Word becomes just bold text in Markdown, it usually means the DOCX used manual styling instead of Word’s heading styles.

  • Fix before converting: In Word, apply built-in styles (Heading 1, Heading 2, Heading 3). Don’t fake headings with larger font size + bold.
  • Fix after converting: Replace “title-like” bold lines with Markdown headings (#, ##, ###).

2) Nested lists become flat (sub-bullets disappear)

Word lists can be deeply formatted. Markdown lists are indentation-based, so converters sometimes lose nesting.

What you want:

- Item one
  - Sub-item
- Item two
  • Use consistent indentation for sub-items (two spaces is a safe default).
  • Avoid mixing bullets and numbers across the same nesting level unless it’s intentional.

3) Weird line breaks and spacing

A common symptom: sentences split across multiple lines, or extra blank lines everywhere. Word’s “soft breaks” and paragraph spacing don’t map cleanly to Markdown paragraphs.

  • Merge broken lines into a single paragraph when they’re meant to flow.
  • Keep one empty line between paragraphs.
  • If your converter hard-wrapped text at 80 columns, consider reflowing paragraphs (most editors can do this).

4) Tables convert to plain text (or break alignment)

Some converters output tables as space-separated text instead of Markdown tables. For simple tables, rewrite them using pipes:

| Name | Price |
|------|-------|
| A    | 10    |

If your table is complex (merged cells, multi-line cells), you’ll get better results by simplifying it in Word first or converting it into multiple smaller tables or lists.

5) Images missing, not exported, or broken paths

DOCX stores images internally. During conversion, images may export into a separate folder—or not export at all—leaving Markdown references that don’t load.

  • Ensure your conversion process exports images to a folder (e.g. ./images).
  • Update paths to be relative and consistent, e.g. ![Alt text](./images/figure-1.png).
  • Add descriptive alt text (better accessibility + SEO, and clearer diffs in Git).

6) Links and inline formatting glitches

You might see doubled emphasis markers (like ****bold****) or links that lose their URL. This typically happens when Word has overlapping styles (bold + underline + hyperlink + character styles).

  • Normalize emphasis to clean Markdown: **bold**, *italic*.
  • Rebuild broken links as [text](https://example.com).
  • In Word, avoid stacking multiple character-level styles on the same phrase.

7) Smart quotes, em dashes, and invisible characters

Word auto-replaces characters with typographic variants like curly quotes (“ ”), em dashes (—), and non-breaking spaces. These can cause odd rendering, search issues, or lint failures.

  • Replace curly quotes with straight quotes (") if your pipeline prefers ASCII.
  • Replace em dashes with -- (or a normal hyphen) depending on your style guide.
  • Watch out for non-breaking spaces when copy/pasting from Word.

8) DOCX layout features Markdown can’t represent

Columns, text boxes, floating shapes, and “designed layouts” won’t convert cleanly because Markdown is structure-first, not layout-first.

  • Remove text boxes and floating objects before converting.
  • Turn layout sections into real structure: headings, paragraphs, lists, and simple tables.
  • If you must keep layout, consider exporting HTML instead and using Markdown only for the body content.

A quick cleanup workflow (5 minutes)

  1. Scan headings: confirm the hierarchy reads correctly from H1 → H2 → H3.
  2. Fix lists: ensure nesting is indented correctly and numbering makes sense.
  3. Check spacing: merge broken lines and remove extra blank lines.
  4. Verify tables: rewrite simple ones; simplify complex ones.
  5. Confirm images + links: fix relative paths and rebuild broken URLs.

Where Lexon helps

If you’re doing DOCX → Markdown regularly, the goal is repeatable structure. Lexon fits best when you want quick, local-first conversion and editing:

FAQ

Why does my DOCX convert poorly even though it looks fine in Word?
Because Word can look structured while actually being visually formatted. Converters rely on semantic structure (real heading styles, real lists).
What’s the #1 thing I should fix before converting?
Headings. Apply Heading 1/2/3 properly in Word—everything else becomes easier.
Do I need to clean everything manually?
Usually not. Most documents only need a quick pass: headings, list indentation, and spacing. Tables and complex layouts are the most time-consuming.

Final thoughts

Word is visual-first. Markdown is structure-first. Once you treat headings and lists as structure (not styling), DOCX → Markdown conversion becomes predictable—and cleanup becomes a fast, repeatable step.

← Back to Blog