Migrating Documents to Markdown: A Workflow for Word, PDF and HTML Sources

• ▸Word documents (.docx): best results, because the file contains structure. Heading styles, lists, tables, links, bold and italic all map to Markdown. Quality depends on whether the author used real styles or only changed font sizes.
• ▸HTML and web pages: also good. Headings, lists, links, code blocks and tables convert well. Remove navigation, scripts and ads first, or copy only the article container.
• ▸PDF files with text: workable but lossy. The file stores positions, not structure, so the converter must infer headings from font size and paragraphs from spacing. Expect to repair lists, tables and multi column pages.
• ▸Scanned PDFs and images: need text recognition first, and then everything a PDF needs, so budget for manual work.

A few minutes of preparation improve results more than any amount of post-processing.

• ▸In Word: apply Heading 1, 2 and 3 styles instead of manual formatting, use real list formatting instead of typed hyphens and numbers, and accept or reject all tracked changes.
• ▸Remove headers, footers and page numbers that would repeat in the text.
• ▸Convert old .doc files to .docx before converting.
• ▸For web pages, save only the main content and remove cookie banners and menus.
• ▸Decide whether images will be kept. The Word converter on this site replaces embedded pictures with a marker, since inline Base64 images make a Markdown file unreadable. Export images separately and link them.

Use the matching tool: the Word to Markdown Converter for .docx files, the HTML to Markdown Converter for markup and the PDF to Markdown Converter for PDFs with a text layer. Each runs in your browser, so the documents are not uploaded. For HTML choose a heading style, ATX with hash marks is the most common in repositories, and a bullet marker, and turn on table and strikethrough support if your Markdown flavor has them.

• ▸Headings: exactly one top level heading per file, and no skipped levels.
• ▸Lists: check nested lists and numbered lists that restarted or merged.
• ▸Tables: confirm the header row and the column count. Markdown tables cannot have merged cells or multiple paragraphs, so complex ones may need a different treatment such as an image or an HTML table.
• ▸Links: fix relative links, anchors that pointed inside the original document and links that point to the old location.
• ▸Quotes and dashes: Word's curly quotes are valid in Markdown, but you may want straight quotes for consistency. The Plain Text Converter normalizes them.
• ▸Line breaks: single line breaks inside a paragraph render as a space in most flavors. Check that nothing relied on a hard break.
• ▸Footnotes: convert to the footnote syntax your renderer supports, or to numbered notes at the end.
• ▸Code: wrap code in fenced blocks and add a language name for syntax highlighting.

Static site generators expect a block of metadata at the top of each file, with a title, a date and sometimes a description or tags. Add it consistently, preferably with a script for large sets. Use lowercase file names with hyphens, matching your URL scheme, and keep the folder structure parallel to the navigation you want readers to see.

• ▸Render the Markdown with the same engine your site will use. Different renderers disagree about tables, nested lists and line breaks.
• ▸Run the Markdown Formatter for consistent list markers, spacing and table alignment, so later edits produce clean diffs.
• ▸Compare a sample of converted pages with the originals side by side, and look at headings, lists, tables and links first.
• ▸For a large migration, convert a pilot batch of ten files, record the recurring problems and fix them in the source or with scripted replacements before processing the rest.