A good README is a book cover. If it's boring, nobody opens the project. This guide gathers proven techniques that make READMEs professional and eye-catching.
| Technique | What it Does | Example |
|---|---|---|
| Centered header | <div align="center"> — logo + title centered, creates a "cover" |
⏳ LifeLine / 🔍 xyzz.me |
| Shields.io badges | Bright colored badges with status, license, tech stack |  |
| Emoji section headers | Visual navigation — eyes catch icons instantly | 💡 Concept · ✨ Features · 🚀 Quick Start |
| Tagline | One bold line under the title — project essence in 1 sentence | "See your entire life on paper" |
| Preview image | Instantly shows what the product looks like | <img src="preview.png" width="600"> |
| Feature tables | Structured feature list, easy to scan | Feature | Description |
| Collapsible sections | <details> — hides secondary info (env vars, build, lectures) |
Keeps README uncluttered |
| Blockquote | > — project philosophy / concept, visually stands out |
"Lines and structures are a language..." |
| Horizontal dividers | --- between sections — clear visual separation |
|
| ASCII tree structure | Instant architecture overview in code | client/ ├── pages/ |
| Inline navigation | Anchor links under header — quick access to sections | Quick Start · Features · Docs |
| Animated GIF / video | Demo in action beats a screenshot — shows the flow |  |
| Contributing section | Attracts contributors, sets standards: fork → branch → PR | Fork → feature/name → PR |
| Roadmap | Shows the project is alive and evolving | - [ ] Feature A - [x] Feature B |
| GitHub Alerts | > [!NOTE] / > [!WARNING] — colored blocks instead of plain quotes |
Supported since 2023, rendered on GitHub |
| Table of Contents | Section navigation for long READMEs (or inline links) | For READMEs > 5 sections |
| No © sign | Don't use the copyright symbol — cleaner and more modern. Author name always links to LinkedIn | [Maxim Osovsky](https://linkedin.com/in/osovsky). Licensed under CC BY-SA 4.0. |
| llms.txt files | Machine-readable project summary for LLMs — llms.txt (short) + llms-full.txt (detailed) |
llms.txt standard |
| CI link checker | GitHub Actions workflow that auto-checks for dead links and markdown errors on every push | Free, runs on GitHub servers |
| GitHub About | Description + URL + Topics in repo About (⚙️) — improves discoverability and first impression | Description = tagline, Topics = react, miro-sdk etc. |
- Wall of text without formatting — nobody reads unformatted prose
- No image/preview — unclear what the project looks like
- Too-long README without
<details>for secondary sections - No badges — looks like an unfinished project
- No Quick Start — people leave if they can't figure out how to run it
- Technical docs in README — move to ARCHITECTURE.md, MANUAL.md
- Hardcoded secrets in examples — even
sk_test_...alarms reviewers - No license — legally unclear whether the code can be used
- Dead links — broken links to demo/docs kill trust, verify before pushing
- © sign — don't use it, just name + license looks cleaner
- No llms.txt — LLMs can't discover or understand the project without machine-readable docs
- No CI checks — dead links and broken badges go unnoticed until someone reports them
- Empty About section — no description, no URL, no topics. Repo looks abandoned and won't appear in search
Optional but recommended. Add one file to your repo and GitHub will check every README on push — free, no servers needed.
📋 Ready-to-use workflow (click to expand)
Create .github/workflows/readme-lint.yml:
name: README Lint
on: [push, pull_request]
jobs:
links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lycheeverse/lychee-action@v1
with:
args: --verbose *.md
markdown:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DavidAnson/markdownlint-cli2-action@v16
with:
globs: "*.md"What it checks:
- 🔗 Dead links (URLs returning 404)
- 🏷️ Broken badge images
- 📝 Markdown syntax errors
- ✅ Result: green checkmark or red X on your repo page
Cost: $0 for public repos, 2 000 free minutes/month for private.
1. Centered header + logo
2. Badges (status, license, stack)
3. Tagline (1 line)
4. Inline navigation (Quick Start · Features · Docs)
5. Preview screenshot / GIF
---
6. 💡 Concept (blockquote + explanation)
---
7. ✨ Features (table)
---
8. 🚀 Quick Start (3 lines of code)
<details> Advanced setup </details>
<details> Environment variables </details>
---
9. 🏗️ Tech Stack (table + file tree)
---
10. 🗺️ Roadmap (task checklist)
---
11. 🤝 Contributing (fork → branch → PR)
---
12. 📄 License + author
13. llms.txt + llms-full.txt (root, plain text)
14. GitHub About (⚙️): Description = tagline, Website = demo URL, Topics = keywords
| Resource | Description |
|---|---|
| shields.io | Badge generator |
| Simple Icons | Logos for badges |
| readme.so | Visual README builder |
| GitHub Docs: Formatting | Official documentation |
| GitHub Alerts | [!NOTE], [!WARNING] etc. |
| Badgen | shields.io alternative |
| Contributor Covenant | Code of Conduct standard |
| llms.txt | Standard for LLM-readable project docs |
Start here — copy, rename to
README.md, fill in the{PLACEHOLDERS}.
| Template | Best for | Sections |
|---|---|---|
| ➡️ TEMPLATE.md | Full projects | 12 sections — badges, features table, tech stack, file tree |
| ➡️ TEMPLATE-minimal.md | Scripts, games, prototypes | 4 sections — badges, features, quick start, license |
Projects built with these guidelines:
| Project | What it is | README |
|---|---|---|
| WallPlan | Multi-year wall calendar generator | View |
| LifeLine | Lifetime visualization on paper | View |
| DelayedPopup | Chat-like popup with Stripe payments | View |
| TeleInviter | Telegram meeting scheduler bot | View |
| WallPlan Miro | Gantt calendar generator for Miro boards | View |
| File | Purpose |
|---|---|
| llms.txt | Short project card for LLM discovery |
| llms-full.txt | Complete guidelines as LLM instruction |
| README_GUIDELINES.md | Structured rules for AI-assisted README generation |
| PROMPTS.md | Ready-to-use prompts: generate, audit, improve |
README audit for all repositories →
Fork → feature/name → PR
Add your discoveries to the techniques table!
Maxim Osovsky. Licensed under CC BY-SA 4.0.