The Markdown you get back, and how to clean it up

What the output actually is

The converter emits GitHub Flavored Markdown, the dialect used by GitHub, GitLab, Obsidian, Notion imports and most static site generators. It is CommonMark plus a few additions, of which the one that matters here is pipe tables.

That choice is deliberate. Plain CommonMark has no table syntax at all, so a converter targeting it either drops tables or emits raw HTML. GFM tables are readable as text and understood nearly everywhere Markdown is.

What survives the trip

The five edits worth making every time

Most converted files need the same small set of passes. They take a couple of minutes and they are the difference between a file you can search and one you can read.

• Fix the heading ladder. Font-size thresholds produce levels that are locally right and globally uneven — a document can end up with three H1s and no H2s. Skim the headings alone and renumber so the nesting matches the document's real outline.
• Rejoin split paragraphs. A generously spaced document breaks paragraphs at soft line ends. These read as a stack of short lines; join them and delete the stray blank lines.
• Repair hyphenation. Text justified with hyphenation at the right margin leaves words split across lines: "conver-" then "sion". Search the file for a hyphen followed by a line break.
• Check every table. Count the columns in the Markdown against the original, and check the last row — a trailing row is the most common casualty. A table that lost its shape is usually faster to retype than to repair.
• Delete the page furniture. Running headers and footers are detected and removed, but a document that varies them — a different chapter title on each page — can leave fragments behind.

A note on tables

A GFM pipe table needs the same number of cells in every row, and the header separator row decides the column count for the whole table. If the converter miscounts one row, the table is invalid and renders as literal text with pipes in it.

That is a visible failure, which is a mercy — you will see it immediately rather than discovering it later. A table like this is broken:

| Region | Q1 | Q2 |
| --- | --- | --- |
| North | 120 | 140 |
| South | 95 |
| East | 88 | 102 |

Fixing it

Add the missing cell, empty if the source cell was empty. Every row must have the same number of pipes as the separator row.

| Region | Q1 | Q2 |
| --- | --- | --- |
| North | 120 | 140 |
| South | 95 |  |
| East | 88 | 102 |

Escaping, and why the output sometimes has backslashes

Markdown gives meaning to characters that appear in ordinary prose. An asterisk means emphasis, an underscore means emphasis, a hash at the start of a line means a heading, a leading number and full stop mean a list item.

When those characters appear in your document as themselves — a footnote marker, a variable name with underscores, a line that genuinely begins with "1985." — they have to be escaped with a backslash or they will silently change how the document renders. A backslash in the output is usually the converter being careful, not a mistake.

If a backslash is in the way, deleting it is safe as long as you check how the line renders afterwards.

Where the file goes next

Markdown is plain text, which is the reason to convert in the first place: it is greppable, diffable, and readable in fifty years by anything that can open a text file.

For a repository, put it in the tree and let code review handle it. For a note vault, check the heading ladder first, since most vaults build their outline from it. For a static site, add the front matter your generator needs — no converter can invent it, because it is not in the PDF. For feeding a language model, see the guide on preparing PDFs for retrieval, which is a different job with different priorities.