Documenteer de Discourse Calendar plugin beter

[mattdm (Matthew Miller)]

Continuing the discussion from Discourse Calendar — since my post there is about to get auto-deleted after a month.

The top post describing this plugin needs some work. It’s really confusing. Specifically:

Event Confusion

There seem to be three separate things all called “event”:

1. Most basic: a reply with a [date] , which gets shown in a calendar in the first post in the topic.
2. A first-post-in topic which contains [event], used by the optional “alpha state” feature separately described here.
3. A completely separate plugin with a similar name: Events instead of Event.

That’s… confusing.

Unclear syntax for the basic single-topic event

1. How does one set the name of the event? The plugin description shows text with events, but not how that actually got set.
2. How does one create repeating events?
3. The holiday calendar shows colors. Can the regular calendar have colors too, and if so, how?
4. The separate “events” feature can apparently produce an ical feed. Can a “basic” calendar?

More questions about the holiday calendar

Does that use the same syntax as the per-topic calendar, or the “event” one? Is it limited to “staff holidays”, or could it be used by anyone who can reply to a given topic? Where do the colors come from? Is the “Holiday flair” emoji changeable? Is it possible to make that visible to anyone, or to some arbitrary group, not just staff?

Etc…

Some of this I’ve figured out on my own or by asking support. But it really needs to be documented in the plugin documentation topic.

It would probably also be good to spell out some of the limitations, too — week-start-date doesn’t follow your locale and isnt’ configurable, the whole thing is confused about timezones… and if there’s a roadmap or plans to address some of these things or add new features (or if there isn’t!), please say that as well.

Thank you! This is a nifty little Discourse feature which could be super-useful to a lot of people, but it’s also pretty confusing.

[nathank (Nathan Kershaw)]

That post is a wiki - so you can make your own contributions to it easily. That would be very helpful for all.

[mattdm (Matthew Miller)]

I can, although some things will just be guesses!

[JammyDodger]

I spotted this in Related Topics while having a refresh of the Calendar and Event topics (another win for Related Topics )

I’ve just rejigged them so both features now appear properly as one plugin topic, which should hopefully remove some confusion:

Discourse Calendar (and Event)

Summary Discourse Calendar and Event adds dynamic and interactive calendar and event features to your Discourse site. Install Guide This plugin is bundled with Discourse core. There is no need to install the plugin separately. Enabling Calendar (and Event) The Calendar plugin can be enabled either by the toggle or from its settings, both accessible from your admin/plugins page: [/admin/plugins] Features Somewhat unsurprisingly, Discourse Calendar …

I’ve also split a lot of the ‘how to’ details into a couple of guides to give them some breathing space:

Creating and managing calendars

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 you…

Creating and managing events

This guide explains how to create and manage events using the Calendar (and Event) plugin in Discourse. It covers how to create events, set event options, interact with events, and view the upcoming events calendar. Required user level: All users (with appropriate permissions) Enabling events Events are a feature of the Calendar (and Event) plugin. To use this feature: Enable the Calendar (and Event) plugin Configure related settings For detailed instruct…

The main focus was to give them some more consistent structure (though I’ve thrown in a quick refresh for good measure). They were a little thorny to smooth out, but I think they’re in a better shape than they were. Having slept on it, I think there are a few things I’d still like to do so I won’t break out the just yet.

But hopefully we’re moving in the right direction.