github-readme

# A GitHub README that looks good and keeps working A README is read top to bottom by someone deciding in ten seconds whether the project is for them. Design serves that: it makes the important things easy to find, it never hides them. Everything here is rendered by GitHub itself, so it works in both themes, on mobile and years from now. ## Order of the page Keep the first screen for these, in this order; decoration goes around them, never above them: 1. Name and one sentence: what it is, for whom. 2. A screenshot, GIF or diagram that shows it working (if it has anything to show). 3. Install: one copy-pasteable block. 4. Use: the smallest real example. Then the rest (features, configuration, results, FAQ, contributing, license). When redesigning an existing README, keep every fact in it: move, trim repetition, never drop install steps, commands or links. ## What GitHub renders (and what it strips) GitHub sanitizes README HTML: no `<style>`, `style=""`, `class`, scripts, iframes or custom fonts/colors. What survives is the toolbox: | Need | Use | |---|---| | Centered header, logo | `<p align="center">` / `<div align="center">` with `<img>` and `<h1>` | | Panels, feature grid, comparison | Markdown tables; an HTML `<table>` only for a grid of images | | Callouts | `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`; one or two per page | | Long optional content | `<details><summary>…</summary>` (blank line after `<summary>` so Markdown inside renders) | | Diagrams | Mermaid in a ```` ```mermaid ```` block: `flowchart`, `sequenceDiagram`, `stateDiagram-v2`, `gitGraph`, `timeline` | | Charts | Mermaid `pie`, `xychart-beta` (bar/line), or a generated SVG (below) | | Formulas | `$…$`, `$$…$$` | | Keys, small print | `<kbd>Ctrl</kbd>`, `<sub>`, `<sup>` | | Image per theme | `<picture>` with `prefers-color-scheme` (below) | Mermaid follows the viewer's theme by itself; don't hardcode colors in it unless they read on both white and dark backgrounds. ## Charts from real data Data comes from a file in the repo (CSV, JSON, benchmark output), never typed from memory. Show the numbers you have, label units, start bar axes at zero. - **Few values, simple chart** (≤ ~12 bars or points): Mermaid `xychart-beta`. Renders natively, diffs as text, follows the theme. ```mermaid xychart-beta title "Checks passed, %" x-axis ["omarchy-plugin", "parallel-worktrees", "herdr-tabs"] y-axis "%" 0 --> 100 bar [100, 100, 100] bar [64, 55, 43] ``` Several `bar` series are drawn over each other, not side by side: put the larger series first, and since Mermaid has no legend, say in the title or a line below which bar is which. - **More than Mermaid can show** (grouped bars with a legend, many series, annotations): an SVG generated by a script that lives in the repo, committed in a light and a dark variant, shown with `<picture>`. Rerun the script when the data changes; mention the command next to the chart (in a comment or `<details>`). Light/dark image: ```html <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/chart-dark.svg"> <img alt="Checks passed with and without each skill: 100% vs 64%, 55%, 43%" src="docs/chart-light.svg"> </picture> ``` The `<img>` is the light/fallback one and carries the alt text; alt states the takeaway, not "chart". ## Images and screenshots - Relative paths to files in the repo (`docs/`, `.github/assets/`), not hotlinks to other sites. - Every image has alt text. Set `width` on large ones; GIFs short (under ~5 MB). - Transparent PNG/SVG with dark lines vanishes on the dark theme: give it a background, or ship a dark variant through `<picture>`. ## Badges A badge is a fact a visitor wants at a glance: license, latest release, CI status, package version, maybe downloads. Use shields.io or the CI's own badge URL, one row under the title, at most ~5. Only badges that reflect the real state of this repo: no CI badge without a workflow, no release badge before the first release (`git tag`, `gh release list`), no "coverage" without a coverage report, no Go Report Card / pkg.go.dev for a module nobody indexed. A badge that would read "none" or "unknown" today waits until it has something to show. ## Avoid - Live third-party widgets: github-readme-stats, visitor counters, "typing" SVGs, streak cards. They rate-limit, go down and show broken images. If the user asks for one, add it and say that tradeoff once. - Emoji on every heading, walls of badges, ASCII art headers, text inside images (except designed cards, below, which carry their text in alt). - A hand-written table of contents in a short README: GitHub shows an outline button. Worth it only for long pages. - Colors or layout that need CSS in the README: it will be stripped (render it into an image instead, below). ## Designed cards (when the user wants a styled look) Fonts, colors, borders and layout GitHub would strip can be rendered into images. Use this for a few hero elements (project cards, a header), not for text a reader needs to copy: - One HTML template in the repo (`assets/src/cards.html`), one `<template>` per card, light and dark palettes as CSS variables, picked by a query parameter. - A script next to it renders each card in both themes at 2x with a transparent background, for example `chromium --headless --force-device-scale-factor=2 --default-background-color=00000000 --window-size=772,204 --screenshot=../<card>-<theme>.png "file://$PWD/cards.html?c=<card>&t=<theme>"`. Look at the PNGs before using them. - Each card goes in `<picture>` with an alt that holds all its text; a comment in the README names the script to rerun when a card's text or numbers change. - Expandable: put the `<picture>` in a `<details>`'s `<summary>`, the details (commands, links) in the body as normal text. Clickable instead: wrap it in `<a>`. ## Check the rendering before saying done 1. Every relative link and image path exists: `git ls-files` them. 2. HTML and Markdown structure: render through GitHub's API and look at the result: `gh api markdown -f mode=gfm -f context=<owner>/<repo> -F text=@README.md > /tmp/readme.html` Alerts, `align` and tables come back rendered; stripped `style`/`class` show up as missing. Mermaid comes back unrendered (the browser draws it), so a syntax error only shows on the page: step 3. 3. Mermaid and the page as a whole: with the user's OK, push to a branch and open `https://github.com/<owner>/<repo>/blob/<branch>/README.md`, in light and dark theme. Without a push, at least validate Mermaid locally if `mmdc` (`@mermaid-js/mermaid-cli`) is available. Say in the reply what was verified and what was not.