A Pelican plugin that generates a GitHub-style writing heatmap from your articles

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for LeeW from gravatar.com LeeW

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT
  • Author: Wei Lee
  • Tags pelican , plugin , heatmap , blog , writing
  • Requires: Python >=3.10
Classifiers
Report project as malware

Project description

pelican-heatmap

A Pelican plugin that generates a GitHub-style writing activity heatmap for your blog. At build time it scans all your articles and produces a JSON data file; a self-contained JS + CSS widget reads that file and renders an interactive calendar you can drop into any page.

Features

  • GitHub-style heatmap — one cell per day, four color levels based on post frequency
  • Year navigation — scroll back through your entire writing history with ‹ › buttons; the view always opens on the most recent year
  • Live stats — posts in the current view window, all-time total, and current streak
  • Clickable cells — click or tap any day to pin a tooltip listing that day's articles with links; click again or press Escape to dismiss
  • Dark mode — respects prefers-color-scheme automatically
  • Reduced motion — respects prefers-reduced-motion by disabling animations
  • Responsive — cell size scales with viewport via clamp(); works on mobile and large screens
  • Accessible — keyboard-navigable year buttons with visible focus ring, aria-label for screen readers, Escape to dismiss tooltips, aria-busy loading state, <noscript> fallback support
  • Touch-friendly — dedicated touch handling for tooltips on mobile devices
  • i18n — built-in locales (en, zh-TW) via window.HM_LANG, or full custom override via window.HM_LOCALE
  • Customizable — every element has a named CSS class; colors and sizing controlled by CSS custom properties (--hm-level-1–4, --hm-cell-size, etc.)
  • Configurable data source — override the JSON URL via data-src attribute or window.HM_DATA_URL
  • Zero dependencies — no third-party libraries required

Installation

pip install pelican-heatmap

Or with uv:

uv add pelican-heatmap

Setup

1. Enable the plugin

# pelicanconf.py
PLUGINS = ["pelican.plugins.heatmap"]

2. Add the widget to a page

The plugin copies pelican_heatmap.css and pelican_heatmap.js to output/static/ automatically at build time. Add these three lines wherever you want the heatmap to appear — a dedicated page, your about page, or a sidebar:

<link rel="stylesheet" href="/static/pelican_heatmap.css">
<div id="writing-heatmap"></div>
<script src="/static/pelican_heatmap.js" defer></script>

In a Jinja2 template:

<link rel="stylesheet" href="{{ SITEURL }}/static/pelican_heatmap.css">
<div id="writing-heatmap"></div>
<script src="{{ SITEURL }}/static/pelican_heatmap.js" defer></script>

3. Build

pelican content

The plugin generates output/writing-heatmap.json and copies the static assets. That's it.

Localization

The widget automatically reads <html lang="..."> to pick the right locale. For example, if your page has <html lang="zh-TW">, the heatmap renders in Taiwanese Mandarin with no extra configuration.

Available built-in locales: en (default), zh-TW.

You can explicitly override with window.HM_LANG:

<script>window.HM_LANG = "zh-TW";</script>

Resolution order: window.HM_LANG > <html lang> > en.

You can also override individual keys on top of any locale with window.HM_LOCALE:

<script>
window.HM_LOCALE = { no_posts: '無文章' }; // override just one key
</script>

All keys are optional — omitted keys fall back to the resolved locale's defaults.

The heatmap data (writing-heatmap.json) is shared across all languages — only the UI strings change per locale.

Custom data URL

By default the widget fetches /writing-heatmap.json. Override this if your site is served from a subpath:

<div id="writing-heatmap" data-src="/blog/writing-heatmap.json"></div>

Or via JavaScript:

<script>window.HM_DATA_URL = "/blog/writing-heatmap.json";</script>

Resolution order: data-src attribute > window.HM_DATA_URL > /writing-heatmap.json.

No-JavaScript fallback

Place fallback content inside the mount div. The widget replaces it once JS loads:

<div id="writing-heatmap">
  <noscript>
    <p>Enable JavaScript to see the writing activity heatmap.</p>
  </noscript>
  <p class="hm-loading">Loading heatmap…</p>
</div>

Customization

CSS custom properties

Override these in :root or any parent selector:

