Persian Calendar

فارسی / English

"Persian Calendar" Plugin for Obsidian

This plugin adds the Solar Hijri calendar alongside the Gregorian and Lunar Hijri calendars to Obsidian, offering Iranian users a more pleasant journaling experience.

• Guide to the Essential Features
• Collaboration and Project Participation

Installation Guide

First method (recommended)

You can install this plugin by searching for Persian Calendar in Obsidian's Community plugins.

Second method

You can visit the Releases section of this GitHub page, download the plugin's executable files -main.js, manifest.json and styles.css- and move them to the following path:

[Your Vault Address]/.obsidian/plugins/persian-calendar

Guide to the Essential Features

• Dynamic Paths
• Quick Reference to Calendar Notes
• Placeholders
• Using the Dedicated API
• Other Features

Dynamic Paths and Naming

You can use dynamic placeholders to customize the paths and filenames of your calendar notes.

Quick Reference to Calendar Notes

Use @ to insert a link to a calendar note, or @/ to insert the resolved date as plain text without creating a link.

• Days: امروز، دیروز، فردا، پریروز، پس‌فردا
• Days of the week: (نام روز جاری)، روز بعد، روز قبل
• Weeks: این هفته، هفته قبل، هفته بعد
• Months: این ماه، ماه قبل، ماه بعد
• Seasons: این فصل، فصل قبل، فصل بعد
• Years: امسال، سال قبل، سال بعد

You can also select the desired phrase in the text and link it to the corresponding note by executing the related command.

Placeholders

By inserting the following placeholders into your note templates, you can include your desired text in the final result.

By typing {{}} you can receive suggestions for choosing your placeholder.

Daily Note Placeholders

Only replaced in daily notes.

Weekly Placeholders

Work in daily notes and weekly notes.

Monthly Placeholders

Work in daily notes and monthly notes.

Seasonal Placeholders

Work in daily notes, monthly notes, and seasonal notes.

Yearly Placeholders

Work in daily, weekly, monthly, and yearly notes.

Current Time Placeholders

These always return today's date, regardless of the note type.

Elapsed and Remaining Days

By default, calculated relative to the daily note's date; if placed in a non-daily note, they use today's date.

Using the Dedicated API

This plugin provides a public API so you can use features like date and number conversion in other plugins and scripts (such as DataviewJS or Templater).

const pcApi = app.plugins.getPlugin("persian-calendar").api;

// Number conversion
pcApi.toEnNumber("۱۲۳ تست test"); // "123 تست test"
pcApi.toFaNumber("123 تست test"); // "۱۲۳ تست test"

// Solar Hijri date conversion
pcApi.jalaliToDate(1405, 9, 13); // Equivalent Gregorian date as Date object
pcApi.jalaliToGregorian(1405, 9, 13); // {gy: 2026, gm: 12, gd: 4}
pcApi.jalaliToHijri(1405, 9, 13); // (Iran basis) {hy: 1448, hm: 6, hd: 24}
pcApi.jalaliToHijri(1405, 9, 13, { base: "umalqura" }); // (Umm al-Qura basis) {hy: 1448, hm: 6, hd: 24}
pcApi.jalaliMonthName(9); // آذر (Azar)
pcApi.jalaliMonthName(9, "en"); // Azar
pcApi.seasonName(3); // پاییز (Autumn)
pcApi.seasonName(3, "en"); // Autumn

// Gregorian date conversion
pcApi.dateToGregorian(new Date()); // {gy, gm, gd}
pcApi.gregorianToDate(2026, 12, 4); // Date object
pcApi.gregorianToJalali(2026, 12, 4); // {jy: 1405, jm: 9, jd: 13}
pcApi.gregorianToHijri(2026, 12, 4); // (Iran) {hy: 1448, hm: 6, hd: 24}
pcApi.gregorianToHijri(2026, 12, 4, { base: "umalqura" }); // (Umm al-Qura) {hy: 1448, hm: 6, hd: 24}

// Lunar Hijri date conversion (Iran basis)
pcApi.hijriToDate(1448, 6, 24); // Date object
pcApi.hijriToGregorian(1448, 6, 24); // {gy: 2026, gm: 12, gd: 4}
pcApi.hijriToJalali(1448, 6, 24); // {jy: 1405, jm: 9, jd: 13}

// Lunar Hijri date conversion (Umm al-Qura basis)
pcApi.hijriToDate(1448, 6, 24, { base: "umalqura" }); // Date object
pcApi.hijriToGregorian(1448, 6, 24, { base: "umalqura" }); // {gy: 2026, gm: 12, gd: 4}
pcApi.hijriToJalali(1448, 6, 24, { base: "umalqura" }); // {jy: 1405, jm: 9, jd: 13}

// Events
pcApi.checkHoliday(new Date()); // Is it a holiday? true/false
pcApi.dateToEvents(new Date()); // Array of {title(fa/en), categories, isHolidayInIran}
pcApi.dateToEvents(new Date(), { base: "umalqura" }); // With Umm al-Qura basis

Other Features

• scales responsively with the sidebar width
• Display of official Iranian holidays on the calendar
• Display of Iran's official calendar events and international observances
• Option to "Open today's daily note on startup," user configurable
• Customizable display of calendar events
• Option to create and display seasonal notes, user configurable
• Choose whether weekly notes use the Gregorian or Jalali week numbering system.
• For better compatibility with other Gregorian calendar plugins, you can use Gregorian naming for Jalali monthly and yearly notes.
• Confirmation dialog before creating calendar notes, user configurable
• Option to set the user interface to Persian or English
• Ability to configure calendar note templates
• Ability to set the Lunar Hijri calendar based on Iran's Crescent Committee or Saudi Arabia's Umm al-Qura
• Option to display the Gregorian or Lunar Hijri calendar as supplementary calendars
• Ability to use a dedicated date picker when setting a property with type date
• Users can use this plugin's default font named "Persian Calendar"

Collaboration and Project Participation

This plugin has been developed with love, for non-commercial purposes, and under this license.

You can support our continued efforts in the following ways:

• Contribute to the development of this plugin
• Report bugs or suggest a feature for development via the Issues section on this GitHub page
• Recommend installing and using this plugin to your friends
• Follow our website and Telegram channel