What does a Markdown file actually look like?

Ordinary text with a few punctuation marks doing the formatting. Every example on this page shows the source on the left and what it produces on the right, which is the fastest way to see the relationship.

Can I edit these examples?

Yes — each one is a live editor. Type into the left side and the right side updates. Nothing is saved or sent anywhere; refresh and the example is back as it was.

What is a good README example?

One that answers, in order: what is this, how do I install it, how do I use it, and where do I go if it breaks. The example below follows that order. Everything else — badges, contributor lists, a table of contents — is optional and usually added too early.

Why do the examples use different styles?

Because the documents have different jobs. A README opens with a one-line summary; release notes are grouped by version and change type; a doc page leads with the task. The syntax is identical — the structure is what changes.

Where do I get these as files?

The template library has each of these as a complete document you can fill in and download, with the placeholders wired to a small form. These examples are for reading; those are for taking.

Markdown examples

Four complete documents, each with its source beside the rendered result. They are live — edit the left-hand side of any of them and the right-hand side follows. The point is not the syntax, which is the same in all four; it is what changes when the document has a different job to do.

A README

The most-read document in any project, and usually the least edited. It answers four questions in order: what is this, how do I install it, how do I use it, and what do I do when it breaks. Anything before the one-line summary is in the reader's way.

A README — edit it and watch the result

Markdown

Result

Open the full editor Runs in this tab — nothing is uploaded.

One thing is missing on purpose: the row of badges most READMEs open with. They are written as ordinary images —

[![Build](https://img.shields.io/badge/build-passing-brightgreen)](https://example.com)

— and that is the problem. Each badge is an image fetched from a third-party service every time anyone loads your README, so they break when that service is slow or rate-limited, and they leak a request to it. This page makes no third-party requests at all, which is why the example above has none. Two badges that mean something beat eight that decorate.

Release notes

Grouped by version, newest first, then by kind of change. The value is in the grouping: someone deciding whether to upgrade reads the Breaking and Security lines and skips the rest. A flat list of commits makes them read everything.

A changelog — the same syntax, a different shape

Markdown

Result

Open the full editor Runs in this tab — nothing is uploaded.

A documentation page

Task-shaped: what you will achieve, what you need first, numbered steps with the commands in them, then what to do when a step fails. Note the front matter at the top — the block between three dashes that a static site generator reads for the title and description.

A docs page, with YAML front matter

Markdown

Result

Open the full editor Runs in this tab — nothing is uploaded.

Meeting notes

Decisions first, because that is what anyone reads them for. Discussion second, actions last with a name attached to each. Task list syntax means the open items are countable rather than buried in prose.

Meeting notes — decisions, then actions

Markdown

Result

Open the full editor Runs in this tab — nothing is uploaded.

What is the same in all four

Every one of these uses the same handful of marks: hashes for headings, asterisks for emphasis, hyphens for lists, backticks for code, pipes for tables. There is no document type, no mode and no template engine — the difference between a README and a set of meeting notes is entirely in how you arrange the same six things.

That is worth knowing early, because it means learning Markdown is not a per-document-type exercise. Learn the marks once and every document is a structure decision instead of a syntax one.

What is different, and why

Document	Opens with	Because
README	One line on what it is	The reader does not yet know whether to care
Changelog	The newest version	The reader has an old version and wants the delta
Docs page	The task	The reader arrived from a search with a job to do
Meeting notes	Decisions	The reader missed the meeting and needs the outcome

Taking one away

These are here to read. If you want one as a file, the template library has each of them as a complete document with a small form for the blanks — type a project name once and it fills the title, the install line and every URL that mentions it, then copy or download the result.

Common questions

What does a Markdown file actually look like?: Ordinary text with a few punctuation marks doing the formatting. Every example on this page shows the source on the left and what it produces on the right, which is the fastest way to see the relationship.
Can I edit these examples?: Yes — each one is a live editor. Type into the left side and the right side updates. Nothing is saved or sent anywhere; refresh and the example is back as it was.
What is a good README example?: One that answers, in order: what is this, how do I install it, how do I use it, and where do I go if it breaks. The example below follows that order. Everything else — badges, contributor lists, a table of contents — is optional and usually added too early.
Why do the examples use different styles?: Because the documents have different jobs. A README opens with a one-line summary; release notes are grouped by version and change type; a doc page leads with the task. The syntax is identical — the structure is what changes.
Where do I get these as files?: The template library has each of these as a complete document you can fill in and download, with the placeholders wired to a small form. These examples are for reading; those are for taking.