substack-contribution-graph

A GitHub-style contribution heatmap for your Substack posts.

What it does

Takes your Substack data export and generates an interactive heatmap showing your posting activity over time -- just like GitHub's contribution graph, but for your writing.

Features:

• GitHub dark-theme heatmap with green intensity scale
• Hover any day to see post titles
• Month and day-of-week labels
• Stats: total posts, posts/week average, best week, longest daily streak
• Copy as PNG / download image buttons
• Single self-contained HTML file

How to get your Substack data

1. Go to your Substack dashboard
2. Click Settings in the left sidebar
3. Scroll down to the Exports section
4. Click Create new export
5. You'll receive an email with a download link -- download and unzip the archive
6. Inside the archive you'll find a posts.csv file

Usage

With an AI coding agent (recommended)

This repo is designed to work as a skill for AI coding agents (Claude Code, OpenCode, Cursor, etc.):

1. Point your agent at this repo and the SKILL.md file
2. Give it your unzipped Substack export directory
3. Ask it to generate the contribution graph

The agent will read your posts.csv, inject it into the template, and produce a ready-to-go index.html.

Manual usage

1. Open template.html
2. Replace {{SUBSTACK_HANDLE}} with your Substack handle (e.g. jamespember)
3. Replace {{CSV_DATA}} with the contents of your posts.csv file
4. Open the resulting HTML file in a browser

Note: Since the CSV is placed inside a JavaScript template literal, you'll need to escape any backtick characters (` to \`) and ${ sequences (${ to \${) in your CSV data. In practice, Substack CSVs rarely contain these characters.

License

MIT