How to Prepare a Markdown Document Before Converting It

By M. Hassan Ali Published January 29, 2025 2 min read

A minute spent checking these five things before converting saves a repeat trip back through the tool after spotting a problem in the output.

1. Check your heading hierarchy

Scan for headings that jump levels unexpectedly (a # followed immediately by a ###, skipping ##). It won't cause an error, but it'll look inconsistent once rendered.

2. Confirm every link actually has a destination

It's easy to leave a placeholder like [link text]() while drafting and forget to fill in the URL. Search your document for empty parentheses right after a closing bracket before converting.

3. Match your code fences

Count your triple-backtick fences — there should always be an even number. An odd number means one fence never got closed, and everything after it may render as code.

4. Decide what to do about tables, if you have any

If your destination format is plain TXT, know going in that tables won't render as a grid. If that matters, switch your target to HTML or PDF instead, both of which handle tables properly.

5. Remove anything you don't want passed along

If you copy-pasted from another source, double-check for leftover tracked-change marks, comments, or draft notes to yourself that shouldn't make it into a final version — these copy over as regular text since Markdown doesn't have a special "comment" syntax; a Markdown comment left in the file will be visible in your final PDF or HTML unless you delete it first.

Do a test conversion first

For anything longer than a page, run it through the relevant tool once, skim the result, fix what looks off, and then do your final conversion. It's a thirty-second habit that catches the majority of formatting surprises before they reach a final document.

Frequently asked questions

Does Markdown have real hidden comments like HTML does?: Not in standard Markdown — there is no universally supported comment syntax that gets stripped out during conversion, so anything you don't want visible in the final output needs to be deleted, not just marked as a comment.