README Preview
Push, look, fix, push again is a slow way to write a README. Paste yours here, or point at a repo, and see it rendered the way a reader will get it: badges, tables, collapsible sections, callouts and highlighted code.
Paste a repo URL and the browser fetches that repo’s README directly from GitHub, GitLab or Bitbucket. A link to a single .md file works too. Nothing is sent to our server, and private repos will not fetch, so paste their contents below instead.
Rendered
Starter sections
Append any of these to the markdown above and watch how it renders.
Whole README skeleton
The sections a reader looks for, in the order they look for them.
# project-name
One sentence on what this does and who it is for.
## Install
```bash
npm install project-name
```
## Usage
```js
import { thing } from 'project-name';
thing({ ready: true });
```
## Options
| Option | Type | Default | What it does |
| ------ | ---- | ------- | ------------ |
| `ready` | boolean | `false` | Starts the thing straight away. |
## Contributing
Issues and pull requests are welcome. Run `npm test` before opening one.
## Licence
MIT
Badge row
Put these on one line directly under the title, with no blank line between them.
[](https://www.npmjs.com/package/project-name) [](https://github.com/owner/repo/actions) [](./LICENSE)
Table of contents
Anchor links are the heading text, lowercased, spaces to hyphens, punctuation dropped.
## Contents - [Install](#install) - [Usage](#usage) - [Options](#options) - [Contributing](#contributing)
Collapsible section
For the long output nobody needs on first read. The blank line after <summary> matters.
<details> <summary>Full output</summary> ```text line one line two ``` </details>
Callouts
Rendered as coloured admonitions on GitHub and in this preview.
> [!NOTE] > Useful context that is not a warning. > [!WARNING] > This one people actually read.
What a good README answers
In order, because a reader leaves as soon as one of them is missing: what is this, who is it for, how do I install it, what does the smallest working example look like, what are the options, and how do I report a problem. Everything else is optional.
Things that surprise people
- Badges have to sit on consecutive lines with no blank line between them, or each one becomes its own paragraph and they stack vertically.
- A
<details>block needs a blank line after the<summary>, otherwise the markdown inside is not parsed as markdown. - Relative image and link paths resolve against the repo on the host, so they break in anything that renders the file outside it. Absolute URLs travel.
- Heading anchors are the heading text lowercased, spaces turned into hyphens, punctuation dropped. That is what a table of contents has to match.
- A table cell is a single line. No lists, no line breaks, no fenced code inside one.
Private repos
Fetching happens in your browser with no credentials, so a private repo returns nothing. Copy the file contents into the box instead. Same result, and the text still never leaves your machine.