What an MD file is

It is a text file where a hash means a heading. That is genuinely the whole format.

It is a text file with conventions. A hash starts a heading, a dash starts a list item, asterisks mark emphasis, square brackets and parentheses make a link.

A plain text source beside the same content rendered as a page.
A plain text source beside the same content rendered as a page.

The whole syntax, nearly

# A heading
## A smaller heading

Normal text, with **bold** and *italic*.

- A list item
- Another one

[A link](https://example.com)

That covers the great majority of what anybody writes. Tables, quotations and code blocks exist and are learned when needed.

The point is that the source is readable as it stands. Somebody who has never seen the format understands the file without being told anything.

Property Word processor Plain text with markup
Readable without software No Yes
Meaningful version differences Poor Yes
Precise layout Yes No
Converts to other formats Awkwardly Cleanly
Opens in forty years Probably Yes

Why people use it

It does not rot. A text file opens in anything, forever. Proprietary document formats need their program, and the program needs a licence, and eventually a version that still runs.

Differences are meaningful. Two versions compared show the sentence that changed. Two word processor files compared show that the files differ.

It converts. One source becomes a page, a fixed document, slides or a word processor file. Nothing is written twice.

It gets reviewed. In a code project it sits beside the code, so documentation goes through the same review as everything else, which is the only arrangement under which documentation stays current.

What it cannot do

Layout.

There are no page breaks, columns, positioned images or precise spacing. That is not a gap in the format; it is the trade. Structure is described and appearance is decided by whatever renders it.

If the document is designed, with a layout that has to hold exactly, use a design tool. If the document is structured, headings and paragraphs and lists, this is the better container.

One source file producing a page, a fixed document and slides.
One source file producing a page, a fixed document and slides.

Publishing it

Readers should not see the marks.

Render it to a page and publish that. The headings become headings, the links become clickable, and the reader gets a document rather than a file full of punctuation.

The source stays where you keep it, and regenerating the page is how a correction is made.

Closely related: Turning Markdown into a document, and What is a CSV file for the adjacent problem.

Put it at an address

Open it in any text editor, learn the four marks that cover most writing, use it for structure rather than layout, convert instead of rewriting, and publish the rendered page rather than the source.

Questions people ask

What is in the file?

Plain text with a few punctuation conventions: a hash for headings, asterisks for emphasis and lists, square brackets for links.

How do I open one?

Any text editor, because it is a text file. Many editors and services also render it, showing the headings and lists formatted.

Why do people prefer it to a word processor?

The file is readable without any program, differences between versions are meaningful, and it converts cleanly into pages, documents and slides.

What can it not do?

Precise layout. There are no page breaks, columns or positioned elements, which is why a designed document is not written in it.

Why do code projects use it?

It sits in version control alongside the code, so documentation is reviewed in the same way and its history is visible.

Keep reading