How to write a README in Markdown

A README is the first file someone reads about a project, written in Markdown and named README.md, with a title, a one-line description, an install section, a usage section, and a license line. That covers almost every README worth reading. Add or drop sections as the project needs them.

The job of a README is narrow. Tell a stranger what this is, how to run it, and what they're allowed to do with it. Most of the file is plain prose with a few headings and one or two code blocks for commands.

The sections most READMEs have

A README is read top to bottom, so the order is the structure. Lead with what the project is, then how to get it running, then the rules.

A title: the project name as an H1.
A one-line description under the title, saying what it does and who it's for.
An install section with the commands to get it on someone's machine.
A usage section: the smallest example that proves it works.
A license line naming the license.

Bigger projects add Configuration, Contributing, or a Changelog. A weekend script needs none of those. Start with the five. Stop when the file answers the questions a new reader would actually ask.

A copyable skeleton

Here's a full README you can paste and fill in. Swap the names, keep the shape.

# Tilemap
 
A command-line tool that turns a folder of images into a single sprite sheet.
For game developers who'd rather not open a graphics editor.
 
## Install
 
```bash
npm install -g tilemap
```
 
## Usage
 
Point it at a folder and name the output:
 
```bash
tilemap ./sprites --out sheet.png
```
 
Options:
 
- `--out`: the file to write (default `tilemap.png`)
- `--padding`: pixels between tiles (default `2`)
- `--power-of-two`: pad the sheet to the nearest power of two
 
## License
 
MIT. See [LICENSE](LICENSE).

The triple-backtick fences mark the code blocks. The bash label on the opening fence tells a reader the lines are shell commands. The license line links to a LICENSE file sitting next to the README, which is where the full license text belongs.

A note on badges

Most READMEs you've seen on GitHub open with a row of badges: build status, version, downloads. A badge is an image. The Markdown for one is the standard image syntax pointing at a service that draws the badge on the fly:

![Build](https://img.shields.io/github/actions/workflow/status/you/tilemap/ci.yml)

Write the alt text in the brackets so the line still says something when the image itself doesn't load.

Write it, then read it back

Write the README in Write mode, the clean source editor. The syntax dims as you type and reveals at the cursor, so you see the raw # and backticks where you're working and rendered-looking text everywhere else. The + Insert menu drops in a heading, a list, or a fenced code block without you typing the marks by hand, and smart list continuation keeps a bullet list going each time you press Enter.

Then press ⌘E to switch to Read mode and check the result. Headings become real headings. The install block becomes a code box with a bash label and a copy button. The options list renders as bullets, and the license link is clickable. This is the view your reader gets, so it's the one to proofread against.

Badges are the one thing that renders differently than on GitHub. A badge is a remote image, an ![alt](https://…) pointing at the web, and Unmarked has no network access by design. Where each badge would sit, Read mode shows the alt text you wrote in the brackets, which is exactly why that alt text is worth writing well. Everything else renders. A local image, like a screenshot saved next to the file and linked as ![Demo](docs/demo.png), shows as the picture. The file stays useful in Unmarked and looks complete the moment it lands on GitHub.

The outline sidebar lists your H2 sections as you add them, which doubles as a quick check that the README has the parts a reader expects. When the file is ready, the word count in the status bar tells you if it's grown past what a README should be. A README that needs scrolling for ten minutes is usually two documents.