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.

README.md Sample loaded

The file page on GitHub, GitLab or Bitbucket works too: the matching raw URL is worked out for you.

Markdown edit freely
Preview live

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

RuleDefaultWhat it catches
link-existserrorRelative links pointing at missing files
heading-orderwarnAn h3 that follows an h1 with no h2
fence-languagewarnCode blocks with no language after the backticks
no-bare-urloffURLs 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 to off
  • 1 — at least one error, or any finding when --strict is on
  • 2 — configuration could not be read

Contributing

  1. Open an issue describing the problem before sending a pull request.
  2. Run npm test — the suite has to pass on Node 20 and 22.
  3. 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.

ServiceWhat to paste
GitHubThe /blob/ page or the raw.githubusercontent.com link
GitLabThe /-/blob/ page or the /-/raw/ link
BitbucketThe /src/ page or the /raw/ link
Anywhere elseAny 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.

The address field of the tool with a raw GitHub URL for a README typed in, and the button that fetches and renders the file beside it.

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.

A README fetched by address and shown formatted, with headings, lists and code blocks, so you can read it before cloning the repository.

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.

read formatted This is the badge, at actual size.

The raw link — the one that returns the Markdown itself, not the repository page.

An example, while the field is empty. Paste your address to replace it.

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 seeWhat it meansWhat to do
Could not fetch the fileThe request never completed — wrong host, dead link, or a CORS policy that refuses browsers from other originsOpen the URL in a tab; if it downloads, the block is CORS
Returned a page, not a documentThe address answered with HTMLUse the raw file link
Format not supportedThe path ends in an extension that is not a text documentPoint at .md, .markdown, .txt or .feature
Document over the limitThe file is larger than 2 MB of textSplit 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.