# Calendar++

**English** | [中文](README_ZH-CN.md)

An enhanced calendar plugin for [Obsidian](https://obsidian.md), built on top
of the classic [Calendar Plus](https://github.com/liamcain/obsidian-calendar-plugin)
plugin with a full rewrite of the note management layer and additional
features.

## Features

- **Calendar view** in the right sidebar — open it via the ribbon icon
  (`calendar-days`) or the `Calendar++: Open view` command.
- **Periodic notes** — daily, weekly, monthly, quarterly, and yearly notes,
  each with its own folder, filename format (Moment.js syntax), and template.
  Click a day/week/month/quarter/year cell to open or create the note.
- **Chinese calendar data** — lunar dates, solar terms, and Chinese public
  holidays shown under each day; legal holidays are highlighted in gold, rest
  days (`休`) and make-up workdays (`班`) are marked for past dates.
- **Memorial days** — custom one-per-line entries in `solar:MM-DD:name` or
  `lunar:MM-DD:name` form, displayed in gold and overriding the day's
  lunar/term text.
- **Holiday data sync** — regenerates lunar/term/holiday data for the current
  year ±3 years using the bundled Tyme library.
- **Heatmap** — each day cell's background tint reflects how many files were
  created on that day, with configurable intensity thresholds.
- **Week numbers** — shown on the left (default) or right side of the grid.
- **Keyboard navigation** — arrow keys move day by day / week by week; `Enter`
  creates the daily note when it doesn't exist.
- **Open in new tab / split** — `Ctrl`/`Cmd` + click on any calendar item.
- **Dual-language UI** — `Auto` (follow Obsidian's language), `中文`, or
  `English`.
- Compatible with the **Minimal** theme and the **CalcCraft** plugin (conflict
  fixes included).

## Installation

### From GitHub Releases (recommended)

1. Download the latest release assets (`main.js`, `manifest.json`,
   `styles.css`) from the Releases page.
2. Create a folder named `calendar-plus-plus` under your vault's
   `.obsidian/plugins/` directory.
3. Copy the three files into it and enable **Calendar++** in
   *Settings → Community plugins*.

### With BRAT

1. Install the [BRAT](https://github.com/TfTHacker/obsidian42-brat) plugin.
2. In BRAT settings, add the GitHub repository of this plugin
   (`<your-username>/calendar-plus-plus`).
3. Enable **Calendar++** under *Settings → Community plugins*.

> The release package must also include `tyme4ts.cjs` (bundled dependency used
> by the "Sync holiday data" feature). When installing manually, copy all four
> files listed in the release assets.

## Usage

### Creating notes

Enable each note type in *Settings → Calendar++*. For every enabled type you
can set:

- **Date format** — Moment.js format string used for the filename
  (e.g. `YYYY-MM-DD` for daily, `gggg-[W]ww` for weekly).
- **Folder** — where notes are created (empty = vault root).
- **Template** — template file applied on creation (supports
  `{{date:...}}`/`{{time:...}}` and `{{weekday:...}}` tokens).

Clicking an empty cell creates the note; clicking an existing note opens it.
`Ctrl`/`Cmd` + click opens it in a new tab or split (configurable).

### Chinese calendar & memorial days

Under *Special Daily Markers*:

```text
lunar:08-15:Mid-Autumn memorial
solar:02-02:Anniversary
```

Use the *Sync latest holiday data* button to regenerate lunar dates, solar
terms, and holidays for the current year ±3 years (dates after today are not
marked as rest/work days).

### Heatmap

`heatmapThresholds` takes three comma-separated numbers (default `1,3,7`) that
control the background intensity tiers: no tint for 0 files, light for 1–2,
medium for 3–6, heavy for 7+.

## Settings reference

| Setting | Description |
| --- | --- |
| Confirm before creating new note | Show a confirmation dialog before creating notes |
| Show Today button on mobile | Show the `Today` button in the mobile calendar header |
| Arrow key navigation | Move between days/weeks with the arrow keys |
| Show week number on the right | Move week numbers from the left to the right side |
| Override locale | Force a Moment.js locale instead of the system default |
| Plugin language | `Auto` / `中文` / `English` |
| Memorial days | Custom solar/lunar memorial entries (gold display) |
| Sync latest holiday data | Regenerate lunar/term/holiday data for current year ±3 years |
| Heatmap thresholds | Comma-separated tiers for the per-day background intensity |
| Exclude folders from creation-date search | Folders ignored by the per-day file list |

## Compatibility

- Obsidian **1.12.7** or newer (desktop and mobile).
- Tested with the **Minimal** theme; known conflicts with the **CalcCraft**
  plugin have been fixed.

## Related plugins

- **[Tickban](https://github.com/mashx43/obsidian-tickban)** — recommended for
  to-do management: it automatically collects `[ ]` task items from across
  your entire vault and aggregates them into a Kanban board
  (TODO / DOING / DONE), with Glob-based include/exclude filtering and tag
  badges on cards.

## Development

This repository ships prebuilt artifacts only (`main.js` is a bundled
CommonJS build that requires `obsidian` at runtime). No build step is needed
to install the plugin.

## License

[MIT](LICENSE). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for attributions of bundled/derived projects.