Markdown File
Definition
John Gruber released Markdown in 2004 with the aim that the unconverted text should still read naturally. A line beginning with one to six hash characters is a heading, text wrapped in asterisks or underscores is emphasised, lines starting with a hyphen make a list, and a link is written as the text in square brackets followed by the URL in parentheses. Gruber left plenty undecided, so implementations diverged and CommonMark was written in 2014 to settle the ambiguities; GitHub Flavored Markdown adds tables, task lists and strikethrough on top of it. Files use .md or .markdown, and the registered content type is text/markdown, given to it by RFC 7763 in 2016. The format is deliberately incomplete: anything it cannot express, such as a table with merged cells, is written as raw HTML inside the document.
Why It Matters
The gap that catches people is that publishing a .md file does not publish a page. Upload notes.md to any static host and a visitor sees the hashes and asterisks exactly as typed, because no browser has ever shipped a Markdown renderer. Something has to run the conversion first — a static site generator, a build command, an editor's export, or a small script — and that something runs on your machine, not on the host. The quieter benefit is that a change shows up in a diff as one altered line, where the same edit in a word processor document is an opaque change to a binary archive. That is why documentation, changelogs and READMEs live in Markdown almost universally.
How It Works
A converter reads the Markdown, builds a document tree and emits HTML: a line starting with two hashes becomes an h2 element, a hyphenated list becomes ul and li elements, and the result is wrapped in a template that supplies the head, the stylesheet and the navigation. Pandoc does this from the command line, as does the markdown-it library in Node, and every static site generator — Eleventy, Hugo, Astro, Jekyll — is that step plus a templating system. Many files carry front matter at the top too: a small block fenced by three hyphens, usually YAML, holding the title, date and tags the template reads. What you upload afterwards is the generated HTML with the CSS and images it references. A host that serves static files will not run this step for you, so a .md left on the server is source you are storing, not a page you are publishing.
Real-World Example
A developer writes release notes as a folder of .md files, runs a build that turns them into HTML pages, and drags the output folder onto 99helpers. The site appears at changelog.99helpers.site with index.html at the root, and each release gets its own address. The original .md files go up in the same upload, costing a few kilobytes, so anyone can read a page's source by adding .md to the URL — it arrives as text/markdown and shows as plain text, which is right for a source file.
Common Mistakes
- ✕Uploading a .md file and expecting a formatted page — the browser displays the raw syntax, because conversion is a step that happens before publishing
- ✕Assuming every renderer behaves the same — tables and task lists are GitHub extensions, not CommonMark, and a strict converter leaves them as literal text
- ✕Forgetting that most converters pass raw HTML straight through — that is useful for a video embed and dangerous for text submitted by other people
- ✕Writing front matter with a tab in the indentation — YAML rejects tabs, and the page is silently skipped or built without its title
Related Terms
Static Site Generator
A static site generator is a tool that turns content and templates into a folder of finished HTML files. Hugo, Eleventy, Astro, Jekyll and Next.js in export mode are the common ones.
HTML File
An HTML file is the source of a web page: nested elements that describe headings, paragraphs, links, images and forms. It is the one format a browser executes rather than merely displays — it fetches what the file references and runs the scripts it names.
Plain Text File
A plain text file holds characters and line breaks and nothing else — no fonts, no sizes, no embedded images. It is the format that survives everything, and the one that carries no clue about how to read its own bytes.
Build Step
A build step is the command that turns source files into the folder a web server can actually serve. It runs before publishing, produces an output folder, and is not part of the live site.
index.html
index.html is the file a web server returns when a visitor asks for a folder rather than a named file. It is the default document for the site root and for every directory inside it.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →