Practical guide
Common Markdown conversion issues and how to fix them
Most conversion problems fall into a few categories: the source lacks semantic structure, visual reading order differs from stored text order, tables are irregular, text encoding is unreliable, or links and media depend on the original application. Diagnose the source format first, preserve the original file, and fix the Markdown with a repeatable checklist rather than trusting a visually plausible draft.
Last reviewed July 17, 2026 · Release 2026-07-17-adsense-r9
Who this guide is for
- • People reviewing failed conversions
- • Documentation and migration teams
- • Developers testing format support
- • Editors cleaning generated Markdown
Why are headings missing or overused?
Word files may use bold text instead of heading styles, PDFs may expose only font fragments, and plain text has no semantic heading metadata. Rebuild a logical H1/H2/H3 outline.
Why is reading order wrong?
Columns, text boxes, slide coordinates, sidebars, captions, and page furniture can be emitted before or after the intended paragraph. Compare section order with the source.
Why are bullets empty or numbering merged?
PDF glyph bullets may be detached from their text, custom numbering may flatten, and hard line breaks can create empty items. Join the item text and normalize one list style.
Why are tables broken or too wide?
Merged cells, multi-row headers, PDF-drawn grids, spreadsheet formulas, and dozens of columns do not map cleanly. Rebuild a regular grid, split by topic, or use record lists.
Why are characters, links, or images wrong?
Custom fonts, legacy encodings, relative URLs, lazy-loaded assets, and application-specific references can fail. Verify Unicode text and resolve every destination.
Why does a large or unusual file fail?
The public service has a 50 MB limit, a 60-second conversion timeout, concurrency limits, and archive safety checks. Simplify, split, export to a cleaner source, or use a controlled batch workflow.
Before and after example
Before
### 1. 2. • • Total 1,24O ../../image.png Page 3 Confidential
After Markdown
## Section 1 - First item - Second item **Verified total:** 1,240 
Review checklist
- • Identify whether the problem comes from source structure, layout, encoding, or destination paths.
- • Compare the draft with the original before editing away evidence.
- • Normalize headings, paragraphs, lists, and code fences.
- • Rebuild irregular or wide tables.
- • Verify Unicode characters, links, image paths, names, dates, and totals.
- • Split large files or use the original editable format when possible.
Risk boundary
Converted Markdown remains a draft. Use an approved private workflow for confidential, regulated, customer, financial, medical, legal, credential-containing, or private source material. Keep the original source available until all material details are verified.
Frequently asked questions
Why does a PDF show readable text but extract gibberish?
Embedded fonts can map visible glyphs to unusual character codes. Test copy and paste before conversion.
Why did my Word headings disappear?
They may have been visually styled instead of using Word heading styles.
Why are list numbers combined?
Positioned numbers and text can be extracted separately. Reconstruct the intended sequence during cleanup.
How do I fix a very wide table?
Keep essential columns, split by topic, or convert each record into a section or list.
Why are image links broken?
Relative paths and temporary asset URLs do not automatically match the publishing destination.
What should I send in a bug report?
Include the URL, format, size, browser, expected structure, actual structure, warnings, and a sanitized sample.
Related workflows
These links provide the next format, privacy, or review step for this specific guide.