UniCalendar

A unified calendar view for Obsidian that aggregates events from Google Calendar, CalDAV servers, and ICS feeds into a single month view — with Chinese lunar calendar, solar terms, and public holiday annotations.

Features

• Unified month view — see all your calendar sources in one place, color-coded by source
• Google Calendar sync — OAuth 2.0 PKCE flow, no server required; supports multiple calendars per account
• CalDAV sync — connect to Nextcloud, iCloud, Fastmail, or any CalDAV-compatible server
• ICS feed sync — subscribe to any public or private .ics URL
• Chinese lunar calendar — lunar dates, traditional festivals (春节, 端午, 中秋…), and 24 solar terms displayed in each cell
• Public holiday overlay — statutory holidays and adjusted workdays (补班) sourced from holiday-cn
• Event deduplication — events shared across sources are shown once, with configurable source priority. Additional same-source deduplication removes duplicate instances when a provider returns the same occurrence more than once; if duplicates share the same source, start time, and overlapping normalized titles (exact match or one title containing the other), UniCalendar keeps the richer copy (for example the one with location, description, or meeting link metadata)
• Auto-sync — configurable sync interval (default 30 minutes); manual sync available via command palette
• Mobile compatible — works on iOS and Android (isDesktopOnly: false)

Installation

From Obsidian community plugins (recommended)

1. Open Settings → Community plugins → Browse
2. Search for UniCalendar
3. Select Install, then Enable

Manual installation

1. Download main.js, manifest.json, and styles.css from the latest release
2. Copy the three files to <Vault>/.obsidian/plugins/uni-calendar/
3. Reload Obsidian and enable the plugin in Settings → Community plugins

Configuration

Open Settings → UniCalendar to configure calendar sources.

Add a Google Calendar source

1. Select Add source → Google Calendar
2. Enter your Google OAuth client ID and client secret (see Google Cloud Console)
3. Select Authorize — a browser window opens for the OAuth flow
4. After authorization, select which calendars to include

Add a CalDAV source

1. Select Add source → CalDAV
2. Enter the server URL, username, and password
3. Select Discover calendars to list available calendars

For Feishu/Lark CalDAV performance notes and troubleshooting, see Feishu CalDAV diagnostics.

Add an ICS feed

1. Select Add source → ICS feed
2. Paste the ICS URL
3. Optionally set a display name and color

Other settings

Event title filters

Use Settings → UniCalendar → Event title filters to hide noisy events across all calendar sources without deleting the underlying event data.

Each rule supports two modes:

• Hide when title exactly matches — useful for suppressing one recurring event name only
• Hide when title contains the string — useful for suppressing classes of events by keyword

Examples:

• Input WaytoAGI晚8点共学 with exact match hides only events whose title is exactly WaytoAGI晚8点共学
• Input WaytoAGI with contains hides any event whose title contains WaytoAGI

Matching is case-insensitive and ignores leading/trailing or repeated whitespace.

Usage

• Select the calendar icon in the ribbon to open the calendar view
• Use the command palette (Ctrl/Cmd+P) and search for Open calendar
• Navigate months with the < and > arrows in the view header
• Select any event to see its full details

Privacy

UniCalendar operates entirely locally. Calendar credentials are stored in your vault's plugin data file (<Vault>/.obsidian/plugins/uni-calendar/data.json). No data is sent to any third-party service other than the calendar providers you explicitly configure. Holiday data is fetched from the jsdelivr CDN on first load and cached locally.

Development

# Optional: enable external dependencies for this shell session.
# This keeps node_modules out of OneDrive-synced project directories.
. .\setenv.ps1

# Install dependencies.
# With setenv.ps1 loaded, this installs to the external directory.
# Without setenv.ps1, the same command installs to local ./node_modules.
npm run deps:install

# Watch mode (auto-recompile on save)
npm run dev

# Production build
npm run build

# Run tests
npm test

# Lint
npm run lint

Use npm run deps:install in both modes. By default, it behaves like npm install and creates local ./node_modules. To opt in to external dependencies, dot-source setenv.ps1 in the current PowerShell session before running npm scripts:

. .\setenv.ps1

The script sets EXTERNAL_NODE_MODULES to C:/local_data/<project-folder>/node_modules and updates NODE_PATH/PATH for the session. With that variable set, npm run deps:install installs dependencies into the external directory, and build/test/lint resolve tools from there. Without that variable, scripts fall back to the project directory's node_modules. Do not create a symlink or junction back to node_modules. See External node_modules guide for the reusable setup details.

Copy main.js, manifest.json, and styles.css to <Vault>/.obsidian/plugins/uni-calendar/ and reload Obsidian to test locally.

License

0-BSD