How do I add an ASCII art portrait to my GitHub profile README?

Generate portrait.svg here, upload it to the assets/ folder of your profile repository (username/username), then add to README.md and commit.

Why not paste the code straight into the README?

GitHub strips inline from Markdown. The SVG must be a file loaded with , where only SMIL animation runs, so the typing effect is built with SMIL.

Is my photo uploaded anywhere?

No. The conversion runs entirely in your browser canvas. Only a GitHub username lookup calls the GitHub API to fetch the public avatar.

ASCII Portrait for GitHub Profile README

~/gallery $ ls *.svg

Classics, Anime, Space. 6,820 Characters Each.

Every card below is a real output of this page, rendered from public-domain works and original illustrations. Each one is a single SVG file that plays inside a GitHub README.

Mona Lisa as a colour ASCII portrait — Mona Lisa · Leonardo da Vinci

Girl with a Pearl Earring as a colour ASCII portrait — Girl with a Pearl Earring · Johannes Vermeer

Self-Portrait as a colour ASCII portrait — Self-Portrait · Vincent van Gogh

Abraham Lincoln as a colour ASCII portrait — Abraham Lincoln · Alexander Gardner

Albert Einstein as a colour ASCII portrait — Albert Einstein · Ferdinand Schmutzer

The Great Wave off Kanagawa as a colour ASCII portrait — The Great Wave off Kanagawa · Katsushika Hokusai

Silver-haired developer as a colour ASCII portrait — Silver-haired developer · original illustration

Night coder as a colour ASCII portrait — Night coder · original illustration

Rooftop coder as a colour ASCII portrait — Rooftop coder · original illustration

Earthrise as a colour ASCII portrait — Earthrise · William Anders / NASA

The Blue Marble as a colour ASCII portrait — The Blue Marble · Apollo 17 crew / NASA

Pillars of Creation as a colour ASCII portrait — Pillars of Creation · NASA, ESA, Hubble

The Tetons and the Snake River as a colour ASCII portrait — The Tetons and the Snake River · Ansel Adams

~/studio $ ./portrait.sh --live

The Studio.

Drag the frame on the source image, pick a contrast mode and watch every stage of the pipeline update.

Source 1.0

—

Drag the frame · scroll or +/− to zoom · arrow keys move it.

Options 1.1

Cells Columns110

Contrast

Global Local Off

Zoom1

Colour Brightness1.6 Saturation1.3

Terminal

Window title whoami

Animation Entrance style Seconds per line0.07

portrait.svg — Preview

example

— Download .svg

Pipeline

—

1 crop—

2 lumaITU-R 601

3 contrastequalize

4 cells110×62

README.md

49% · beside a card 100% · alone

Add a tiny "made with" link

Upload the file to assets/portrait.svg in username/username.
Paste the code into README.md.
Commit. It types itself out on your profile.

Hand it to an AI coding agent

~/src $ npm test

Built Like Software, Not A Filter.

Pillow parity

The JavaScript port reproduces the reference Python/Pillow script cell for cell: 6,820 of 6,820 characters and colours, and a byte-identical SVG. Local contrast matches OpenCV's CLAHE on 99.98% of pixels.

Works inside <img>

GitHub strips inline SVG and blocks scripts and fonts in README images. The typing is pure SMIL, and every line is pinned with textLength so macOS, Windows and Linux line up.

Never blank

Rows are visible by default and the delay lives in keyTimes. Email previews, social cards and screenshots always show the full portrait.

100%cell match with the reference

~145 KBdefault file, 110×62 cells

0image bytes sent anywhere

MITopen source, no tracking

~ $ man readme_portrait

Questions, Answered.

Why not paste the <svg> straight into the README?

GitHub strips inline SVG from Markdown. It has to be a file loaded with <img>, where scripts and web fonts are blocked and only SMIL animation runs.

Is my photo uploaded?

No. Pixels are read and converted in your browser. The only network call is the GitHub API lookup when you type a username.

Global or local contrast?

Global equalisation gives bold silhouettes. Local (CLAHE) keeps detail inside faces when the background is bright or busy. Try both on your image; the pipeline window shows the difference.

It looks blank in an email preview.

It should not: every line is visible by default and the animation only hides lines briefly while it plays. Turn the animation off for a fully static file.

Where do the example images come from?

Public-domain works from Wikimedia Commons. Sources are listed in CREDITS.md.

MAKE YOUR PORTRAIT

Or start from an example