Monthly Tracker

Monthly Tracker Plugin for Obsidian

Visualize your daily note data as monthly tracker strips — right inside your notes. Turn habits, moods, exercise, sleep, and anything else you log into color-coded patterns you can read at a glance.

---

How It Works

1. Your monthly note declares year and month in its frontmatter.
2. The plugin scans your daily notes folder for files starting with YYYY-MM-DD. (Folder is read from settings, or auto-detected from the Daily Notes / Periodic Notes plugin.)
3. It reads a frontmatter property from each daily note and renders a full month of colored cells.
4. Click any cell to open that day's note.

---

Prerequisites

Monthly Note

The plugin reads year and month from the current note's frontmatter to determine which month to render. Both fields are required.

---
year: 2026
month: 6
---

Daily Notes

File names must start with your configured date format (default: YYYY-MM-DD). Text after the date is ignored — 2026-06-03.md and 2026-06-03 Tuesday.md both work.

Values to track go in each daily note's frontmatter:

---
workout: true
mood: good
distance: 5.2
sleep: 7
---

---

Usage

Add a monthly-tracker code block anywhere in your monthly note:

```monthly-tracker
type: boolean
property: workout
color: blue
```

---

Tracker Types

1. Boolean — Completion

Highlights days where a property is truthy. Perfect for habit tracking.

Habit tracking — preset color

```monthly-tracker
type: boolean
property: workout
color: blue
```

Habit tracking — hex color

```monthly-tracker
type: boolean
property: meditation
color: "#66bb6a"
```

File existence — omit property

If property is omitted, any day that has a file in the source folder will be highlighted. Useful for journals or logs where creating the file is the record itself (e.g. morning journals, meal diaries).

```monthly-tracker
type: boolean
source: Calendar/Morning Journals
color: yellow
```

---

2. Colormap — Categories

Maps string values to colors. Use it when you want to classify data by label — mood, condition, workout type, focus level, etc.

Workout type

```monthly-tracker
type: colormap
property: workout-type
colors:
  run: "#e53935"
  lift: "#7986cb"
  yoga: "#66bb6a"
  swim: "#29b6f6"
```

Focus level — 4 labels

```monthly-tracker
type: colormap
property: focus
colors:
  great: "#1565c0"
  normal: "#64b5f6"
  low: "#ffb74d"
  none: "#e57373"
```

---

3. Heatmap — Activity Volume

The higher the value, the darker the color. Great for sleep hours, running distance, pages read, and any other numeric data.

Running distance — colorScheme

```monthly-tracker
type: heatmap
property: distance
colorScheme: indigo
bins: [3, 5, 7, 10]
unit: km
showTotal: true
```

Setting bins: [3, 5, 7, 10] with 4 boundary values creates 5 intensity levels:

Sleep — custom colors

```monthly-tracker
type: heatmap
property: sleep
unit: h
bins: [5, 6, 7, 8]
colors:
  - "#ffcdd2"
  - "#ef9a9a"
  - "#e57373"
  - "#ef5350"
  - "#c62828"
showTotal: true
```

Pages read — no total

```monthly-tracker
type: heatmap
property: pages
colorScheme: green
bins: [10, 30, 60, 100]
unit: p
```

---

Built-in Colors

Boolean color / Heatmap colorScheme

You can also use any hex color directly: color: "#ff5722"

For Boolean, the color is applied as a single solid fill. For Heatmap, the chosen theme is rendered as a gradient from light (low/no data) to dark (high). Default theme is indigo.

---

Settings

Settings → Monthly Tracker:

Use YYYY (year), MM (month), and DD (day) tokens with any separator:

Need a different format? Feel free to open a PR.

For trackers that need to scan a different folder than the default, use the source option:

type: boolean
source: Calendar/Morning Journals
color: yellow

---

Troubleshooting

Missing required field: type — Add type: boolean, type: colormap, or type: heatmap to the code block.

heatmap requires "bins" — bins is required for heatmap trackers. Add e.g. bins: [3, 5, 7, 10].

Current note must have 'year' and 'month' in frontmatter — Add year and month to the monthly note's frontmatter.

Cells not colored — Check that the property name exactly matches the frontmatter key in your daily notes, and that your daily note files are in the configured folder with names starting in the correct date format.

---

Contributing

Have ideas for new color themes, features, or improvements? PRs are welcome.

Development setup

Requires Node.js 20 or newer.

npm install      # install dependencies
npm run dev      # build main.js and rebuild on change
npm run build    # type-check and produce a production main.js

main.js is a build artifact and is not tracked in the repo — run npm run build (or npm run dev) before loading the plugin in Obsidian for local testing.

Tests

Pure logic (date patterns, folder resolution, config validation, color presets) and the renderer's DOM output are covered by Vitest. The renderer tests run under happy-dom, so no Obsidian runtime is needed.

npm test         # run the full suite once
npx vitest       # watch mode: re-run on change

Please add or update tests when changing behavior. Lint, build, and tests run automatically on every pull request via GitHub Actions.

---

한국어 README