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.
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 --versionUsage
# check a whole directory, failing on warnings
mdlint check ./docs --strict
# write the table of contents back into the file
mdlint toc README.md --writeRules
| 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.
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.
The address is not written into this page's URL either. That is a deliberate trade: you cannot share a link that reopens the document, and in exchange nothing about the document you read is recoverable from a browser history, a bookmark or a server log.
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?
Not from this page: the address you type is not put in the page URL, so nothing about the document you opened is shareable or logged.