Hugo iCalendar Theme Component

A Hugo theme component to generate iCalendar files from your Hugo content.

This project provides a set of simple templates for Hugo to generate iCalendar files. It follows the 80/20 rule with a special focus on event data and strives to be RFC compliant.

Original work: This theme component is based on hugo-ical-templates by Raoul B.

Installation

1. Add Hugo module

Add this theme component as a Hugo module to your project's hugo.toml config file:

[module]
[[module.imports]]
path = 'github.com/finkregh/hugo-theme-component-ical'

Fetch or update the configured modules:

# if you did not already do this before (change the domain/url)
hugo mod init yourdomain.com

hugo mod get -u ./...

2. Configure output formats

You need to configure the Calendar and CalendarWithAlarms output formats in your config:

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

[outputFormats.Calendar]
  baseName = "calendar"
  mediaType = "text/calendar"
  isPlainText = true
  permalinkable = true
  suffix = "ics"
  # Avoid webcal scheme
  protocol = "https://"

[outputFormats.CalendarWithAlarms]
  baseName = "calendar-alarms"
  mediaType = "text/calendar"
  isPlainText = true
  permalinkable = true
  suffix = "ics"
  # Avoid webcal scheme
  protocol = "https://"

The CalendarWithAlarms output format generates iCalendar files that include alarm/reminder components (VALARM) in addition to the event data. This allows calendar applications to display notifications and reminders for events at specified times before the event starts.

4. Link to calendar files

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

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

For calendars with alarms:

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

5. (optional) display calendar via javascript

Some javascript libraries are used to display the calendar entries visually. They are downloaded from npmjs.org when the site is built and then served from here.

If you do not want to display the calendar entries on your website you can skip this section.

With npm

# Initial setup (after hugo mod get from above)
hugo mod npm pack
npm update

# To get the latest version later
npm update

The generated (minified) javascript file can be served as a separate file or directly inside the respective webpage:

<!-- separate .js file -->
  <!-- Begin calendar javascript -->
  {{ partial "vendor/finkregh/ical/js.html" . }}
  <!-- End calendar javascript -->

<!-- inside the html -->
  <!-- Begin calendar javascript -->
  {{ partial "vendor/finkregh/ical/js-inline.html" . }}
  <!-- End calendar javascript -->

This generates:

if the page has a calendar entry (if and (.OutputFormats.Get "Calendar") (eq .Type "events")):
- <meta http-equiv="Content-Security-Policy" content="font-src data:" />
- JS referenced by a file or inline

Inline does not required an additional request, not-inline does make the HTML bigger (on every page where a calendar exists). Decide for yourself what to use.

Either way the javascript will only be included in places where a calendar entry exists and it will not require loading anything from a third party (besides when building the static files).

Prepared partial

The component provides a partial you can include in your layouts/events/.

single.html:

{{ partial "vendor/finkregh/ical/events/single.html" . }}

list.html:

{{ partial "vendor/finkregh/ical/events/list.html" . }}

Without npm

If you do not have npm installed a pre-built file is also available which you can insert into your templates:

Warning

This has been created manually and will not be updated with each release, use with caution!

{{ $prebuilt := resources.Get "js/vendor/finkregh/ical/minified.min.2c0b8eb566757daf33d80723a369c40de708920b6faeb3f6016302e4d986635d" | resources.Fingerprint "sha256"}}
<script src="{{ $prebuilt.Permalink }}" type="module" {{ if $isProd }}integrity="{{ $prebuilt.Data.Integrity }}"{{ end }} defer></script>

Alternatlively load the javascript from a third party (the versions here might be outdated too!):

<script src="https://cdn.jsdelivr.net/npm/[email protected]/index.global.min.js"></script>
<script src=" https://cdn.jsdelivr.net/npm/@fullcalendar/[email protected]/index.global.min.js "></script>
<script src="https://cdn.jsdelivr.net/npm/@fullcalendar/[email protected]/locales-all.global.min.js"></script>
<script src="https://unpkg.com/ical.js/dist/ical.es5.min.cjs"></script>
{{ $themejs := resources.Get "js/vendor/finkregh/ical/script.js" | js.Build $options | resources.Minify | resources.Fingerprint "sha256"}}
<script src="{{ $themejs.Permalink }}" type="module" {{ if $isProd }}integrity="{{ $themejs.Data.Integrity }}"{{ end }} defer></script>

Event specification

The events are specified in the fontmatter, all parts are optional from the templating perspective, you as the user need to be aware what is required.

The time format is {YEAR}-{MONTH}-{DAY}T{HOUR}:{MINUTE}:{SECOND}+{TIMEZONE_HOUR}:{TIMEZONE_MINUTE}.

---
title: Important Event!11

# First occurrence, this also defines the timeframe for the calendar entry
startDate: 2024-01-08T09:00:00+01:00
endDate:   2024-01-08T09:30:00+01:00
# Location
where: "Meeting Room 1, Main Office"
# Who created the event
orga: "Scrum Master"
# Contact
orgaEmail: "[email protected]"
---

