Tool
Open a Markdown file straight from its URL
Paste the address of a public .md file — the GitHub file page works too — and read it formatted right away. Your browser makes the request; there is no service in the middle.
Source
mdlint
Build: passing · License: MIT · Node: 20 and 22
A linter for Markdown documentation. Checks links, heading order and code fence languages, with no dependencies outside the standard library.
Install
npm install -g mdlint
mdlint --version
Usage
# check a whole directory, failing on warnings
mdlint check ./docs --strict
# write the table of contents back into the file
mdlint toc README.md --write
Rules
| Rule | Default | What it catches |
|---|---|---|
link-exists | error | Relative links pointing at missing files |
heading-order | warn | An h3 that follows an h1 with no h2 |
fence-language | warn | Code blocks with no language after the backticks |
no-bare-url | off | URLs pasted without link syntax |
Rules are configured in mdlint.json. Every rule can be set to error,
warn or off, and disabled inline with <!-- mdlint-disable link-exists -->.
Exit codes
0— no findings, or only findings set tooff1— at least oneerror, or any finding when--strictis on2— configuration could not be read
Contributing
- Open an issue describing the problem before sending a pull request.
- Run
npm test— the suite has to pass on Node 20 and 22. - Commits follow Conventional Commits.
License
MIT © the mdlint authors
Raw URL and file page are not the same thing
A repository serves two addresses for the same file. The page
(github.com/user/repo/blob/main/README.md) returns HTML, with the sidebar, the
history and an edit button. The raw file
(raw.githubusercontent.com/user/repo/main/README.md) returns the Markdown itself.
Only the second one is any use for reading the content, and forgetting it is the single most common reason an online viewer returns an error. Both work here: when the address you paste is recognised as a file page on GitHub, GitLab or Bitbucket, the equivalent raw URL is built before the request goes out.
| Service | What to paste |
|---|---|
| GitHub | The /blob/ page or the raw.githubusercontent.com link |
| GitLab | The /-/blob/ page or the /-/raw/ link |
| Bitbucket | The /src/ page or the /raw/ link |
| Anywhere else | Any public URL that responds with Markdown text |
The scheme is optional. Pasting raw.githubusercontent.com/… without
https:// works, because a missing scheme is assumed rather than rejected.

When opening by URL is the right move
- Reviewing a README before you commit — see how the file will look, without publishing it.
- Reading a library's docs without cloning the whole repository.
- Checking a document someone shared as a link instead of downloading it and hunting for an editor.
- Comparing two versions by opening two URLs in separate tabs.
- Reading docs on a machine you do not control, where installing an editor is not an option.
The last one comes up more than you would expect. A locked-down work laptop, a borrowed machine, a shared workstation: a browser tab is often the only place you can render a file.

Add a badge to your docs
Someone who opens your README as a raw file sees characters, not a document: no headings, no tables, nothing to skim. A badge near the top gives them one click to read the same file formatted, with an outline. Paste the address of your .md and copy the Markdown.
This is the badge, at actual size.
The raw link — the one that returns the Markdown itself, not the repository page.
What does not work, and why
A private repository will not work. The request leaves your browser with no token and no authentication, and the server answers 404. The same is true of files behind a VPN or a login wall. In those cases the way through is to download the file and paste the contents — the result is identical.
Addresses that answer with HTML are refused on purpose, even when they end in .md.
Rendering a whole repository page as if it were a document would produce nonsense; it is more
useful to say so and point at the raw link.
There is also a class of failure that is nobody's bug: a restrictive CORS policy. The remote server decides whether a browser from another origin may read its files. Raw file hosts allow it by default, which is why they work; a private documentation server usually does not.
Nothing passes through a server of ours
The request goes from your browser straight to the address you gave. There is no proxy, no queue and no record of what was opened — which is also why the destination has to permit cross-origin reads, as described above.
A shared link keeps that property. The address rides in the fragment — everything after the
# — and a browser never sends a fragment to a server. So a link that opens a
document leaves no trace in our logs, and none in the logs of whoever hosts the page the link
was on. It does enter your own browser history, the way any address does.
A link like that is written by someone else, which changes what the page is allowed to do with
it. Only https is accepted; addresses that resolve inside a private network are
refused; the request goes out with no cookies and a size cap; and the domain appears above the
editor before anything is rendered. If that domain is outside a short list of known
file hosts, nothing is fetched until you say so.
What the errors actually mean
| What you see | What it means | What to do |
|---|---|---|
| Could not fetch the file | The request never completed — wrong host, dead link, or a CORS policy that refuses browsers from other origins | Open the URL in a tab; if it downloads, the block is CORS |
| Returned a page, not a document | The address answered with HTML | Use the raw file link |
| Format not supported | The path ends in an extension that is not a text document | Point at .md, .markdown, .txt or .feature |
| Document over the limit | The file is larger than 2 MB of text | Split it, or open one section |
The distinction worth internalising is the second row. A viewer that happily renders an HTML page as Markdown does not fail — it produces a document full of tag soup and navigation text, and you find out much later that you read the wrong thing.
Where this fits in a review workflow
The usual sequence is: write the docs in a branch, push, then discover on the rendered page that a table lost its separator row or a code fence swallowed the rest of the file. Opening the raw URL of the branch closes that loop before the pull request exists.
It also works in the other direction. Reviewing someone else's documentation change is easier from the rendered file than from the diff, because a diff shows you the lines that changed and not the document the reader ends up with. Two tabs — the raw URL of each branch — is the cheapest before-and-after comparison available.
Frequently asked questions
Do I have to use the raw GitHub URL?
No. Paste the file page URL from GitHub, GitLab or Bitbucket and the matching raw address is worked out before the request is made.
Does it work with a private repository?
No. The request is made by your browser with no authentication, so the file has to be publicly reachable. For a private file, download it and paste the contents into the editor.
Why did it say the address returned a page?
Because that URL responds with HTML instead of the file. It happens with view URLs that have no known raw equivalent — use the service’s own raw file button in that case.
Is there a size limit?
Yes, 2 MB of text. Larger documents should be split, or opened one section at a time.
Can I link someone straight to a rendered document?
Yes. Put the file address in the link as a fragment — /en/tools/markdown-from-url/#url= followed by the encoded address — and the page opens it on arrival. The badge generator on this page writes that link for you.
Is it safe to click a link somebody else built?
Only https addresses are accepted, addresses that resolve inside a private network are refused, the request carries no cookies, and the domain is shown before anything is rendered. A domain outside a short known list waits for you to confirm.