Markdown Broken Link Checker

Markdown Broken Link Checker

What the link checker does

This page scans Markdown for links and checks whether they are reachable. It finds inline links, reference-style links and bare http or https URLs, skips fenced code blocks, removes duplicates and requests each address from the server. The result is a table with the link text, URL, HTTP status and any error. You can copy or download a JSON report. It is a reachability check, not a guarantee that the destination contains the right content.

Which links are checked

Inline links such as a label followed by a URL in parentheses are supported. Reference-style links that use a separate definition are also supported, and bare http or https URLs in the text are picked up. Links inside fenced code are skipped so examples do not create false failures. Relative links, mail links, anchors and other non-http schemes are never requested; inline ones are still listed in the report with a validation error so you can review them. Deduplication means the same URL is requested once even if it appears many times.

How the server checks a link

The server sends an HTTP GET request with a browser user agent, follows up to five redirects, and uses a 15-second total timeout with a 5-second connection timeout. Requests are made one at a time. That is gentle on remote hosts but slow for a document with hundreds of links. A 200 status is treated as reachable; redirects and error codes are reported. Some sites block automated requests even when the page works in a browser.

Private and local addresses are rejected

The checker refuses non-http schemes, localhost names, private IP ranges and reserved addresses. This protects the server from being used to probe an internal network. If you need to check a staging site behind a firewall, this page is not the right tool. Use a local link checker that runs inside your network. A rejected address will appear as an issue rather than a successful response.

Reading the status table

The table shows each URL, its status and an error message when the request fails. A 200 means the server responded successfully. A 301 or 302 means a redirect was followed; the final response may still be an error. A 403 often means the site blocked the request, not that the link is dead. A timeout can be a slow host or a network problem. Investigate the reason before deleting a link.

False positives and false negatives

A link can be reported as broken when the host blocks bots, requires JavaScript or returns a challenge page. A link can be reported as working when it redirects to a generic home page or a soft 404. The checker does not read the page content or compare it with the link text. Use the report as a starting point, then open the questionable links in a browser and confirm what the reader will see.

How to use it

Paste the Markdown into the editor. Press the check button. Wait for the sequential requests to finish; a long document can take a while. Review the issue count and the table. Copy the raw JSON or download it as markdown-link-issues.json if you need to track the results. Fix the Markdown and run the check again. The page does not edit your document automatically.

Limits and performance

The input limit is 200,000 characters. The server checks links sequentially, so the total time grows with the number of URLs. The 15-second timeout applies to each request, which means a few slow hosts can make the whole run feel stuck. Very large documents should be split or checked with a local tool that can run requests in parallel. The page does not cache results between runs.

Privacy and server requests

The Markdown is sent to the Newisty server, and the server contacts each URL. That means the destination hosts see a request from Newisty, not from your browser. Do not paste private documents or links that contain tokens, signed URLs or internal addresses. For confidential material, run a link checker locally and keep the requests inside your own environment.

Common problems

If every link fails, the server may be unable to reach the network or the sites may block it. If a known-good link fails, try it in a browser and check for a bot challenge. If the run is slow, reduce the number of links or split the document. If a link is missing from the report, confirm that it is not inside a code fence or written as a relative path. If the JSON is empty, check that the input contains at least one supported URL.

When to use it

Use it before publishing documentation, a README or a blog post with many external references. It is a quick way to find typos and dead destinations. It is not a full site crawler, a spelling checker or a replacement for manual review. For a documentation site with hundreds of internal links, use a build-time link checker that understands the site's routes and can run in continuous integration.

What not to do

Do not assume a 403 means the page is gone. Do not paste private URLs or signed links. Do not use the checker to probe internal systems. Do not delete a link solely because an automated request failed. Do not expect it to validate anchors or relative paths. Do not run it on a huge document and assume the first timeout is a permanent failure.

Working with redirects

The checker follows up to five redirects, so a shortened URL or a moved page can still pass. The final status is what matters, not the first response. If a redirect chain loops or exceeds the limit, the request fails. For documentation, update the link to the final destination when you can. A permanent redirect may work today, but it can be removed later. Record the final URL in the report so the next review has a clearer target.

How links are picked out of your Markdown

Knowing exactly what the extractor matches explains most surprises in the results table. The server makes three passes over every part of the document that is outside a fenced code block:

1. Inline links written as [text](url), with or without a quoted title after the URL. Image syntax with a leading exclamation mark is skipped in this pass.
2. Reference links written as [text][ref] or the collapsed form [text][]. The reference name is matched against the definitions in the document without regard to case. A reference with no matching definition is silently ignored, and a definition that nothing uses is not checked. The shortcut form, a plain [text] on its own, is not recognised.
3. Bare URLs that begin with http:// or https:// anywhere in the text. This pass also picks up the address inside image syntax, so image URLs are checked too; they appear in the table with the URL in place of link text.

Each address is checked once. The duplicate test ignores case, so two links that differ only in capital letters count as one row.

Rows that look broken but are not dead links

Some issues in the report come from the way a link was written rather than from the destination:

• Relative paths, anchors and mail links. These are never requested, but an inline link such as [guide](./guide.md) or [top](#intro) still gets a row, marked as an issue with a message asking for a valid URL. Treat those rows as "not checkable here", not as broken.
• Empty targets. A link written as [text]() is reported with the error "Empty URL". That one is a real mistake worth fixing.
• Parentheses in the URL. The address stops at the first closing bracket, so a link such as a Wikipedia page whose title contains brackets is cut short and may come back as a 404. Encode the brackets as %28 and %29 and check again; most sites accept the encoded form.
• Trailing punctuation on bare URLs. A comma or full stop that ends a sentence is taken as part of the address. Put bare URLs in angle brackets or turn them into proper links.
• Spaces in an inline URL. A link whose address contains a space is not matched at all, so it will be missing from the report.

A row is marked OK when the final response has a status from 200 to 399. Everything else, including a request that never got a status code, counts toward the issue total shown in the status panel.

Frequently Asked Questions