You might want to look into the specifications (RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar), RFC 7986: New Properties for iCalendar) as the examples here only show part of what is possible.

Recurrence

The RRULE implementation supports YEARLY and MONTHLY frequencies with BYMONTH, BYDAY, and BYSETPOS components.

Every monday

# Every Monday
recurrenceRule:
  freq: "WEEKLY"
  byDay: "MO"

Third Sunday of April (yearly)

recurrenceRule:
  freq: "YEARLY"
  byMonth: 4
  byDay: "SU"
  bySetPos: 3

Generates: RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=SU;BYSETPOS=3

First and second Monday of October (yearly)

recurrenceRule:
  freq: "YEARLY"
  byMonth: 10
  byDay: "MO"
  bySetPos: [1, 2]

Generates: RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=MO;BYSETPOS=1,2

Every last Sunday of every 3 months

recurrenceRule:
  freq: "MONTHLY"
  interval: 3
  byDay: "SU"
  bySetPos: -1

Generates: RRULE:FREQ=MONTHLY;INTERVAL=3;BYDAY=SU;BYSETPOS=-1

Alarm settings

The VALARM implementation supports DISPLAY, EMAIL, and AUDIO alarms with flexible trigger configurations.

Note

I did not test these, so try not to wake up (others) in the middle of the night ;-)

Display Alarm (Popup Reminder)

alarms:
  - action: "DISPLAY"
    trigger:
      duration: "-PT15M"  # 15 minutes before event start
    description:
      text: "Meeting starts in 15 minutes"
      lang: "en"

Email Alarm with Multiple Recipients

alarms:
  - action: "EMAIL"
    trigger:
      duration: "-PT1H"   # 1 hour before event start
    description:
      text: "Don't forget about the meeting in 1 hour"
      lang: "en"
    summary:
      text: "Meeting Reminder"
      lang: "en"
    attendee:
      - email: "[email protected]"
        commonName: "Ahmed Doe"
      - email: "[email protected]"
        commonName: "Jane Smith"

Duration Format Reference

Duration values use ISO 8601 duration format:

PT15M = 15 minutes
PT1H = 1 hour
P1D = 1 day
P1W = 1 week
-PT15M = 15 minutes before (negative for "before")
PT15M = 15 minutes after (positive for "after")

About

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.

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

Development

PRs, issues, comments, etc. are welcome!

You can use the setup in .github/exampleSite/ to test things locally.

Directory structure:

.github/exampleSite/
- example implementation, also used to generate the demo site
.github/scripts/
- python script used in the CI to validate the generated .ics files
.github/workflows/
- tests, deployment of the demo site
assets/js/vendor/finkregh/ical/
- JavaScript files
assets/saas/vendor/finkregh/ical/
- unused
layouts/*.ics, layouts/_partials/events/, layouts/_partials/ical/
- various parts to generate the .ics files
layouts/_partials/vendor/finkregh/ical/js{,-inline}.html
- <script ...> to get all required JS
layouts/_partials/vendor/finkregh/ical/events/
- example template for single/list views

Specification

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

Implementation Status

From rfc 5545

3.2. Property Parameters

3.3. Property Value Data Types

3.6. Calendar Components

3.8. Component Properties

3.8.1. Descriptive Component Properties

3.8.2. Date and Time Component Properties

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.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

From rfc 7986

5. Properties

6. Property Parameters

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

This hugo theme component was scaffolded with the cookiecutter-hugo-theme-component template.

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
.github		.github
assets		assets
layouts		layouts
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
cog.toml		cog.toml
go.mod		go.mod
hugo.toml		hugo.toml
justfile		justfile
package-lock.json		package-lock.json
package.hugo.json		package.hugo.json
package.json		package.json
renovate.json5		renovate.json5
theme.toml		theme.toml

License

Finkregh/hugo-theme-component-ical

Folders and files

Latest commit

History

Repository files navigation

Hugo iCalendar Theme Component

Installation

1. Add Hugo module

2. Configure output formats

4. Link to calendar files

5. (optional) display calendar via javascript

With npm

Prepared partial

Without npm

Event specification

Recurrence

Every monday

Third Sunday of April (yearly)

First and second Monday of October (yearly)

Every last Sunday of every 3 months

Alarm settings

Display Alarm (Popup Reminder)

Email Alarm with Multiple Recipients

Duration Format Reference

About

Known Issues

No folding of long lines

No CRLF line termination

Development

Specification

Implementation Status

3.2. Property Parameters

3.3. Property Value Data Types

3.6. Calendar Components

3.8. Component Properties

3.8.1. Descriptive Component Properties

3.8.2. Date and Time Component Properties

3.8.4. Relationship Component Properties

3.8.5. Recurrence Component Properties

3.8.7. Change Management Component Properties

5. Properties

6. Property Parameters

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Contributors 2

Languages

No `CRLF` line termination

Packages