Checking the markdown a model hands you before it becomes a page

Raw markdown is a promise, not a page

A markdown document looks finished in a chat window because the window renders it. The same text pasted into a CMS, a static site or an email editor is subject to a different parser, different extensions and a different CSS reset, and the differences are where the failures live.

The most common is the table. A pipe table needs a delimiter row — that second line of dashes and colons that tells the parser which cells are headers. Without it, the entire table renders as one paragraph of vertical bars, which is exactly the kind of thing that is invisible while you are editing and glaring on a page.

The second is the fence. An unclosed triple-backtick block swallows the rest of the document into a code block, so everything after it renders in monospace and the page ends in the middle of a paragraph. The third is emphasis: nested asterisks and underscores that resolve differently depending on whether the parser follows CommonMark strictly.

Reading the rendered version is the only way to see what the visitor gets. Reading the source is how you find out why.

Citations fail in three predictable ways

A model writing a research summary will produce bracketed numbers that look like citations and then fail to emit the reference list. The prose reads as though it is sourced and nothing at all is sourced, which is worse than no citation because it borrows authority from a list that does not exist.

When the list does appear, the labels frequently do not match the body: the text cites [4] and the list runs from 1 to 3, or the list uses author-year and the body uses numbers. This is the failure that survives review most often, because the presence of a references section makes an editor stop looking.

The third is the placeholder. A citation in the shape [source] or (Smith, YEAR) or a URL with example.com in it has been left in from a template the model invented. Each of those is a public confession that nobody checked, so they are worth finding before publication rather than after.

• Bracketed numbers with no matching definition.
• Numbered labels that do not run in sequence.
• References present but never cited in the body.
• Placeholder markers: [source], (Author, Year), example.com.

Links, images and the paths that only worked in the chat

Relative links are the quiet killer. A model working in a sandbox produces paths like /images/chart.png or /docs/setup, which resolved inside its own environment and 404 on your domain. The rendered preview shows a link; nothing about it looks wrong until a reader clicks it.

Plain-http targets get a similar treatment. They will be blocked as mixed content on an https page, or worse, silently accepted by an old browser, and either way the link is a liability rather than a link. Unsafe schemes — javascript and data URLs — are worse still, and they are worth finding before a CMS sanitises them inconsistently across pages.

Images without alt text are a structural failure and an accessibility one. In markdown, an image with empty alt text renders as a broken-sounding element to a screen reader and as nothing at all when the file fails to load. A model writing a hero image tag will usually omit the alt, because alt text is the part of an image that carries meaning and meaning is not visual.

The checker lists each of these by cause rather than by symptom, so a wall of pipes in the preview becomes a row with the wrong number of separators, and a dead reference becomes a citation number with no definition.

Which dialect you are publishing into

GitHub-flavoured markdown is the practical default: tables, strikethrough, task lists and fenced code with language hints. Most CMSs and static site generators implement a superset or a subset of it, and the differences only matter at the edges — footnotes, definition lists, embedded HTML.

If your target supports raw HTML inside markdown, an unscoped script tag from a model's output becomes a real script on your page. That is worth deciding before you paste, not after. If your target sanitises HTML, the markdown that relied on it will render as literal tags instead of the formatting the model intended.

Knowing the dialect also tells you which of the findings to trust. A table that fails here may be valid in a parser that tolerates missing delimiter rows; a link that looks relative here may be correct in a repository where it is relative to the file. The checker reports structure, you supply the destination.

Code blocks, footnotes and the long tail

Fenced code is where generated markdown most often breaks the page, because a model that runs out of attention will emit an opening fence and no closing one. Everything after it renders in monospace, and the visible symptom is a page that appears to end in the middle of a paragraph.

Language hints matter for the same reason a closed fence does. A fence with no language is a grey block that nobody can scan, and a fence with a language your highlighter does not support renders identically to one that does. Check that each block declares something, and that the declarations are consistent across a document.

Footnotes are the least portable construct in markdown. Some parsers support bracketed caret syntax, some require an extension, and a model asked for footnotes will mix both within one document. If your target does not implement them, every footnote marker becomes literal text in the middle of a sentence.

The long tail is escaping. An asterisk used as multiplication, a hash used as a number sign, a pipe inside a table cell, a colon next to a slash that becomes an autolink to a scheme that does not exist. Each of those is a rendering bug that reads as carelessness, and each takes a backslash to fix.

• Unclosed fences swallowing the rest of the page.
• Missing or inconsistent language hints on code blocks.
• Footnote syntax that the target parser does not implement.
• Unescaped asterisks, pipes, hashes and autolinked colons.

A pre-publish sequence that takes five minutes

Render first, read second. The rendered view is the only one that answers what a visitor sees, and it is much faster to spot a collapsed table than to verify one in source. Skim the preview the way a reader would, top to bottom, without stopping.

Then the structure pass: citation numbers against definitions, table delimiter rows, closed fences, images with alt text. Those are mechanical, they are the majority of findings, and they are the ones that make a document look unedited rather than wrong.

Then the link pass. Shape, scheme, relativity. No network requests are made, so this checks whether a target looks like a URL a reader could follow, not whether it resolves. The dead-link check is a person clicking, and it is worth doing on the four or five links that matter most.

Then hand the substance to the claim tools. Structure first because it is cheap and it stops the eye, and substance second because it is the part that needs a person who knows the field.

Publishing targets that sanitise

Every CMS makes a decision about how much HTML it will accept from a markdown field. Some pass it through, some strip it, some escape it so it appears as visible tags. The same document renders three different ways in three targets, and all three are correct behaviour.

That matters for generated output because models reach for raw HTML whenever markdown is awkward: a two-column layout, an embedded video, a styled callout. If your target strips the tags, the page loses the structure and the text runs together; if it escapes them, the page shows the tags.

Test one representative document in the real target before trusting any preview. A markdown checker can tell you the source is well-formed; only the destination can tell you what survives.

The citation habits that outlive a draft

Two habits prevent most citation failures before they exist. Cite as you write rather than afterwards, and keep a list of sources at the top of the document you are working in, not at the bottom of the one you will publish from.

The second is to read every reference out loud as a sentence: as the report found, as the policy states. If the sentence does not name the document, the reference is decoration, and a reader who follows it will not know what they are looking at.

What structural validation leaves out

None of this checks whether a link works. There are no network requests: the tool validates the shape of a target and whether its reference is defined, not whether the destination resolves, redirects or still exists. A perfectly formed citation to a deleted page passes.

It also cannot judge relevance. A source can exist, resolve and be entirely irrelevant to the sentence citing it, and that is the most common failure of AI-assisted research writing. Checking relevance is a reading task: open the source, find the passage, decide whether it says what the draft claims.

So the flow is: render, fix the structure, then check the substance. A document that renders correctly is publishable in the mechanical sense and may still be wrong in every particular.

For the substance, take the claims into the review editor or the matrix, and take anything consequential to a reviewer who knows the field. The markdown checker's job is to make sure nobody is arguing about pipes when they should be arguing about facts.