GitHub repo description and topics: how to write them
The one-line description and the topics are the only parts of your repo that show up in GitHub search results, topic pages and link previews. They take two minutes to fix and most repos get them wrong.
The description (120 characters or fewer)
GitHub's description field is short, and search results truncate it, so lead with the useful words. Use the same sentence that sits under your README title. Say what the thing does and for whom, in plain words.
| Weak | Better |
|---|---|
| My awesome project | Query JSON and CSV files from the command line using plain SQL |
| A Python library | Parse and validate cron expressions in Python, with human-readable output |
| Dotfiles | My zsh, tmux and neovim config, with an install script for macOS and Ubuntu |
Topics: pick 6 to 10
- Language or runtime: python, typescript, rust.
- What it is: cli, library, framework, api-client, dotfiles.
- The problem area: sql, json, markdown, scheduling.
- Ecosystem: the platform it runs on or plugs into, such as docker, vscode-extension or home-assistant.
Topics are lowercase, can contain hyphens, and are limited to 50 characters each. GitHub allows up to 20 per repo, but a short list of accurate ones beats a long list of loosely related ones. Look at the topic pages of similar projects and reuse the names they use; a topic nobody else uses won't help anyone find you.
Do's and don'ts
- Do put the website or docs URL in the repo's website field.
- Do keep the description in sync with the README tagline.
- Don't stuff the description with keywords, emoji or badges.
- Don't tag a topic you don't actually support.
Not sure your README says the same thing? Run it through the free README checker, and see the full checklist. README Rescue writes the description and topics for you as part of a $5 AI-written README rewrite.