Turn your GitHub contribution activity into an isometric pixel-art city, rendered as one small, deterministic SVG for profile READMEs and dashboards. Each day is a building; busy days grow into taller buildings.
Version note: this working tree is the 1.3.0 release candidate; the published release is 1.2.0. 1.3.0 changes the default building height (see Upgrading). Everything else keeps its defaults. CHANGELOG | Customization guide | Preview gallery
git clone https://github.com/partialHuman/contribution-city
cd contribution-city
python -m pip install -e ".[dev]" # tests, lint and the visual tools
# or, just the tool: python -m pip install -e .Python 3.10 or newer. The only runtime dependency is pyyaml; resvg-py and Pillow (the visual
extra, included in [dev]) are needed only for the visual regression tools.
# Offline, from the bundled sample data (default: standard heights, detailed buildings)
contribution-city generate --input examples/sample-contributions.json --output dist/city.svg
# Another look: theme, layout, solid buildings and a lower camera
contribution-city generate --input examples/sample-contributions.json \
--theme cyberpunk --layout downtown --building-style solid --view-angle low
# Live data from GitHub (needs a token with read access)
export GITHUB_TOKEN=ghp_xxx
contribution-city generate --username octocat --theme profile --year 2025Output directories are created automatically. Want to use it in your own repository? Follow the step-by-step customization guide; it has copy-paste workflows.
Every image below is a real SVG generated by the renderer from the same deterministic sample data
(see previews/; regenerate with contribution-city previews --readme README.md).
Click an image to open the SVG. Under each image is the flag that produced it.
Fourteen themes, default settings. Every theme is plain data, see
renderer/palettes.py. Light variants exist for
navy-cyan (navy-cyan-light) and profile (profile-light).
| Layout | What it does |
|---|---|
calendar (default) |
GitHub grid: columns are weeks, rows are weekdays |
compact |
Square block with one empty tile between buildings |
dense-grid |
Square block without gaps: the smallest footprint, good for small embeds |
downtown |
Busiest days in the centre (not in date order; tooltips keep the dates) |
floating-island |
Dense block on a thick slab with a tapering rock underside and a shadow |
wireframe |
Outlined schematic; hidden lines stay hidden |
Two different settings decide how tall the buildings are. Do not mix them up:
| Setting | Decides | Values | Default |
|---|---|---|---|
Height preset --height-preset |
The overall height profile: how tall the tallest building may get | standard, tall, custom |
standard |
Height mode --height-mode |
The curve: how a day's contribution count turns into a height inside that profile | power, linear, sqrt, log |
power |
Preset first, curve second. Standard keeps buildings proportionate (at most about three tiles
high); tall is the look of versions 1.0 to 1.2 (up to seven tiles); custom uses your own
--scale, --min-building-height and --max-building-height.
standard (default) --height-preset standard | tall --height-preset tall | custom: scale 1.5, max 90 --height-preset custom --scale 1.5 --max-building-height 90 |
power (default curve) --height-mode power | linear --height-mode linear | sqrt --height-mode sqrt | log --height-mode log |
power (default curve) --height-mode power | linear --height-mode linear | sqrt --height-mode sqrt | log --height-mode log |
| Mode | Height above the minimum |
|---|---|
power |
grows with count ** 0.78, so huge days do not dwarf the rest |
linear |
exactly proportional to the day's count (the busiest day reaches the preset maximum) |
sqrt |
proportional to the square root of the count |
log |
proportional to log(1 + count) |
--building-style detailed (default) draws windows and rooftop beacons. --building-style solid
draws plain boxes with three shades (roof, left wall, right wall): no windows, no antennas, no
outlines. It works with every theme, layout, preset and view.
detailed --building-style detailed | solid --building-style solid |
The camera elevation changes the projection: a lower camera flattens the ground and makes buildings
read taller, a higher camera shows more ground and shortens them. The default isometric view is
the classic 2:1 pixel projection of every earlier release.
--view-angle |
Elevation | Look |
|---|---|---|
isometric (default) |
30 deg | Classic pixel isometric |
low |
20 deg | Flatter ground, towers read taller |
high |
42 deg | More ground, buildings look shorter |
top-down |
58 deg | Steep, almost a plan view |
For anything in between use --view-elevation DEGREES (10 to 70; it overrides --view-angle).
The city is always scaled to fit the canvas, so no angle clips it.
isometric (30 deg) --view-angle isometric | low (20 deg) --view-angle low | high (42 deg) --view-angle high | top-down (58 deg) --view-angle top-down |
GitHub shows a transparent SVG on the page colour, so the transparent previews above sit on a
checkerboard (*.on-checkerboard.svg, preview only). The real files in previews/backgrounds/ stay
transparent.
--background |
Result |
|---|---|
solid |
The theme's gradient background and sky stars |
transparent |
No background rectangle and no stars: the page shows through |
transparent-sky |
No background rectangle, but the sky stars stay (they are tuned for dark pages) |
auto |
transparent-sky when --appearance auto is used (the SVG carries a light and a dark palette), otherwise solid |
Legacy flag. --transparent (config city.transparent) still works as in 1.1.0 and equals
--background transparent. If both are given, --background wins; a contradictory pair
(--transparent with --background solid) prints a warning.
contribution-city generate [options]
| Option | Meaning | Default |
|---|---|---|
-i, --input FILE / -u, --username NAME |
Offline JSON file, or live GitHub data | |
-t, --token TOKEN |
Token | GITHUB_TOKEN / GH_TOKEN |
-c, --config FILE |
YAML configuration file | |
-o, --output FILE |
Output SVG | dist/city.svg |
--theme NAME |
One of the 14 themes | navy-cyan |
--layout NAME |
calendar, compact, dense-grid, downtown, floating-island, wireframe |
calendar |
--height-preset |
standard, tall, custom |
standard (see the legacy rule below) |
--height-mode |
power, linear, sqrt, log |
power |
--scale X |
Multiplier for building heights, 0.1 to 5 | unset |
--min-building-height, --max-building-height |
Smallest / tallest building in unscaled pixels (0-40 / 8-400) | preset |
--building-style |
detailed, solid |
detailed |
--view-angle |
isometric, low, high, top-down |
isometric |
--view-elevation DEG |
Camera elevation 10 to 70, overrides --view-angle |
unset |
--background MODE |
solid, transparent, transparent-sky, auto |
solid |
--appearance fixed|auto |
Add the light palette (themes with a light variant) | fixed |
--width, --height |
Canvas size in pixels (100 to 10000) | 1200 x 680 |
--no-fit |
Keep the configured tile size instead of fitting the canvas | fit on |
--year YYYY (repeatable), --from DATE, --to DATE |
Limit the data (a year list and a date range cannot be combined) | all |
--retries N |
Retries for temporary GitHub failures | 2 |
--id-prefix NAME |
Prefix ids and CSS rules when inlining several SVGs in one page | none |
--no-tooltips, --smooth |
Smaller file, anti-aliased edges | tooltips on |
--no-windows, --no-stars, --no-header, --no-platform |
Hide those parts | shown |
--title TEXT |
Custom header title | |
--version, --help |
Print the version / the full help with examples | |
--transparent |
Legacy, see Backgrounds |
Other commands: previews, gallery, visual list|check|approve, check-svg. Exit status: 0
success, 1 error or failed check, 2 usage error (also visual approve without --yes).
Precedence: built-in defaults < configuration file < command-line options. Every key of the
configuration file is documented in examples/config/all-options.yaml.
The height rule for old configurations. If you set --scale, --min-building-height or
--max-building-height (or the same keys in YAML) without a --height-preset, the preset is
custom, which is the 1.2.0 look. Your explicit numbers are never reinterpreted. With an explicit
preset, --scale simply scales that preset.
- uses: partialHuman/contribution-city@v1
with:
username: ${{ github.repository_owner }}
token: ${{ secrets.GITHUB_TOKEN }}
theme: cyberpunk
layout: dense-grid
building-style: solid
view-angle: high
background: transparent
output: dist/city.svg| Input | Default | Accepted values |
|---|---|---|
username |
repository owner | GitHub user |
token |
github.token |
token; a personal access token with read:user also counts private activity |
theme |
navy-cyan |
any of the 14 themes |
layout |
calendar |
calendar, compact, dense-grid, downtown, floating-island, wireframe |
height-preset |
empty = standard |
standard, tall, custom |
height-mode |
power |
power, linear, sqrt, log |
scale |
empty | 0.1 to 5 |
min-building-height, max-building-height |
empty | 0-40, 8-400 |
building-style |
detailed |
detailed, solid |
view-angle |
isometric |
isometric, low, high, top-down |
view-elevation |
empty | 10 to 70 degrees (overrides view-angle) |
background |
empty = solid |
solid, transparent, transparent-sky, auto |
transparent |
false |
legacy; ignored when background is set |
appearance |
fixed |
fixed, auto |
width, height |
empty = 1200 x 680 | 100 to 10000 |
auto-fit, tooltips |
true |
true, false |
years, from, to |
empty | 2024,2025, YYYY-MM-DD |
retries |
2 |
0 to 10 |
id-prefix, config, input |
empty | prefix, YAML path, JSON path (offline) |
output |
dist/city.svg |
path; parent folders are created |
Output: svg-path, the path of the generated file. The action checks layout, appearance,
background, height-mode, height-preset, building-style and view-angle before doing any work.
Ready-to-adapt workflows (all third-party actions pinned to commit SHAs) are in
examples/workflows/, explained step by step in the
customization guide.
Security: inputs reach the script only as environment variables (never pasted into shell text), the token is never put on a command line or printed.
contribution-city previews --readme README.md # the browsable previews/ folder and the grids above
contribution-city previews --check --readme README.md # fail if previews or grids are out of date
contribution-city gallery --output-dir gallery # PNG contact sheet and manifest of all test cases
contribution-city visual check # compare with approved baselines (never writes them)
contribution-city visual approve --yes --case theme-cyberpunk # explicit, after reviewingThe guide for tolerances, failure artifacts and adding themes is docs/visual-testing.md.
Every generated SVG is checked (contribution-city check-svg, and the test suite) for well-formed
XML, unique ids, resolving references, no external resources (http(s), @import, <image>,
<use>, <foreignObject>), no scripts or event handlers, a viewBox equal to width/height, and
role="img" with a <title> and <desc>. All user-controlled text is escaped. This is a technical
check, not an accessibility audit.
examples/sample-contributions.json shows the format. The loader also accepts the raw GitHub GraphQL
response and a flat list of { "date", "count" } objects. Private activity is read from
restrictedContributionsCount and shown in the header.
What changes for you
- The default building height is lower. New default:
--height-preset standard. To get exactly the old look, add--height-preset tall(action inputheight-preset: tall, YAMLcity.height_preset: tall). SVGs are otherwise byte-identical for the same options (tested). - Configurations that set
building_scale,min_building_heightormax_building_heightkeep their old look (they become presetcustom). Nothing you set explicitly is reinterpreted. - The city now always fits on very small canvases (before, below about 50 % scale it could overflow).
What is new: height-preset, building-style, view-angle, view-elevation,
min-building-height, max-building-height, the previews command, the preview gallery and the
examples folder. Defaults of all other options, the theme names, the layout names, the height modes
and the background behaviour are unchanged.
appearance=autoexists fornavy-cyanandprofileonly.- The camera presets change the elevation of a symmetric projection. An oblique projection (a camera that is not at 45 degrees to the grid) is not implemented.
downtownis not chronological.- On a transparent background,
wireframefills faces with the theme's lower background colour to hide lines behind them; choose a theme close to your page colour. --no-fitwith a steep or low angle can leave the city outside the canvas; the default fit cannot.- The preview SVGs use the dark
solid/transparentthemes; light-page rendering is covered by the*-lightthemes. Browser handling ofprefers-color-schemeinside<img>was not tested. - Visual baselines come from one renderer (resvg 0.5.x) and are compared on Linux in CI.
python -m pip install -e ".[dev]"
pytest # everything
pytest -m "not baseline" # without the pixel comparison
ruff check . && ruff format --check .
pip wheel . --no-deps -w wheelhouse # package build
contribution-city previews --check --readme README.mdMIT, see LICENSE.