English | 中文

A calendar widget for Obsidian combining the Gregorian and Lunar (Chinese) calendars with 5 levels of periodic notes, task tracking, and holiday support. It merges the ideas of Calendar and Chinese Calendar into one view.

Features

Calendar views

• Month view — classic month grid with ISO week numbers, lunar dates, festivals, and holiday/workday badges
• Year view — 4 quarters × 3 months layout; open or create monthly, quarterly, and yearly notes
• Selection highlight and nav-button tooltips

Lunar calendar & holidays

• Lunar dates, the 24 solar terms, and traditional festivals
• Chinese statutory holidays — 休 (day off) / 班 (workday) badges with custom overrides
• Gan-Zhi year & zodiac shown under the calendar title

Periodic notes (5 levels)

• Daily / Weekly / Monthly / Quarterly / Yearly notes, each with its own enabled flag, date format, folder, and template
• Confirm before create — clicking a missing note asks first; existing notes open directly
• Context menu — open, reveal in file explorer, or delete an existing note
• Date sync — opening a daily note moves the calendar to its month

Tasks & links

• Task indicators — parses - [ ] / - [x] checkboxes and shows completion dots
• Click a task dot to open the note and jump to the first incomplete task
• Backlink counts for daily notes (up to 5 dots + overflow badge)
• Aggregated progress (3/5) on weekly/monthly/quarterly/yearly notes

Interaction

• Hover preview on dates that already have a note
• Ctrl/Cmd + click to open in a new split
• Keyboard navigation — ← → ↑ ↓ to page, t for today

Performance & theming

• Incremental indexing — O(1) updates on create/delete/rename/modify, no full-vault rescans
• Custom CSS classes injectable onto the calendar container
• First-run migration from Core Daily Notes, Calendar, and Chinese Calendar plugins
• Template path auto-repair for legacy paths

Install

From Obsidian Community Plugins

1. Open Settings → Community plugins
2. Browse and search for Mix Calendar, then install and enable it

Requires Obsidian 1.7.2 or later.

Manual install

1. Download main.js, styles.css, and manifest.json from the latest release
2. Place them in <vault>/.obsidian/plugins/mix-calendar/
3. Restart Obsidian and enable Mix Calendar under Community plugins

Build from source

git clone https://github.com/Liury23/mix-calendar
cd mix-calendar
npm install
npm run build
# Deploy to your vault
cp main.js styles.css manifest.json <vault>/.obsidian/plugins/mix-calendar/

Settings

General

Appearance

Periodic notes (5 levels)

Each level configures: enabled, date format (moment.js format used for filenames), folder, and template. Defaults:

• Daily: YYYY/YYYY-MM/YYYY-MM-DD · Weekly: YYYY/YYYY-[W]WW · Monthly: YYYY/YYYY-MM · Quarterly: YYYY/YYYY-[Q]Q · Yearly: YYYY

Custom holidays

Override the built-in statutory holiday table, one YYYY-MM-DD:休 or YYYY-MM-DD:班 per line. Lines starting with # are comments.

# Company holiday
2026-05-05:休
# Makeup workday
2026-10-10:班

Template variables

Commands

Development

npm run dev          # Watch mode
npm run build        # Typecheck + production build
npm run test         # Unit tests
npm run lint         # ESLint (obsidianmd rule set)
npm run typecheck    # tsc --noEmit

Stack: TypeScript + Svelte 4 + esbuild + lunar-typescript + vitest. Releases run through GitHub Actions with build-provenance attestations; publish the draft release created for each tag.

Acknowledgments

• dust-obsidian-calendar by a-nano-dust — inspiration
• Calendar, Periodic Notes, and obsidian-daily-notes-interface by Liam Cain — core design patterns for periodic-note indexing, month view interactions, and the daily-notes interface
• obsidian-lunar-calendar by DevilRoshan — lunar calendar integration

License

MIT

中文说明

English | 中文

Mix Calendar 是一个 Obsidian 日历插件，在同一视图中合并公历与农历、节假日、任务状态以及 5 种颗粒度的周期性笔记。它融合了 Calendar 与 Chinese Calendar 的功能。

