Creating and managing calendars

[Discourse]

This guide explains how to create and manage calendars in Discourse using the Calendar (and Event) plugin.

Required user level: All users

Calendars are a powerful feature in Discourse that allow you to organize and display events within your community. This guide will walk you through the process of creating calendars, adding events, and managing them effectively.

Summary

• Enable the Calendar plugin
• Create a calendar in a topic or category
• Add events to your calendar
• Manage calendar options and settings
• Use the holiday calendar feature

Enabling the Calendar plugin

Before you can create calendars, ensure that the “Calendar (and Event)” plugin is enabled on your Discourse instance. For more details on enabling the plugin and its related settings, refer to the Discourse Calendar and Event plugin documentation.

Creating a calendar

Topic calendar

To embed a calendar in a topic:

1. Create a new topic or edit the first post of an existing topic

2. Add the following code on separate lines:

   [calendar]
   [/calendar]
   

3. Publish or update the post

The first day of the week defaults to Monday, but can be configured using the “calendar first day of week” site setting (options: Saturday, Sunday, or Monday).

Category calendar

To create a category-wide calendar:

1. Go to /admin/site_settings/category/discourse_calendar?filter=plugin=discourse-calendar

2. In the “calendar categories” setting, add an entry with the following format:

   categoryId=123;tzPicker;defaultView=month
   

   • Replace 123 with your category ID (found in the URL when viewing the category)

3. Add the category ID to the “events calendar categories” setting

4. Optionally, set “discourse post event allowed on groups” to control which groups can add events

Adding items to a calendar

Topic calendar

To add an event to a topic calendar:

1. Reply to the topic containing the calendar
2. Open the ⊕ options menu in the composer toolbar and use the “Insert date / time” function to add a date or date range
3. Add a description above the date
4. Submit the reply

The event will appear in the calendar after reloading the topic.

Category calendar

To add an event to a category calendar:

1. Create a new topic in the category
2. Open the ⊕ options menu in the composer toolbar and select “Create event”
3. Fill in the event details and publish

The event will appear on the category calendar.

Calendar options

You can customize your calendar using various options:

Option	Example	Description
Hide weekends	weekends="false"	Hides Saturday and Sunday
Hide specific days	hiddenDays="1,2"	Hides Monday and Tuesday (use 0-6 for Sunday-Saturday)
Set default view	defaultView="month"	Options: month, week, listNextYear
Ignore timezones	fullDay="true"	Treats all events as full-day events

Example usage:

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

Removing calendar items

Calendar items can be removed in these ways:

• Expired calendar items can be automatically removed using the “delete expired event posts after” setting
• Use topic timers to auto-delete replies
• Manually delete posts as needed

Holiday calendar

The holiday calendar is a special feature for managing site staff holidays:

1. Create a topic with a calendar in the first post
2. Set the “holiday calendar topic id” to the ID of this topic
3. Replies to this topic will be treated as vacation time for the posting user
4. Each reply must contain a date/time stamp added via the “Insert date / time” function in the composer ⊕ options menu for it to appear on the calendar
5. Vacation entries are automatically and randomly colored
6. An emoji (default: ) appears next to vacationing users’ names in user cards and @mentions
7. Optionally, include locale-specific holidays for users by enabling “calendar automatic holidays enabled”

FAQs

Q: Why do some events appear to span multiple days?
A: The calendar is always in UTC. Use the “all day event start time” and “all day event end time” settings to adjust for timezone differences.

Q: Can I control the colors of calendar entries?
A: For category calendars and upcoming events, you can assign colors by tag or category using the “map events to color” site setting. Holiday calendar entries are automatically and randomly colored and cannot be customized.

Q: How do I display past events in a list view?
A: There’s currently a bug when using defaultView=listNextYear that causes the initial view to be empty. As a workaround, users need to switch to monthly view, go back one month, and then return to list view to see past events.

Additional resources

• Discourse Calendar (and Event)
• Creating and managing events

Last edited by @j.jaffeux 2026-01-07T10:13:07Z

Last checked by @hugh 2024-07-02T09:35:23Z

Check document

Perform check on document: