README Generator
Pick the sections a project README needs, order them with the keyboard, and copy the Markdown — entirely on this device.
Section library
These 15 templates are fixed text. Nothing is fetched or written for you — edit the Markdown after you copy it.
Document outline
Sections appear in this order. Move them with the ↑ and ↓ buttons.
- Title
- Installation
- Usage
- License
Custom sections are not listed in the table of contents.
Fields
Characters with Markdown meaning are escaped in the output, and a fence widens around a backtick run.
Used as the H1 heading and in the install command.
http, https or mailto only — anything else is refused.
Empty fields stay as {{field}} markers in the output.
The rendered preview appears here as you build the document.
The preview never loads an image: remote images become `[image: alt]` and local paths show their alt text. Nothing leaves this tab.
The preview is sanitized HTML rendered on this device.
Press ? for shortcuts
Do it offline:$
How to use it
- Add sections from the library: 15 built-in templates, plus up to three custom ones carrying your own heading and text.
- Order the document with the move-up and move-down buttons on each outline row. Every move is announced, and dragging is never required.
- Fill the fields once — a value is substituted into every section that uses it, and the package-manager choice rewrites the install, run and test commands.
- Copy the Markdown, download it as README.md, or share the permalink. When a document is too large for a URL, the state file is the way to carry it.
A project README answers four things for a stranger: what this is, how to install it, how to run it, and what the licence says. Choose those sections from the library, order them with the keyboard, fill the fields once, and the Markdown is composed here in the page. The 15 templates are fixed text meant to be edited afterwards, and nothing is uploaded.
Examples
Sections: Title, Badges, Installation, Usage, License — pnpm# orbit-cli
Ship release notes from your terminal
[](https://www.npmjs.com/package/orbit-cli)
[](https://github.com/acme/orbit-cli)
[](https://github.com/acme/orbit-cli)
## Installation
Install orbit-cli with pnpm:
```sh
pnpm add orbit-cli
```
## Usage
Run the orbit script:
```sh
pnpm orbit
```
## License
MIT © Acme. See [LICENSE](LICENSE) for the full text.
Choosing pnpm rewrites the install line to pnpm add and the run line to pnpm orbit; npm, Yarn and Bun swap the same two blocks. This exact document is what the Sample button loads and what a shared permalink rebuilds.
Project name pasted with emphasis markers and a backtick run# my\_tool \*\*\*alpha\*\*\* \`\`\`v3\`\`\`
Snapshot testing for the terminal
## Installation
Install my\_tool \*\*\*alpha\*\*\* \`\`\`v3\`\`\` with npm:
````sh
npm install my_tool ***alpha*** ```v3```
````
## License
MIT © Ada Lovelace. See [LICENSE](LICENSE) for the full text.
Nothing validates a name, so a pasted value is escaped for wherever it lands: backslashes in the heading and the sentence, the original bytes inside the shell block, and the fence itself grown to four backticks so the block still closes.
Sections: Title, Badges, Screenshots, License — preview placeholders# orbit-cli
Ship release notes from your terminal
[](https://www.npmjs.com/package/orbit-cli)
[](https://github.com/acme/orbit-cli)
[](https://github.com/acme/orbit-cli)
## Screenshots
## License
MIT © Acme. See [LICENSE](LICENSE) for the full text.
Three shields.io addresses reach the file untouched, and each one becomes a bracketed label in the preview instead of a request to another host. The screenshot path is relative, so the copied file keeps it as written; the preview removes its source attribute too, so nothing is requested and the alt text shows instead.
Sections: Title, Table of contents, Installation, custom, License# orbit-cli
Ship release notes from your terminal
## Table of contents
- [Installation](#installation)
- [License](#license)
## Installation
Install orbit-cli with npm:
```sh
npm install orbit-cli
```
## Deploy notes
Run the release job from `main` only.
## License
MIT © Acme. See [LICENSE](LICENSE) for the full text.
Deploy notes holds its place between Installation and License in the file and stays out of the list above it. The frozen headings have anchors known in advance; a heading you invent does not, and this page will not guess one.
Every example on this page is executed against the same engine that powers the tool, on every build.
Gotchas worth knowing
An empty field stays visible
A field left blank keeps its double-braced marker in the document and raises a warning naming it. A quiet blank would ship a hole nobody notices.
Custom headings are not linked
Only the frozen headings reach the contents list, because only their anchors are known before composition. A custom section keeps its position in the file regardless.
A backtick run widens the fence
Three backticks inside a value would close a shell block early, so the fence around it grows to four. The block survives whatever you typed.
Three URL schemes, nothing else
Repository and homepage values must begin http:, https: or mailto:. Anything else is refused by name rather than written into a link somebody will click.
The licence string is copied, not checked
Whatever you type is written beside the copyright holder as spelled. No list is consulted, so an in-house licence name survives intact.
CR LF becomes LF
Text pasted from a Windows editor is normalized and a note says so, which keeps a composed document identical whatever machine its pieces came from.
Ceilings refuse, they never trim
2,000 characters per field, 8,000 per custom body, 100,000 for the document, three custom sections. Each refusal prints your number beside the limit.
An empty document is not a mistake
With no sections chosen the output is empty and nothing is flagged. Warnings start once there is a document to be wrong about.
Common errors
The repoUrl field starts with "javascript:", which is not a link scheme this page will write into a README — use an http:, https: or mailto: URL.- Link destinations are built from your fields, so a scheme that executes instead of navigating is refused before anything is composed, and the rejected prefix is quoted back to you.
Section "usage" appears twice in the order, at positions 2 and 3 of 3 — each section can only appear once; remove one of them.- A template can appear once. Two copies would share a heading, and the second would collect a different anchor, so a contents link could land on the wrong one. Both positions are named.
The projectName field is 2,001 characters, over the limit of 2,000 — shorten it, or move the long text into a custom section.- One character past the ceiling stops the build and prints both numbers. Long prose belongs in a custom section, which carries a larger allowance of its own.
Custom section 1 ("Deploy notes") is 8,001 characters, over the limit of 8,000 — shorten it, or split it across two custom sections.- The offender is quoted by position and by heading so it is findable in a long outline. Splitting is the way through, up to the ceiling of three custom sections.
This document has 4 custom sections, over the limit of 3 — remove one before adding another.- Three is the whole-document ceiling. Past it the composer stops instead of dropping the fourth section somewhere you would not notice it missing.
FAQ
Does this write the README for me?
No. It fits fixed template text around the values you type — headings, shell blocks, an option table, and the links those fields feed. Nothing about your code is read, fetched or inferred, and the wording is a starting point you are expected to rewrite.
Why are the badges placeholders in the preview?
Rendering one would mean calling another host from this page. Every remote image destination is swapped for a bracketed label before the preview is built, so what you see is drawn on this device while the copied Markdown keeps the real addresses.
Can I rename or reword a built-in section?
Not in the tool. Headings and bodies stay frozen so their anchors are predictable and the contents list can be composed without guessing. Reword freely after you copy — or put your own wording into a custom section now.
Keyboard shortcuts
- ⌘/Ctrl + C
- Copy the Markdown while nothing is selected.
- ⌘/Ctrl + Shift + C
- Copy the Markdown even over a selection.
- ⌘/Ctrl + S
- Download the document as README.md.
- t
- Change the theme.
- ? or ⌘/Ctrl + /
- Open the shortcut help dialog.
- Esc
- Close the topmost overlay.