~/tilder/, Documentation/, Content types/, event

event - dated items with a place, upcoming or past

An event is a Markdown file named by its date, in a collection of type event: meetups, talks, releases. Its card says when and where; it is upcoming until its date has passed, then past, with no one touching the file. The collection lists its events in three ways, writes an RSS feed and an iCalendar file that calendar apps subscribe to.

An event collection may set these keys under [collections.<name>]; each has its default in the type's module, types/event.py.

An empty tag, upcoming_tag = "", leaves the card without one. defaults.toml already declares [collections.events], with feed = "events.xml" and calendar = "calendar.ics": creating content/events/ is enough to start. A second collection names its own:

[collections.talks]
type = "event"
nav = "talks"
feed = "talks.xml"
calendar = "talks.ics"
upcoming_tag = "soon"
none_upcoming = "No talk planned yet."

An event's file is named YYYY-MM-DD-slug.md, the date the event starts, as a post's is (post): the same folder form for images, the same .fr.md translations, the same errors for a date that does not exist.

An event lasts whole days. There is no key for an hour: write it in the description or in the page, and give the last day in end when it lasts more than one.

---
title: Spring meetup
description: Talks and a workshop on documentation, then dinner.
place: 1 Example Street, Exampleton
link: https://meetup.example/spring
end: 2099-03-02
lat: 48.8566
lon: 2.3522
---

Every other key of writing pages applies too. Give coordinates only when you know them: without them, the map link searches for the place instead.

The card shows the date as a <time>, running to end in words when the event lasts several days (Sunday 1 March 2099 - Monday 2 March 2099), the place, and the tag: upcoming_tag when the event starts today or later, past_tag once that day has gone by. In a list it shows the description and links to the event.

On the event's own page, the card also links to the event's site (link, labelled link_label) and to the place on the map (map_label): a marker at lat and lon when both are given, else a search for place. It is a link, not an embedded map, so no reader's browser calls another site unless they click it. The text mirror keeps the event's site and leaves the map link out: the address is on the card already, and the map's URL would not fit in 75 columns.

Three markers list a collection of events, all by the date of the build:

## Upcoming {upcoming}

## Past {past}

Each takes a collection's name, {upcoming:talks}, as every marker does (collections). An empty list shows none_upcoming or none_past.

"Today" is the day the site is built. An event moves from one list to the other only when the site is built again, so a site with events must be rebuilt every day. In watch mode, tilder rebuilds at midnight for this reason alone, even when no file has changed; the compose file of the deployment runs it that way. A site built by hand, or in CI, needs a daily build of its own. The build reads the day from the BUILD_TODAY environment variable when it is set, BUILD_TODAY=2099-03-01, which is how to preview the lists as they will be on another day.

With feed set, the collection's RSS feed lists every event, upcoming and past, the latest date first, each with its title, address, date and description; feed_title and feed_description name the channel. Each language has its own, under its prefix, as for posts (post).

With calendar set, the build writes an iCalendar file (RFC 5545) that calendar apps can subscribe to. It is written once, in the default language, and holds every event of the collection:

• each event as a whole-day VEVENT, from its date to its end or its date (DTEND is the day after, as the format wants), with its UID, the event's title followed by the calendar's name as SUMMARY, the place as LOCATION, lat and lon as GEO, its address as URL and its description;
• the calendar's own name, description, product identifier and time zone, from the [calendar] table: calendar.name, calendar.description, calendar.prodid, calendar.timezone, and calendar.uid_domain for the identifiers. Their defaults are on the collections page.

The text is folded to ASCII and cut into lines of 75 octets, as the format requires.

An event's body is wrapped in <article>. Its JSON-LD node is an Event: name, description, startDate (the date), endDate (end, else the date), a scheduled, in-person event, its location as a Place named by place (with geo from lat and lon), the site's organisation as organizer, and the preview image. Its og:type is website.

• collections
• post
• feeds and images
• the command line