Preview Markdown

Which Markdown, and why the HTML is sanitised

Markdown is a family rather than one specification, and the dialect here is the widely-agreed GitHub-flavoured set: headings, emphasis, lists, links, images, block quotes, tables, fenced code blocks with syntax highlighting, task lists, strikethrough, footnotes and automatic links. That is what almost everyone writes and what a README will contain. More exotic dialects and the custom plugins a particular site adds — admonition blocks, shortcodes, templating — are not, so a document written for one specific generator may show some of its syntax literally.

Raw HTML is rendered but sanitised first, and this is the part worth understanding. Markdown deliberately permits HTML inside it, which means a Markdown file from anywhere can contain a script tag, an inline event handler, an iframe or a javascript: link. Rendering that as-is would run a stranger's code in your session simply because you pasted their README to look at it. Everything executable is stripped before anything is displayed, so the formatting survives and the code does not.

That is a general lesson rather than a detail of this page. Any system that renders user-supplied Markdown — a comment box, a wiki, a support ticket — is rendering user-supplied HTML unless it sanitises, and "it is only Markdown" is how that gets overlooked. Converting the Markdown is not a security boundary; the sanitising step is.

What you get is a preview of the content, not of any particular site. GitHub, GitLab and a documentation generator each apply their own stylesheet, heading anchors and extensions, so the same file looks different in each — the structure shown here is what they all agree on. Nothing is fetched, so images referenced by a web address load only if that server allows it, and relative paths to files in a repository cannot resolve at all.

When you want something else

For a README you are actually writing, preview it where it will live. GitHub's own editor previews with its exact rendering, extensions and anchors, and the GitHub CLI — gh markdown-preview — does it locally against the same renderer. For documentation, the generator itself (MkDocs, Docusaurus, Hugo) has a live-reloading preview showing the real styling and navigation, which is what the reader will see.

For editing rather than checking, a Markdown editor with a live pane — Obsidian, Typora, VS Code with its built-in preview — beats pasting into a page each time, because the preview updates as you type and the file stays where it is. This page is for reading somebody else's Markdown, or for a quick look at something you have been sent.