Hugo iCalendar Templates

About

A set of simple templates for Hugo to generate iCalendar files.

This project does not provide a complete implementation of all features the iCalendar specification contains. It rather follows the 80/20 rule and with a special focus on event data.

All the templates strive to be RFC compliant and produce output files that adhere to the specification. No special hacks are included to work around broken calendar software or the like.

This project does not provide a full turn-key solution and some assembly will be required in most cases. Understanding of Hugo and especially Hugo's templating system is still recommended.

The system is highly flexible and should adapt or extend easily to more exotic use cases. On some spots the chosen defaults might be a bit opinionated.

The partial template snippets from this project should help to easily avoid the most common mistakes when creating ics files. However, there is absolutely no validation, neither on the syntactic nor the semantic level. You can always use an external validation service to check the output.

Usage

Step 1

Copy the partial templates from src/layouts/partials/ical/*.ics to your project's layout directory. Usually this would be .../layouts/partials/ical/.

See also (Hugo documentation):

partials

Step 2

Have template files for the Calendar output format. Examples for a single page (single.calendar.ics) and a list page (list.calendar.ics) can be found in this repository.

See also (Hugo documentation):

Step 3

Activate and configure the Calendar output format, either in your config.toml or more with fine-grained control via the content front matter.

For example (in toml syntax) activate via:

[outputs]
  page = ["HTML", "Calendar"]
  section = ["HTML", "Calendar"]

You need to configure this output format a bit:

[outputFormats.Calendar]
  baseName = "calendar"
  # Avoid unencrypted webcal scheme
  protocol = "https://"
  permalinkable = true

See also (Hugo documentation):

configure output formats

Step 4

Feed in your own data from arbitrary Hugo context variables into the calendar templates from step 2. See the header.ics and event.ics files in this repository for a simple example.

Note: While it can be unavoidable for certain edge cases to directly adapt the top level partials from step 2 this should in general not be necessary.

Collect and add all timezone definitions you need to the timezone.ics partial.

Note: You can download ready-made ics files for all well known time zones from http://tzurl.org.

For example for Europe/Zurich:

http://tzurl.org/zoneinfo-outlook/Europe/Zurich

Step 5

Link the generated ics files for download on your html pages.

A snippet like this should do:

{{ with .OutputFormats.Get "Calendar" }}
    <a href="{{ .RelPermalink }}" type="text/calendar">{{ $.Title }}</a>
{{ end }}

See also (Hugo documentation):

Demo Site

A fully working minimal site can be found in this repository.

Known Issues

No folding of long lines

Due to the way the templates work, we do not fold long lines. However, this is actually fine as the RFC writes SHOULD instead of MUST:

Lines of text SHOULD NOT be longer than 75 octets, excluding the line break. Long content lines SHOULD be split into a multiple line representations using a line "folding" technique.

See: https://tools.ietf.org/html/rfc5545#section-3.1

No `CRLF` line termination

This is the one place where we knowingly break RFC compliance. While this is not correct per se, it hopefully is a minor issue with today's calendar software.

The iCalendar object is organized into individual lines of text, called content lines. Content lines are delimited by a line break, which is a CRLF sequence (CR character followed by LF character).

See: https://tools.ietf.org/html/rfc5545#section-3.1

Empty lines

The generated ics files often contain many completely empty lines. This could in principle be avoided by more careful whitespace control inside the templates or some post processing. (Unfortunately Hugo does not come with a suitable asset minification method.)

Major TODO

Recurrence rules
Timezone component

In principle all missing parts (properties, parameters, components) could be handled by the same way. They were just not in focus for the primary application envisioned: distributing machine-readable information about upcoming events directly from within Hugo.

Specification

RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar)
RFC 7986: New Properties for iCalendar

Implementation Status

Note: This list tracks the implementation by partial template snippets. Some properties like 3.7.x are hardcoded in the top level templates. The Time Zone Component is handled differently (see step 4 above).

From rfc 5545

3.2. Property Parameters

3.3. Property Value Data Types

3.6. Calendar Components

3.7. Calendar Properties

3.7.1. Calendar Scale
3.7.2. Method
3.7.3. Product Identifier
3.7.4. Version

3.8. Component Properties

3.8.1. Descriptive Component Properties

3.8.2. Date and Time Component Properties

3.8.3. Time Zone Component Properties

3.8.3.1. Time Zone Identifier
3.8.3.2. Time Zone Name
3.8.3.3. Time Zone Offset From
3.8.3.4. Time Zone Offset To
3.8.3.5. Time Zone URL

3.8.4. Relationship Component Properties

3.8.5. Recurrence Component Properties

3.8.5.1. Exception Date-Times
3.8.5.2. Recurrence Date-Times
3.8.5.3. Recurrence Rule

3.8.6. Alarm Component Properties

3.8.6.1. Action
3.8.6.2. Repeat Count
3.8.6.3. Trigger

3.8.7. Change Management Component Properties

3.8.7.1. Date-Time Created
3.8.7.2. Date-Time Stamp
3.8.7.3. Last Modified
3.8.7.4. Sequence Number

3.8.8. Miscellaneous Component Properties

3.8.8.1. IANA Properties
3.8.8.2. Non-Standard Properties
3.8.8.3. Request Status

From rfc 7986

Properties

Property Parameters

6.1. DISPLAY Property Parameter
6.2. EMAIL Property Parameter
6.3. FEATURE Property Parameter
6.4. LABEL Property Parameter

Etc

Hopefully, this whole project will some day be superseded by something better, maybe even directly built into Hugo.

raoulb/hugo-ical-templates

Hugo iCalendar Templates

About

Usage

Step 1

Step 2

Step 3

Step 4

Step 5

Demo Site

Known Issues

No folding of long lines

No CRLF line termination

Empty lines

Major TODO

Specification

Implementation Status

Etc

No `CRLF` line termination