功能

日历视图

• 月视图 — 标准月历网格，含 ISO 周数、农历、节日、休/班标记
• 年视图 — 4 季度 × 3 月布局，支持月记/季记/年记创建与打开
• 选中日期高亮、导航按钮 tooltip

农历与节日

• 农历信息 — 农历日期、二十四节气、传统节日
• 法定节假日 — 「休」「班」角标，支持自定义覆盖
• 干支生肖年 — 日历标题下方显示干支年 + 生肖

周期性笔记（5 级）

• 日记 / 周记 / 月记 / 季记 / 年记 — 每种独立配置（启用、格式、文件夹、模板）
• 创建前确认 — 点击不存在的笔记时弹出确认框；已存在则直接打开
• 右键菜单 — 打开、在文件浏览器中显示、删除
• 自动日期同步 — 打开日记时日历自动跟随到对应月份

任务与链接

• 任务完成指示 — 解析 - [ ] / - [x] checkbox，圆点显示完成状态
• 点击任务圆点 — 打开笔记并跳转到第一个未完成任务
• 反向链接计数 — 日记反链数量（最多 5 个点 + 溢出计数）
• 任务汇总 — 周记/月记/季记/年记显示 3/5 形式进度

交互增强

• Hover 预览 — 悬停已有笔记的日期格显示内容预览
• Ctrl/Cmd + 点击 — 在新分栏中打开笔记
• 键盘导航 — ← → ↑ ↓ 翻页，t 跳到今天

性能与主题

• 增量索引 — 创建/删除/重命名/修改笔记时 O(1) 更新
• 自定义 CSS 类 — 注入到日历容器，适配不同主题
• 设置自动迁移 — 首次运行自动从 Core Daily Notes、Calendar、Chinese Calendar 导入
• 模板路径自动修复 — 向后兼容旧路径

安装

从 Obsidian 社区插件安装

1. 打开 设置 → 第三方插件
2. 浏览搜索 Mix Calendar，安装并启用

需要 Obsidian 1.7.2 或更高版本。

手动安装

1. 从最新 Release 下载 main.js、styles.css、manifest.json
2. 放到 <vault>/.obsidian/plugins/mix-calendar/
3. 重启 Obsidian，在第三方插件中启用

从源码构建

git clone https://github.com/Liury23/mix-calendar
cd mix-calendar
npm install
npm run build
# 部署到 vault
cp main.js styles.css manifest.json <vault>/.obsidian/plugins/mix-calendar/

设置

通用

显示

周期笔记（5 级）

每级独立配置 启用、日期格式（moment.js 格式，决定文件名）、文件夹、模板。默认值：

• 日记 YYYY/YYYY-MM/YYYY-MM-DD · 周记 YYYY/YYYY-[W]WW · 月记 YYYY/YYYY-MM · 季记 YYYY/YYYY-[Q]Q · 年记 YYYY

自定义节假日

以 YYYY-MM-DD:休 或 YYYY-MM-DD:班 格式覆盖法定节假日库，每行一条，# 开头为注释。

# 公司假期
2026-05-05:休
# 公司调休
2026-10-10:班

模板变量

命令

开发

npm run dev          # 监视模式
npm run build        # 类型检查 + 生产构建
npm run test         # 单元测试
npm run lint         # ESLint（obsidianmd 规则集）
npm run typecheck    # tsc --noEmit

技术栈: TypeScript + Svelte 4 + esbuild + lunar-typescript + vitest。发布通过 GitHub Actions 完成，带构建来源证明（artifact attestation）；打 tag 后发布为 draft，确认后手动 publish。

致谢

• dust-obsidian-calendar by a-nano-dust — 灵感来源
• Calendar、Periodic Notes、obsidian-daily-notes-interface by Liam Cain — 周期性笔记索引、月视图交互与日记接口的核心设计范式
• obsidian-lunar-calendar by DevilRoshan — 农历系统集成

许可

MIT