Obsidian community plugin · v2.12.0 · Apache-2.0
Heatmap Tracker turns any dated note in your Obsidian vault into a GitHub-style heatmap. Habits, workouts, mood, sleep, finances, work logs — anything you already write down. No account, no cloud, no export step.
Read from exercise: in your daily notes
How it works
You already write things down. Heatmap Tracker reads those notes and draws the grid — no database, no sync, no separate app to open.
Any frontmatter key works. Numbers are used as-is;
true counts as 1.
---
steps: 8420
mood: 4
meditated: true
---The recommended way: fill in the form, watch the live preview, and the codeblock is written for you. Every heatmap keeps an edit button that reopens the same form.
```heatmap-tracker
property: steps
```Hover a square for the details, click it to open that note — or to create it if it isn't there yet.
```heatmap-tracker
property: [running, cycling, swimming]
path: "daily notes"
tags: [journal]
```dataviewjs escape hatch
lets you build the dataset yourself — computed values, external
sources, a custom color per entry — and hand it to
renderHeatmapTracker(container, trackerData).
See the advanced guide →
Features
Everything below ships in the free plugin. No tiers, no upsell, no login wall.
Palettes in settings, customColors per heatmap, or
a customColor on a single entry. Set
scaleStart/scaleEnd so your values
actually spread across the scale.
A dedicated tab with totals and streaks, plus insights you define yourself: most productive day, longest streak, most active month, average intensity. 12 insights to copy →
layout: "monthly" for one row per month with days
1–31 as columns, or "month" / "week"
for a single wall-calendar period you page through — or keep the
classic contribution grid with months visually split.
A full year, the last N months, the last
N days, or an explicit startDate–endDate
window.
Markdown or self-contained HTML, with the grid, a legend you label yourself, a summary line and each day's note content grouped by week.
Every filled square opens the note behind it. Every empty square
offers to create it — or stays quiet with
disableFileCreation.
English, German, Russian, Chinese, Hindi, Spanish, French, Portuguese and Polish — with a documented path for adding yours.
Your notes are the database. Nothing is uploaded, nothing is synced, nothing is measured. Open source under Apache-2.0.
Use cases
Each one is a single frontmatter key. Every example below ships in the example vault.
exercise: 45
Spot the weeks you skipped, not just the total.
meditated: true
Streaks become visible — and hard to break.
hours-slept: 7.5
See the slow drift before it becomes a problem.
mood: 4
Correlate bad stretches with what else was happening.
spent: 120
A year of spending on one screen.
pages-read: 30
Small daily numbers add up visibly.
water: 6
Zero-effort adherence check.
hours: 8
Export it as a report for your manager.
headache: 3
Bring a real timeline to your doctor.
tasks-done: 5
Momentum, not just a burn-down chart.
Export
The Export tab sits between a bare calendar (too little context) and a folder of raw notes (too much noise): the grid, rendered pixel-for-pixel like your heatmap, then every day's own note content underneath it, grouped by week.
Workday: 22 · Leave: 1 with a
total
Install
Settings → Community plugins, turn Restricted mode off, hit Browse and search for Heatmap Tracker. Install, then enable.
Open the plugin page
The heatmap-tracker codeblock reads your notes
through
Dataview. Install it the same way; for dataviewjs examples
also enable Enable JavaScript Queries.
Drop main.js, styles.css and
manifest.json from the latest release into
<vault>/.obsidian/plugins/heatmap-tracker/.
Beta builds go through BRAT.
How it compares
Heatmap Tracker began as a rewrite of the excellent
heatmap-calendar-obsidian
by Richardsl, and went further. If all you need is a one-year grid
from a
dataviewjs script, the original is lighter.
| Capability | Heatmap Tracker | heatmap-calendar |
|---|---|---|
| Codeblock without JavaScript | Yes | dataviewjs required |
| Interactive insert command | Modal builder | No |
| Statistics & custom insights | Yes | No |
| Monthly (calendar) layout | Yes | No |
| Single month / week view | Yes | No |
| Flexible date ranges | Days, months, explicit range | Full year |
| Export to Markdown / HTML | Yes | No |
| Localization | 9 languages | No |
| Click to open and create notes | Yes | Partial |
Guides
Longer walkthroughs for the things people build most often with Heatmap Tracker.
From a line of frontmatter in a daily note to a year of visible streaks — including multi-habit grids and what to check when the grid is empty.
⚙️
The working shape of a dataviewjs block: the
entries array, computed intensities, click-through paths, and
the timezone trap behind off-by-one days.
The same year grid, drawn from your own notes — what carries over from GitHub, what is different, and how to shape the range.
📈
Twelve copy-paste insights — longest streak, days
at goal, most active weekday, year coverage — and the rules for
writing your own.
FAQ
No. Everything is computed locally from your notes. There's no account, no sync, no telemetry.
For the no-code heatmap-tracker codeblock, yes —
that's how notes are read. But
renderHeatmapTracker(container, trackerData) accepts
any entries array, so any JavaScript that can build
one works.
Yes. The plugin isn't desktop-only; iOS and Android are supported.
In order: Dataview enabled; the property name spelled exactly
right (it's case-sensitive); your notes inside the searched folder
(set path
if they're not); the displayed year matching your data. A missing
property logs a warning in devtools.
Your values are landing in one bucket. Bracket the range you care
about with
intensityConfig.scaleStart and
scaleEnd — e.g. 30–120 for
reading minutes.
Almost always a timezone issue in how the date was parsed. Use
plain
YYYY-MM-DD strings for date rather than
Date objects or ISO timestamps with a time component.
Yes — property: [running, cycling, swimming]. The
values are aggregated into a single heatmap.
Nothing. Free and open source under Apache-2.0. If it saves you time, you can buy the author a coffee — entirely optional.
Still stuck? Open an issue with your codeblock, a sample note and your versions.
Free, open source, and it reads the notes you're already writing. One codeblock and your year shows up.