# Markdown parity check

Enter a page address to compare the main content of its HTML and its Markdown version. The report lists missing, added and changed blocks, numbers and links. It also shows where each one sits in the source.

The check compares what the two versions say. It does not score the page. A pass does not prove that both versions mean the same thing.

## How to use it

- In a browser: enter the page address in the field above and press Check.
- More options: a separate Markdown address, a CSS selector for the HTML content, strict mode and front matter handling.
- As an agent: send a JSON POST request, described below under Use it from an agent or CI.

## What this version checks

This hosted version checks the published pages of turva.dev. The site's own Worker renders both versions of the page, so a check sends no request over the network. An address on any other site is refused with a message that points to the command-line tool.

To check another site, run the same comparison on your own machine:

    npx markdown-parity-check --url https://example.com/page

The page and the command run the same comparison code from the open npm package. The report has the same format too.

## What the check compares

- The HTML content comes from main, article or role="main". Without any of them the page body is used and the report warns about it. A CSS selector overrides the choice.
- Headings, paragraphs, list items, tables, code blocks and links are compared block by block.
- Missing and added blocks are errors. So are differences in text, numbers, tables and links.
- A change of order, heading level, case or punctuation is a warning.
- Front matter at the top of the Markdown is kept and compared by default. Choose strip to remove it first.
- Strict mode counts warnings as failures.

## What a result tells you

Pass means that no rejecting difference was found in the compared blocks. Fail lists the differences. Error means that the comparison could not finish, for example because the main content was empty or the page went over a limit.

A missing Markdown version is a failure and never a pass. When the Markdown request returns HTML or an error page, the report says so and compares nothing.

JavaScript is not run. Content that a page builds in the browser is compared as the server sent it.

Not every turva.dev page passes. The HTML adds buttons, cards and forms. Some pages also leave out the Related list that the Markdown carries, and the report names each of these differences.

## Limits

- One page and its Markdown version per check. Nothing else is fetched.
- HTML up to 512 KiB and Markdown up to 128 KiB.
- Up to 250 000 block pairs. A larger page ends with an error, never with a partial result.
- About 10 checks per minute from one IP address at each Cloudflare location.

The command-line tool accepts larger pages.

## Use it from an agent or CI

Send a JSON request:

    POST https://turva.dev/markdown-parity-check
    Content-Type: application/json
    Accept: application/json

    {"url": "https://turva.dev/tools", "strict": false, "frontMatter": "keep"}

The optional fields are markdownUrl and selector. The response is the report in the same JSON format as the command's --format json output. Its summary.exitCode carries the same 0, 1 or 2.

HTTP 200 carries a pass or a fail. 400, 413 and 415 mean that the request was malformed. 403 means that the address is outside what this version checks, and 422 means that the comparison could not finish. 429 and 503 ask you to try again later. The Retry-After header says when. 500 means that the service itself failed.

In CI, run the package with --strict. Source and releases are on [GitHub](https://github.com/erekola/markdown-parity-check) and the package is on [npm](https://www.npmjs.com/package/markdown-parity-check).

## What is kept

The service compares the two versions in memory and discards them. It does not store the report or write the address to its logs. The address travels in the request body and not in the page URL. Every response to a check carries a no-store header.

## Related

- [Serving Markdown to AI clients](/guides/markdown-for-agents)
- [llms.txt validator](/llms-txt-validator)
- [Free tools for agent-readiness](/tools)