MH Calendar

Summary

MH Calendar is an Obsidian plugin that adds a configurable calendar for notes, tasks, agendas, deadlines, recurring events, and embedded event lists. Events are read from Markdown frontmatter and displayed in multiple calendar views.

Purpose And Features

MH Calendar is meant for vaults that track dated work directly in notes. It supports:

• Years, year, quarter, month, week, and day views.
• Task and agenda event behavior.
• Single-day events, date ranges, deadline tasks, unscheduled events, and recurring events.
• Weekly, monthly, and yearly recurrence rules.
• Multiple calendars with color, icon, tag, folder, template, and enable/disable controls.
• Event quadrants for today, upcoming, overdue, past/completed, and unscheduled events.
• Important-event highlighting and task completion actions.
• Configurable event cards, timeline density, time colors, date highlighting, and mobile stats.
• Embedded event lists with the mh-calendar-events code block.
• Optional integration with MH-PERIODIC-NOTES for periodic-note indicators and actions.
• English and Portuguese locale files.

How It Works / How To Use

Open the calendar from the ribbon icon or the Open MH Calendar command. Use the header navigation to move between views, the calendar dots to enable or disable calendars, and the event panel to filter or sort events.

Events are Markdown notes. A note becomes an event when its tags frontmatter contains the tag configured for one of your calendars. The explicit event-behavior frontmatter value wins; if it is omitted, MH Calendar uses the matched calendar's default behavior.

Example agenda event:

---
title: Project review
tags:
  - calendar/agendas
event-behavior: agenda
startDate: 2026-07-10
startTime: "09:00"
endDate: 2026-07-10
endTime: "10:30"
important: true
---

Example deadline task:

---
title: Submit report
tags:
  - calendar/tasks
event-behavior: task
hasDeadline: true
endDate: 2026-07-15
endTime: "17:00"
completed: false
---

Example recurring agenda:

---
title: Weekly planning
tags:
  - calendar/agendas
event-behavior: agenda
recurrenceType: weekly
recurrenceDays:
  - mon
recurrenceStart: 2026-07-01
recurrenceEnd: 2026-12-31
startTime: "08:30"
endTime: "09:00"
---

Supported frontmatter:

• title: display title. If omitted, the note filename is used.
• tags: must include a configured calendar tag, with or without #.
• event-behavior or eventBehavior: agenda or task.
• startDate, endDate: dates in YYYY-MM-DD.
• startTime, endTime: times in HH:MM.
• hasDeadline: true for task deadlines that use endDate.
• completed, completedAt: task completion state.
• important: highlights the event.
• recurrenceType: weekly, monthly, or yearly.
• recurrenceDays: weekday names or numbers for weekly recurrence.
• recurrenceMonthDays: month days, ranges like 10-15, or last.
• recurrenceYearDates: dates like 10-07 or ranges like 01-07..05-07.
• recurrenceStart, recurrenceEnd: optional recurrence bounds.

Embedded event list example:

```mh-calendar-events
show: today, upcoming, overdue
filterBar: true
filterMode: pills
limit: 10
importantOnly: false
layout: list
```

Common code block options:

• show: comma-separated quadrants, or all.
• filterBar: show or hide the filter UI.
• filterMode: pills or dropdown.
• limit: total or per-category event limit.
• importantOnly: only show important events.
• layout: list or columns.
• fontSize: optional event-card font size for embedded lists.

Settings include language, 24-hour time, default view, unscheduled-event visibility, recurrence occurrence mode, auto-refresh interval, calendars, event-card appearance, week/day timeline density, current-date highlighting, important-event styling, mobile stats, code block click behavior, and periodic-note integration.

The settings tab uses the companion MH-API-TEMPORARY UI API. If that plugin is not enabled, the calendar still loads, but the settings UI shows a dependency notice.

Installation

For manual installation, copy these files into:

<vault>/.obsidian/plugins/mh-calendar/

Required install files:

• main.js
• manifest.json
• versions.json
• locales/en-us.json
• locales/pt-br.json

Restart Obsidian or reload plugins, then enable MH Calendar in Community Plugins.

Development

The source is TypeScript under src/. The generated Obsidian entrypoint is main.js; do not edit it manually.

Commands:

npm install
npm run dev
npm run typecheck
npm run build
node --check main.js

Build details:

• Entrypoint: src/main.ts
• Output: main.js
• Bundler: esbuild
• Type checker: typescript
• Production build: minified
• External dependency: obsidian