# iCal Pro for Obsidian

Manage your tasks in Markdown and expose them to Google Calendar, Apple Calendar, and Outlook via standards-compliant iCalendar feeds.

![iCal Pro Illustration](assets/ical_pro_about.jpg)

> **The Professional Standard for Obsidian Calendar Sync.**
> - **High-Fidelity**: Strict RFC 5545 compliance (folding, CRLF, escaping).
> - **Zero Dependency**: Works natively with **Tasks** and **Day Planner** syntax without requiring those plugins to be installed.
> - **Privacy First**: Local-first architecture with optional GitHub Gist sync.
> - **Deep Logic**: Intelligent `VEVENT` vs `VTODO` semantic splitting.

---

## Privacy & Security

iCal Pro is built with a local-first philosophy.
- **No Data Collection**: We do not track your usage or collect any personal data.
- **Direct Sync**: Your calendar is synced directly from your device to your local file or GitHub Gist.
- **Secure Storage**: Your GitHub PAT is stored securely within Obsidian's local storage and is only used to communicate with the GitHub API.

## Core Capabilities

- **Intelligent Sync**: Automatically splits tasks into `VEVENT` (timed) and `VTODO` (dated/floating).
- **Zero-Dependency Discovery**: Inherits dates from Daily Note filenames or headings without requiring extra plugins.
- **Reliable Identity**: Stable `UID` generation ensures no duplicates when tasks move between files.
- **Flexible Destinations**: Sync to a local vault file or a private GitHub Gist for universal access.

## Supported Syntax

iCal Pro intelligently categorizes tasks based on the presence of **Time**.

| Feature | Syntax Example | Result (iCalendar) |
| :--- | :--- | :--- |
| **Event** (Timed) | `- [ ] 2026-04-01 13:00-14:00 Task` | `VEVENT` (Visible in Grid) |
| **Event** (Timed) | `- [ ] 13:00-14:00 Task` | `VEVENT` in Day Planner mode |
| **To-Do** (Dated) | `- [ ] 2026-04-01 Task` | `VTODO` (Sidebar/Reminders) |
| **Priority** | `⏫ High` / `🔼 Medium` / `🔽 Low` | `PRIORITY: 1 / 5 / 9` |
| **Alarms** | `⏰ 15` (15 minutes before) | `VALARM` |
| **Recurrence**| `🔁 every weekday` | `RRULE` |
| **Description**| `the description under the line - [ ]` | Visible in shcedule description |
| **Day Planner Mode** | `# 2026-04-01` (Any Heading) | Inherited Date |

> [!IMPORTANT]
> **Google Calendar Compatibility**: Google Calendar **does not support** `VTODO`. If you want your tasks to appear in the Google Calendar grid, you **must** include a time (e.g., `13:00`).

## Core Capabilities


- **Multi-Source Rules**: Bind specific vault paths to distinct calendar categories.
- **Granular Filtering**: Include/Exclude by global filters, tags, or categories.
- **Task Fidelity**: Native support for **Priority** (`⏫🔼🔽`), **Recurrence** (`🔁`), and **Alarms** (`⏰`).
- **Rich Context**: Full body capture from indented lists or blockquotes mapped to `DESCRIPTION`.
- **Diagnostics**: Built-in sync preview, destination reports, and redacted debug bundles.

## Compatible Calendars

iCal Pro produces RFC 5545 `.ics` output intended to work with:

- Google Calendar subscription
- Apple Calendar
- Outlook
- Proton Calendar
- Thunderbird
- Other clients that support iCalendar subscriptions

Client support for `VTODO` varies. Apple-oriented ecosystems usually handle `VTODO` better than Google Calendar.

## Getting Started

### Install

**Community Plugins (recommended):**
1. Open Obsidian Settings > Community Plugins > Browse
2. Search for "iCal Pro"
3. Click Install, then Enable

Or install directly: [Obsidian Community Plugins - iCal Pro](https://community.obsidian.md/plugins/ical-plugin-pro)

**BRAT (beta):**
1. Install [BRAT](https://github.com/TfTHacker/obsidian42-brat)
2. Add `liuh886/obsidian-ical-plugin-pro` as a beta plugin

### Configure

1. Open the `iCal Pro` settings tab
2. Add at least one source path rule
3. Enable at least one destination:
   - local vault file export
   - [GitHub Gist sync](https://gist.github.com/)
4. If you use GitHub Gist sync:
   - Create a secret Gist at [gist.github.com](https://gist.github.com/) and keep the generated `.ics` file there.
   - Copy the Gist ID from the Gist URL. In `https://gist.github.com/username/gist-id`, the final segment is the Gist ID.
   - Generate a [GitHub personal access token](https://github.com/settings/tokens/new?scopes=gist&description=iCal%20Pro%20Gist%20sync) with only the `gist` scope selected. A classic PAT is recommended for this workflow.
   - Fill in your GitHub username, Gist ID, and PAT in iCal Pro, then click `Validate`.
5. Click `Sync Now`
6. Subscribe to the generated raw Gist URL or local `.ics` file

## Debugging & Logs

If you encounter issues, you can enable verbose logging:

1. Open **Settings** > **iCal Pro**.
2. Scroll to the **Advanced & Diagnostics** section.
3. Toggle **Debug Mode** to **ON**.
4. Open the Obsidian developer console (press `Ctrl+Shift+I` on Windows/Linux or `Cmd+Option+I` on macOS).
5. Look for logs prefixed with `[info][ical]` or `iCal Pro:`.

You can also use the **Copy Diagnostics** button in the status card to generate a redacted summary of your configuration and recent sync history to include in bug reports.

## FAQ

**Q: Why don't my To-Dos (VTODO) show up in Google Calendar?**
A: Google Calendar natively only supports `VEVENT`. For full `VTODO` support, we recommend using Apple Calendar, Microsoft Outlook, or dedicated task managers like Reminders that support iCal subscriptions.

**Q: Is it safe to use GitHub Gist?**
A: Yes. Your Gist is yours. We recommend using a private Gist for maximum privacy. Your Personal Access Token never leaves your machine except to communicate with GitHub.

## Development

- `npm run build`
- `npm run typecheck`
- `npm run test:smoke`
- `npm run validate`

## Credits

iCal Pro is a significantly enhanced and refactored version of the original [obsidian-ical-plugin](https://github.com/mcarper1/obsidian-ical-plugin) by **Andrew Brereton**. 

This "Pro" edition maintains the original vision while introducing a completely re-engineered core for better performance, timezone reliability, and advanced task metadata support.

## License

MIT

---

## Support

If you find this plugin useful and want to support its development, you can buy me a coffee!

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F7WYJ6B)