Create Calendars

:information_source: Calendars are a feature of the Calendar (and Event) plugin. You can find more detail about how to enable them as well as their related settings in: Discourse Calendar (and Event)

Creating a calendar

To embed a calendar, add the following to the first post of a topic (note the separate lines):


:information_source: Monday is considered the first day of the week, regardless of the viewer’s locale settings. This is currently not configurable.

Additional calendar options

Option Example Values
Hide weekends weekends="false"
Hide specific days hiddenDays="1,2" 0-6 for Sunday-Saturday, respectively
Set the default view defaultView="basicWeek" month, basicWeek, listNextYear
Ignore timezones fullDay="true"

For example:

[calendar weekends="false" hiddenDays="1,2" defaultView="basicWeek" fullDay="true"]

Adding items to a calendar

To add items to a calendar, use the Insert Date function in the composer to insert a single date or date range in a reply to the topic:

And any text included above the date will be used to describe the calendar entry:

Once the reply is submitted, the entry is added to the calendar and will be displayed after a reload of the topic.

:information_source: The calendar is always in UTC, so events that are a 24-hour single day in your timezone may appear to span multiple days. The settings all day event start time and all day event end time can be used to reduce this impact.

Deleting calendar items

Expired calendar items can be removed from the calendar automatically using the delete expired event posts after setting. You can also use the topic timer to auto-delete replies, or manually delete the posts as normal.

Holiday Calendar

There is an optional, special “holiday calendar”, primarily intended to help manage site staff holidays.

This is controlled by the setting holiday calendar topic id. By setting holiday_calendar_topic_id to the ID of a topic which has a calendar in the top post, that calendar becomes special — instead of regular calendar entries, any replies will be taken as “vacation time” for that user. These entries will be automatically (and randomly) colored.

:information_source: It is not currently possible to control the colors, nor to get colored entries in the normal type of calendar.

Additionally, an emoji will appear next to the names of people on vacation in their user cards and when @mentioned in a post. The default is :date: but it can be changed through the setting holiday_status_emoji. This is visible to anyone (logged in or not).

holiday icon (usercard) holiday icon (mention)

The calendar will also by default include an entry for every user for every holiday in that user’s locale, if they’ve set one. This can be toggled off using calendar automatic holidays enabled.

And there you go. :slight_smile: If you have any questions please ask them below, or create a support, bug, feature, or ux topic as appropriate.


I have a hard time understanding how to create a calendar so that it displays in a category, and what to do to fill it once it’s there. For topics, it is quite straightforward, but the category case is more obscure. Can someone give an example?

Create a Category Calendar

The difference between a topic calendar and a category calendar is that the former uses add date from a specific topic response, and displays the calendar in the topic itself, while the latter uses create event in any topic of the configured category, and displays the events calendar in the category.

1. Enable the calendar plugin

In /admin/site_settings/category/discourse_calendar?filter=plugin%3Adiscourse-calendarcalendar categories:

You want something like: categoryId=123;postId=4949;tzPicker;defaultView=month

  • categoryId is easy to find: it’s the number in the URL when you click the #category

  • postId can be found like this: go to the category description (the “About category” pinned topic) and append .json to the URL: the postId is at the beginning of the JSON file.

  • Review the discourse-calendar documentation for available options.

  • Add the category (numbered 123 in our example) to events calendar categories

You may want to set discourse post event allowed on groups to include the groups you want to be able to add events.

2. Create an event

You can create a new topic in category 123 and create event (from the gear button).

The event will then appear on the category calendar.