Guide · GitHub

How to make a GitHub Profile README (full guide)

GitHub has a 'secret' feature: create a public repo named the same as your username, add a README.md, and GitHub renders it at the top of your profile. Here is the full how-to, plus how to make it look great with animated cards.

Open the builder →API docs

The special repo

On github.com, click "New repository". Name it *exactly* the same as your username — for example, if your username is `yerdaulet-damir`, name the repo `yerdaulet-damir`. Make it public. Check "Add a README file". GitHub will detect the name match and show a "✨ Special!" hint. The README.md in this repo renders above your pinned repositories on your profile page.

What markdown GitHub allows

GitHub supports the GitHub Flavored Markdown spec. You get headings, lists, tables, links, inline images, blockquotes, and code fences. You also get a *subset* of HTML — `<img>`, `<a>`, `<details>`, `<summary>`, `<sub>`, `<sup>`, `<div align>`, `<picture>` — which is the trick that lets us embed live cards. Scripts and most CSS are stripped. But external image URLs are fully fetched and rendered.

Embedding a coolreadme card

Every coolreadme endpoint returns either PNG or SVG with an `Content-Type` GitHub trusts. Drop in one line: `![cinematic](https://coolreadme.xyz/api/cinematic?user=yourname&status=SHIPPING&focus=ML)`. That is it. GitHub fetches the image, caches it via Camo, and shows it inline. For wider control use `<img src="..." width="100%" />`.

Animated cards on GitHub

SVG cards can include `<animate>` elements and CSS `@keyframes` — both supported by GitHub's image proxy. Our pet streak cards (cat, dog, fox, penguin, owl) animate continuously: idle bounces, particle effects, stage transitions. None of this requires JavaScript, so GitHub renders it natively.

Camo caching gotcha

GitHub caches images through camo.githubusercontent.com. If you change a query param and the URL is identical, Camo serves the old cache. Bust it with an unused param like `&v=2`. Our edge layer also caches for 2 hours — fine for production, occasionally annoying for iteration.

Step by step

  1. 01

    Create the username repo

    Public repo on github.com with the exact same name as your username. Initialize with a README.

  2. 02

    Open README.md in the editor

    Edit directly in the browser or clone locally — either works.

  3. 03

    Paste a coolreadme image tag

    For example: ![](https://coolreadme.xyz/api/cinematic?user=yourname&status=SHIPPING).

  4. 04

    Commit

    Commit the change. Your profile page now renders the README with live animated cards.

Open the builder →

More guides

Claude CodeCursorVercelLinkedIn