Property Default (light) Description
--hm-cell-size clamp(10px, 1.2vw, 18px) Cell and row height; scales the whole grid
--hm-cell-empty #e8e6e1 Empty cell color
--hm-level-1 #b5d8a4 Level 1 cell color (lowest activity)
--hm-level-2 #6db86a Level 2 cell color
--hm-level-3 #3a9142 Level 3 cell color
--hm-level-4 #1d6230 Level 4 cell color (highest activity)
--hm-card-bg #f0ede8 Stat card background
--hm-text-num #1a1a1a Large number color
--hm-text-muted #888 Label and secondary text
--hm-label-col #aaa Month and legend label color
--hm-label-day #bbb Weekday label color
--hm-btn-bg #ede9e3 Nav button background
--hm-btn-hover #ddd9d2 Nav button hover background
--hm-btn-text #555 Nav button text
--hm-btn-dis #ccc Disabled button text

Example — larger cells:

#writing-heatmap {
  --hm-cell-size: 18px;
}

Color levels

#writing-heatmap {
  --hm-level-1: #a8c8f8;
  --hm-level-2: #5a9fd4;
  --hm-level-3: #2376b7;
  --hm-level-4: #0d4f8a;
}

Full class reference

#writing-heatmap               outer wrapper
.hm-stats                      stats row
.hm-stat-card                  individual stat card
.hm-stat-num                   large number in card
.hm-stat-label                 label below number
.hm-nav                        nav row
.hm-nav-btn                    prev / next buttons
.hm-nav-range                  date range text
.hm-container                  scrollable grid wrapper
.hm-month-label-cell           per-column month span
.hm-month-label-cell--visible  span showing a month name
.hm-day-labels                 Su Mo … Sa column
.hm-grid                       the cell grid
.hm-cell                       individual day cell
.hm-cell[data-level="0–4"]     color levels
.hm-cell--future               days after today
.hm-cell--past                 days before first article
.hm-legend                     legend row
.hm-legend-cell                legend color swatch
.hm-tooltip                    tooltip container
.hm-tooltip.hm-visible         tooltip when shown (hover)
.hm-tooltip.hm-pinned          tooltip when clicked / pinned
.hm-tt-date                    date line inside tooltip
.hm-tt-list                    article list inside tooltip
.hm-tt-empty                   "No posts" message
.hm-loading                    loading placeholder (replaced by widget)

JSON format

The plugin writes output/writing-heatmap.json with the following shape:

{
  "data": {
    "2025-03-12": {
      "count": 2,
      "articles": [
        { "title": "Article title", "url": "/posts/article-slug.html" }
      ]
    }
  },
  "total": 260,
  "streak": 5,
  "most_active_day": "2025-07-04"
}

You can consume this file independently of the widget if you want to build your own visualization.

Requirements

  • Python 3.10+
  • Pelican 4.5+

License

MIT

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for LeeW from gravatar.com LeeW

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT
  • Author: Wei Lee
  • Tags pelican , plugin , heatmap , blog , writing
  • Requires: Python >=3.10
Classifiers

Release history Release notifications | RSS feed

0.4.1

This version

0.4.0

0.3.1

0.3.0

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pelican_heatmap-0.4.0.tar.gz (12.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pelican_heatmap-0.4.0-py3-none-any.whl (13.2 kB view details)

Uploaded Python 3

File details

Details for the file pelican_heatmap-0.4.0.tar.gz.

File metadata

  • Download URL: pelican_heatmap-0.4.0.tar.gz
  • Upload date:
  • Size: 12.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for pelican_heatmap-0.4.0.tar.gz
Algorithm Hash digest
SHA256 4ac40c6f7a2ca8c999c6445f8211b35ac57bef769550ef8900e7ee1a134bd8c2
MD5 334dacb388a92cfe9e85e6c8542ece6d
BLAKE2b-256 59619ba19ae657233a0d5892ceb871e584af6b3cfb50ab0d2146b5c25c1c4308

See more details on using hashes here.

Provenance

The following attestation bundles were made for pelican_heatmap-0.4.0.tar.gz:

Publisher: publish-to-pypi.yaml on Lee-W/pelican-heatmap

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pelican_heatmap-0.4.0-py3-none-any.whl.

File metadata

  • Download URL: pelican_heatmap-0.4.0-py3-none-any.whl
  • Upload date:
  • Size: 13.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for pelican_heatmap-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 cc6f77ede42b336ecbecc5c60e6edcfbd10af6dfe73769254244684dafd337b1
MD5 78befc33a4427d06b09cb00400a07aed
BLAKE2b-256 5461e27ae38f71fd9373e5d4901002510f488c2c917abf484f6c18139a2256bf

See more details on using hashes here.

Provenance

The following attestation bundles were made for pelican_heatmap-0.4.0-py3-none-any.whl:

Publisher: publish-to-pypi.yaml on Lee-W/pelican-heatmap

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page