Markdown Example: A Sample .md File You Can Copy
September 11, 2026 · 10 min read
Markdown Example: A Sample .md File You Can Copy
The fastest way to learn the syntax is a complete Markdown example, not a list of fragments. Below is one realistic README-style .md file with every common element and a note on why each is there. A table shows which lines are CommonMark and which are GitHub-only, and a short test file checks any renderer.
What Is Markdown With Example?
Markdown is a plain-text syntax for formatted documents. You type punctuation instead of clicking buttons: # for a heading, ** around bold words, - for a bullet. A converter turns the text into HTML, and platforms such as GitHub, Reddit, and Discord do that conversion for you.
The shortest useful example is three lines:
# Weekly update
We shipped **two fixes** and one new [settings page](https://example.com).
- Next: write the docs
That renders as a heading, a sentence with bold text and a link, and a one-item bullet list. Everything else in Markdown is a variation on that pattern.
People search for markdown examples of several shapes: a README, a changelog, meeting notes, a blog post with front matter, a documentation page. They all use the same dozen constructs in different proportions, so one well-chosen example markdown file covers the lot.
We picked a README because it's the markdown file example most people need first, and because GitHub renders it the moment you push it. Other examples of Markdown, such as a markdown readme example for a library versus an app, differ only in which sections they keep. The Markdown cheat sheet is the reference for every symbol; this post is the worked example of a Markdown document you can copy whole.
The Complete Example of Markdown: A README-Style .md File
Copy this into a file named README.md. It's the shape of a real project readme, so it doubles as a readme markdown example. Everything in it renders on GitHub as of September 2026, and the annotations below say what to change for other platforms.
# Weather CLI
 
A small command-line tool that prints the forecast for any city. Written in Python 3.12, no API key required.[^1]
## Installation
1. Install Python 3.12 or newer.
2. Clone the repository and move into it.
3. Install the package in editable mode:
```bash
git clone https://github.com/example/weather-cli.git
cd weather-cli
pip install -e .
```
## Usage
```bash
weather "Lisbon" --days 3
```
| Flag | Default | Description |
|------|---------|-------------|
| `--days` | 1 | Number of days to show |
| `--units` | metric | `metric` or `imperial` |
> **Note:** Forecasts are cached for 10 minutes to stay under the rate limit.
## Roadmap
- [x] Three-day forecast
- [ ] Hourly view
- [ ] ~~Windows installer~~ (dropped; use pip)
---
Built by the [Weather CLI contributors](https://github.com/example/weather-cli/graphs/contributors). Licensed under MIT.
[^1]: Data comes from a public forecast API with no authentication.
What Each Section of the Sample Markdown File Does
Every element in the example is there for a reason. Here's the annotation, top to bottom.
The H1 and badges. One # heading names the project. The badge line is two image links side by side; GitHub renders them inline because images are inline elements.
The description with a footnote. [^1] marks a footnote and the matching [^1]: line at the bottom holds the text. GitHub renders footnotes in READMEs, issues, and pull requests, but per GitHub's formatting docs not in wikis.
Numbered install steps and a fenced code block. The list uses 1., 2., 3.; Markdown renumbers automatically if you reorder. The fence has bash after the opening backticks, which GitHub passes to Linguist for syntax highlighting.
Pipe table. The header row, a separator row of dashes, then data rows. Backticks inside cells are fine; a literal pipe inside a cell needs \|.
Blockquote with bold. > starts the quote. GitHub also understands > [!NOTE] for a coloured alert box, which we left out because most other renderers show it as a plain quote.
Task list with strikethrough. - [x] and - [ ] render as checkboxes; ~~text~~ crosses out a dropped item.
Relative image path. docs/screenshot.png resolves against the repository on GitHub, so the image works without an absolute URL. Elsewhere, paths resolve against wherever the file is being viewed.
Horizontal rule and footer. Three hyphens on their own line draw the rule. The footer is plain text with a link.
For advice on what a README should say, rather than how to format it, see the README Markdown guide.
Which Lines Are CommonMark and Which Are GFM-Only?
The CommonMark spec defines the core; GitHub Flavored Markdown adds extensions that most modern renderers have adopted but some have not. Knowing which is which tells you what will break when you paste the sample somewhere new.
| Element in the sample | Standard | Renders on |
|---|---|---|
| Headings, paragraphs, emphasis, links, images | CommonMark | Everywhere |
| Numbered and bulleted lists | CommonMark | Everywhere |
| Fenced code with language hint | CommonMark (highlighting is renderer-specific) | Everywhere; colours vary |
| Blockquote, horizontal rule | CommonMark | Everywhere |
| Pipe table | GFM | GitHub, GitLab, Obsidian, most editors; not Slack or original Markdown |
| Task list checkboxes | GFM | GitHub, GitLab, Obsidian; plain bullets elsewhere |
Strikethrough ~~ | GFM | GitHub, GitLab, Discord, Obsidian; not original Markdown |
Footnotes [^1] | GitHub extension (2021), not in the GFM spec | GitHub, GitLab, Obsidian, pandoc; not GitHub wikis |
Alerts > [!NOTE] | GitHub only | GitHub; plain quote elsewhere |
The GitHub Markdown cheat sheet covers the GFM-only lines in detail, including alerts and the mermaid fence. One acknowledged limitation of this sample: it doesn't include math or diagrams, because both depend on the platform and neither belongs in a portable README.
Try the Markdown Example in the Editor
The same file is loaded below, minus the fenced code blocks and the footnote, to keep the demo short. Edit any line and watch the preview.
The Markdown to HTML converter shows the HTML behind each line. That's the quickest way to see why a table needs its separator row, or why a list item needs a blank line before a nested code block. If you'd rather start from a blank page, the same markdown example file is a reasonable template: delete the sections you don't need and keep the structure.
A Markdown Test File for Checking Any Renderer
Searches for a markdown test or test markdown file usually mean one thing. You're about to paste into a new tool and want to know what it supports. This short file answers that in one paste. Each line states its own expected result, so a glance at the preview tells you which features the renderer handles. Save it as markdown-test.md and keep it around.
# H1 renders as the largest heading
## H2 renders smaller
**Bold** and *italic* and ***both*** and `inline code`
~~Strikethrough~~ is GFM: literal tildes mean no GFM support
Line one with two trailing spaces
renders a line break above this text
- Bullet
- Nested bullet (two spaces of indent)
1. Numbered
1. Also numbered 2, auto-incremented
- [ ] Checkbox: a real checkbox means task lists are supported
| Table | Support |
|---|---|
| Renders as a grid | if pipe tables work |
> Quote block
Footnote[^t] with the definition below
[^t]: A superscript link means footnotes work
Escaped \*asterisks\* should show the asterisks
$E = mc^2$ renders as an equation only where math is enabled
When a line fails, the fix is usually one of three things. The renderer doesn't support the feature at all, as with tables in Slack. It needs a setting switched on, as with math in some note apps. Or the syntax differs slightly, as with nested lists in Reddit's older parser. The test file tells you which line failed; the platform's own formatting help tells you which of the three it is.
Two lines deserve a warning. The trailing-space line break is invisible in most editors, so if it fails, check whether your editor strips whitespace on save. And the math line is a deliberate outlier: on GitHub, Obsidian, and math-enabled editors such as ours it becomes an equation; in most other places it stays literal text with dollar signs.
How Do I Create a Markdown File?
A Markdown file is plain UTF-8 text saved with a .md or .markdown extension. RFC 7763, published in March 2016, registers the text/markdown media type and lists both extensions; .md is the one nearly everyone uses. There is no special format, header, or encoding declaration. Save it as UTF-8 so accented characters and emoji survive; the RFC notes that Markdown works on punctuation, not code points, which is why plain ASCII files also render fine.
- Open any text editor: VS Code, the browser editor here, or even Notepad.
- Paste the sample above, or start typing with a
#heading. - Save the file as
README.md(GitHub shows a file with that exact name on the repository's front page) or any other name ending in.md. - Preview it. In VS Code, press Ctrl+Shift+V; in the online editor, the preview is already open beside the source.
If you want a guided path through the syntax rather than a finished file, the Markdown tutorial builds a document step by step. We prefer to start from a working example and delete what you don't need; it's faster than assembling one from a reference.
Markdown Example FAQ
One complete example of Markdown teaches more than a dozen isolated snippets. You see how headings, lists, tables, code, and footnotes sit together in a real file. Copy the README sample, keep the test file for new tools, and paste either one into the editor to watch the source and the rendered page side by side.