Preview Markdown safely before publishing a README or article

Problem

Markdown looks portable because the source is plain text, but renderers disagree on extensions and edge cases. GitHub, a documentation generator, a CMS, and an email editor can handle heading IDs, task inputs, tables, raw HTML, footnotes, math, and URL policies differently. A pasted document may also contain tracking images, private issue links, internal hostnames, tokens in code examples, or HTML that a destination rewrites. A local preview can expose many of these problems, but it cannot replace the destination's renderer, stylesheet, security policy, or final review.

Sources and standards

These authoritative references define the formats or security boundaries used in this workflow. Tool-specific verification is documented separately above.

• CommonMark Specification

  CommonMark

When to use this

• A README or changelog contains tables, tasks, code fences, images, or footnotes that are hard to inspect as plain text.
• A technical article uses KaTeX math, definition lists, or collapsible details and needs a visual pass before publication.
• Markdown will be converted to HTML for a CMS, documentation site, knowledge base, or email workflow.
• A copied document may include remote images, raw HTML, private links, internal names, or sensitive example values.

Steps

1. Step 1

   Remove private and environment-specific data

   Search the source for access tokens, cookies, email addresses, account IDs, internal hostnames, private repository links, customer names, and production log values. Replace them with deliberate examples before previewing or sharing. Local rendering reduces transmission, but the working copy, clipboard history, downloads, and eventual destination can still retain sensitive text.

2. Step 2

   Identify the destination's Markdown contract

   Check whether the target uses GitHub Markdown, CommonMark, a static-site plugin set, a CMS parser, or pre-rendered HTML. Record the features that matter: table alignment, task states, heading anchors, code language names, footnotes, math delimiters, raw HTML, and relative paths. This preview supports many common features but is not GitHub's own renderer.

3. Step 3

   Preview structure before appearance

   Load the document and verify one logical heading hierarchy, list nesting, table headers, link text, image alt text, code-fence closure, footnote references, and readable fallback text. Use Manual mode for a large document so repeated parsing does not interfere with editing. Treat syntax highlighting and typography as secondary to correct structure.

4. Step 4

   Make a deliberate remote-image decision

   Leave remote images disabled during the first review. Relative paths and safe raster data images can still be inspected, while HTTP(S) image URLs are removed and reported. Enable remote images only when every host is trusted and contacting it is intended. Each enabled image can reveal an IP address, timing, user agent, and referrer-related metadata despite the no-referrer policy.

5. Step 5

   Inspect sanitization and the HTML fragment

   Compare the rendered pane with the HTML output. Confirm that scripts, event handlers, iframes, embedded media, forms, active URL schemes, SVG data images, and arbitrary styles are absent. Safe details, tables, task checkboxes, links, and KaTeX markup may remain. Remember that the copied result is a content fragment, not a complete themed document.

6. Step 6

   Test in the real publishing system

   Paste the original Markdown or exported HTML fragment into a draft, staging page, or disposable test entry in the destination. Recheck anchors, relative URLs, code styling, math assets, table overflow, dark mode, keyboard navigation, and mobile width. Review the final network requests and rendered DOM because the destination may add, remove, or rewrite markup after this tool's sanitization.

Example

# Version 2.4 release

- [x] Run automated tests
- [ ] Publish migration notes

| Area | Result |
| --- | ---: |
| Keyboard review | Pass |
| Mobile table | Check |

See the staging record.[^review]

[^review]: Replace this note with the public review date before publishing.

Confirm one h1, disabled task checkboxes, a header row, right-aligned result cells, a linked footnote, and no private staging URL. Then repeat the check in the destination renderer.

Common mistakes

FAQ