Skip to content

About

Generate customizable pixel-art contribution cities with a Python CLI and reusable GitHub Action. Create GitHub repository

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Contribution City

Tests License: MIT Python 3.10+

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.

A floating-island city in the default theme

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

Install

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.

Quick start

# 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 2025

Output directories are created automatically. Want to use it in your own repository? Follow the step-by-step customization guide; it has copy-paste workflows.

Preview gallery

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.

1. Themes

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).

navy-cyan
navy-cyan
--theme navy-cyan
matrix-green
matrix-green
--theme matrix-green
sunset-neon
sunset-neon
--theme sunset-neon
monochrome-slate
monochrome-slate
--theme monochrome-slate
solar-amber
solar-amber
--theme solar-amber
profile
profile
--theme profile
profile-light
profile-light
--theme profile-light
navy-cyan-light
navy-cyan-light
--theme navy-cyan-light
neon-harbor
neon-harbor
--theme neon-harbor
cyberpunk
cyberpunk
--theme cyberpunk
emerald-matrix
emerald-matrix
--theme emerald-matrix
copper-forge
copper-forge
--theme copper-forge
arctic-glass
arctic-glass
--theme arctic-glass
sunset-grid
sunset-grid
--theme sunset-grid

2. Layouts

calendar
calendar
--layout calendar

same file as themes/navy-cyan.svg
compact
compact
--layout compact
dense-grid
dense-grid
--layout dense-grid
downtown
downtown
--layout downtown
floating-island
floating-island
--layout floating-island
wireframe
wireframe
--layout wireframe
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

3. Heights and viewing angles

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.

Height presets

standard (default)
standard (default)
--height-preset standard
tall
tall
--height-preset tall
custom: scale 1.5, max 90
custom: scale 1.5, max 90
--height-preset custom --scale 1.5 --max-building-height 90

Height modes with the standard preset

power (default curve)
power (default curve)
--height-mode power
linear
linear
--height-mode linear
sqrt
sqrt
--height-mode sqrt
log
log
--height-mode log

Height modes with the tall preset

power (default curve)
power (default curve)
--height-mode power
linear
linear
--height-mode linear
sqrt
sqrt
--height-mode sqrt
log
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 styles

--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
detailed
--building-style detailed
solid
solid
--building-style solid

Viewing angles

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)
isometric (30 deg)
--view-angle isometric
low (20 deg)
low (20 deg)
--view-angle low
high (42 deg)
high (42 deg)
--view-angle high
top-down (58 deg)
top-down (58 deg)
--view-angle top-down

4. Backgrounds

solid
solid
--background solid
transparent
transparent
--background transparent
transparent-sky
transparent-sky
--background transparent-sky
auto + appearance auto
auto + appearance auto
--background auto --appearance auto --theme profile

Resolves to transparent-sky; carries a dark and a light palette.

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.

Command-line reference

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.

GitHub Action

- 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.

Visual testing and the gallery

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 reviewing

The guide for tolerances, failure artifacts and adding themes is docs/visual-testing.md.

SVG quality

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.

Data format

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.

Upgrading from 1.2.0

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 input height-preset: tall, YAML city.height_preset: tall). SVGs are otherwise byte-identical for the same options (tested).
  • Configurations that set building_scale, min_building_height or max_building_height keep their old look (they become preset custom). 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.

Known limitations

  • appearance=auto exists for navy-cyan and profile only.
  • 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.
  • downtown is not chronological.
  • On a transparent background, wireframe fills faces with the theme's lower background colour to hide lines behind them; choose a theme close to your page colour.
  • --no-fit with a steep or low angle can leave the city outside the canvas; the default fit cannot.
  • The preview SVGs use the dark solid/transparent themes; light-page rendering is covered by the *-light themes. Browser handling of prefers-color-scheme inside <img> was not tested.
  • Visual baselines come from one renderer (resvg 0.5.x) and are compared on Linux in CI.

Development

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.md

License

MIT, see LICENSE.

About

Generate customizable pixel-art contribution cities with a Python CLI and reusable GitHub Action. Create GitHub repository

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages