jekyll-theme-conference 4.1.0 → 5.0.0

data/README.md

@@ -20,7 +20,7 @@ The theme was created for the yearly Winterkongress conference of the [Digital S
 - [Demo: Winterkongress](https://winterkongress.ch/)
 
 > [!WARNING]
-> If you were using the theme up to version 3, please note the changes to migrate to the new version 4 in the [upgrade guide](UPGRADE_GUIDE.md).
+> If you upgrade from an earlier major version, please note the necessary changes in the [upgrade guide](UPGRADE_GUIDE.md).
 
 
 ## Table of Contents
@@ -29,38 +29,40 @@ The theme was created for the yearly Winterkongress conference of the [Digital S
   - [Gem-based Method](#gem-based-method)
   - [Remote Theme Method](#remote-theme-method)
 - [Setup](#setup)
-  - [Automatic Import](#automatic-import)
+  - [Import from pretalx](#import-from-pretalx)
   - [Automatic Build](#automatic-build)
 - [Configuration](#configuration)
-  - [Theme Verification](#theme-verification)
+  - [Error Checks](#error-checks)
   - [Collection URLs](#collection-urls)
   - [Language](#language)
   - [Timezone](#timezone)
   - [Navigation Bar](#navigation-bar)
-  - [Meta Data for Search Engines and Link Previews](#meta-data-for-search-engines-and-link-previews)
-  - [Main Landing Page](#main-landing-page)
-  - [Information Boxes & Modals](#information-boxes--modals)
+  - [Meta Data](#meta-data)
+  - [Information Bars & Modals](#information-bars--modals)
   - [Live Indications & Streaming](#live-indications--streaming)
   - [Progressive Web App (PWA)](#progressive-web-app-pwa)
-  - [Talk Settings](#talk-settings)
-  - [Location Settings](#location-settings)
-  - [Program Settings](#program-settings)
+  - [Tracks & Tags](#tracks--tags)
+  - [Landing Page](#landing-page)
+  - [Location Page](#location-page)
+  - [Program Page](#program-page)
+  - [Editions](#editions)
 - [Content](#content)
   - [Schedule / Program](#schedule--program)
   - [Talks](#talks)
   - [Speakers](#speakers)
   - [Rooms](#rooms)
   - [Links](#links)
-  - [Overview Pages](#overview-pages)
-  - [Additional Pages](#additional-pages)
+  - [Pages](#pages)
 - [Design](#design)
   - [Pre-compiled Bundle (Default)](#pre-compiled-bundle-default)
   - [Split Bundle (Custom Bootstrap CSS)](#split-bundle-custom-bootstrap-css)
+  - [Full Custom Build (Custom SCSS)](#full-custom-build-custom-scss)
   - [Icons](#icons)
-- [JavaScript](#javascript)
+- [Custom JavaScript](#custom-javascript)
 - [Development](#development)
   - [Jekyll Theme Development](#jekyll-theme-development)
   - [JavaScript & CSS Development](#javascript--css-development)
+  - [Tests](#tests)
 - [License](#license)
 
 
@@ -128,50 +130,39 @@ To install:
    bundle
    ```
 
-4. Add `remote_theme: "DigitaleGesellschaft/jekyll-theme-conference@v4.0.1"` to your `_config.yml` file. Remove any other `theme:` or `remote_theme:` entry.
+4. Add `remote_theme: "DigitaleGesellschaft/jekyll-theme-conference@v5.0.0"` to your `_config.yml` file. Remove any other `theme:` or `remote_theme:` entry.
 
    ```yaml
-   remote_theme: "DigitaleGesellschaft/jekyll-theme-conference@v4.0.2"
+   remote_theme: "DigitaleGesellschaft/jekyll-theme-conference@v5.0.0"
    ```
 
 5. Continue with the [_Setup_](#setup) section below to customize the theme and add content for your conference.
 
-To update the theme, change the version tag in the `remote_theme` value (e.g., `@v4.0.0` to `@v4.1.0`).
+To update the theme, change the version tag in the `remote_theme` value (e.g., `@v4.1.0` to `@v5.0.0`).
 
 
 ## Setup
 
-The different talks, speakers and rooms are stored as a collection of files. Each file contains a small header in form of a YAML block (called [FrontMatter](https://jekyllrb.com/docs/front-matter/)) used to store additional information beside a description. Their exact use and meaning is described further below in the section [_Content_](#content). Additional configuration options can be found in the section [_Configuration_](#configuration).
-
-The schedule defining when and in which room a talk takes place is stored as a [YAML data file](https://jekyllrb.com/docs/datafiles/) under `_data/program.yml`. For further details about it see below in the section [_Content_](#content).
+Add the talks, speakers, rooms and the schedule of your conference as described in the section [_Content_](#content), and adapt the theme as described in the section [_Configuration_](#configuration). The tools below import them or build the site for you.
 
 > [!TIP]
 > Please note that the generated website can be large containing many unnecessary whitespaces. It is recommended to minimize the generated output files before uploading them to a server (e.g., with [minify](https://github.com/tdewolff/minify)).
 
-### Automatic Import
+### Import from pretalx
 
 In this repository, you'll find the Python file `_tools/import_schedule.py`. This script allows you to import content from a [frab](https://github.com/frab/frab/wiki/Manual#introduction)-compatible JSON file, such as those exported from [pretalx.com](https://pretalx.com/p/about/).
 
 1. Copy the files `_tools/import_schedule.py` and `_tools/requirements.txt` from this repository
 
-2. Create a virtual environment and activate it
-
-   ```bash
-   python -m venv .venv
-   source .venv/bin/activate
-   ```
-
-3. Install the requirements
+2. Execute the script with [uv](https://docs.astral.sh/uv/), which installs the requirements, e.g., to show the help type
 
    ```bash
-   pip install -r _tools/requirements.txt
+   uv run --no-project --with-requirements _tools/requirements.txt python _tools/import_schedule.py --help
    ```
 
-4. Execute the script, e.g., to show the help type
+   With several [editions](#editions), pass the edition's id, e.g. `--edition 2026`: the script then writes to `_talks/2026/`, …, `_data/programs/2026.yml` and creates the edition's overview pages.
 
-   ```bash
-   python _tools/import_schedule.py --help
-   ```
+Likewise, `_tools/import_resources.py` imports resources such as slides and other documents from [pretalx.com](https://pretalx.com/p/about/) via its API. It downloads all files, stores them and updates the links of the talks concerned (see [_Links_](#links)). Run it the same way, e.g., `uv run --no-project --with-requirements _tools/requirements.txt python _tools/import_resources.py --help`. With several [editions](#editions), pass the edition's folders, e.g. `--file-folder 2026/documents/slides/ --talk-folder _talks/2026/`.
 
 ### Automatic Build
 
@@ -179,11 +170,13 @@ If you prefer not to install the full Ruby/Jekyll toolchain locally, you can lev
 
 - `build.yml`: This workflow automatically builds and optimizes the website whenever a new tag starting with `v` (e.g., `v2020.01.01`) is added. It then attaches the generated website as an archive to a release for easy download.
 - `test.yml`: This workflow automatically attempts to build the website upon a new pull request, making it suitable for use as a status check before merging.
-- `schedule.yml`: This workflow automatically generates schedule and content files when a new pull request includes a `schedule.json` file (refer to the 'Automatic Import' section for details). This enables quick content updates from [pretalx.com](https://pretalx.com/p/about/) exports.
+- `schedule.yml`: This workflow automatically generates schedule and content files when a new pull request includes a `schedule.json` file (see [_Import from pretalx_](#import-from-pretalx)). This enables quick content updates from [pretalx.com](https://pretalx.com/p/about/) exports. With several [editions](#editions), set its `EDITION` variable to the id of the edition to import.
 
 To get started, simply copy the desired workflow file to your repository and adapt it to your needs:
 
 - `_tools/build.yml` -> `.github/workflows/build.yml`
+- `_tools/test.yml` -> `.github/workflows/test.yml`
+- `_tools/schedule.yml` -> `.github/workflows/schedule.yml`
 
 > [!IMPORTANT]
 > Please note that the `Gemfile.lock` of your project must be adapted to include specific versions required by GitHub's workflow server, i.e., run `bundle lock --add-platform x86_64-linux` to add support for them.
@@ -191,9 +184,9 @@ To get started, simply copy the desired workflow file to your repository and ada
 
 ## Configuration
 
-All configurations and customization for this theme are stored under the `conference` property in the `_config.yml` file. You can find an example configuration containing most of the here discussed parameters under `_config.example.yml` in this repository.
+Most settings of this theme are stored under the `conference` property in the `_config.yml` file. Some are Jekyll's own settings at the top level (e.g. `timezone`), and the settings of the main landing page, the location page and the program page are stored in their Front Matter (sections at the end).
 
-### Theme Verification
+### Error Checks
 
 Upon building, the theme runs some basic verification to check if all necessary files and configurations are in place. If it encounters an error it shows this by adding an information bar on all your sites. You can disable this, e.g., in a production environment, by setting `show_errors` to `false` (default: `true`).
 
@@ -241,7 +234,7 @@ defaults:
       layout: room
 ```
 
-To change the URL of the collection, simply edit the `permalink` property and replace the `:collection` tag (which translates to `talks`, `speakers` and `rooms`) with your desired value. Please note that the talk and speaker overview pages should reside in a folder of the same name.
+To change the URL of the collection, simply edit the `permalink` property and replace the `:collection` tag (which translates to `talks`, `speakers` and `rooms`) with your desired value.
 
 > [!NOTE]
 > Please note that while you might want to change the URLs, the name of the three collections (`talks`, `speakers` and `rooms`) is fixed and cannot be changed.
@@ -276,7 +269,7 @@ timezone: Europe/Zurich
 
 ### Navigation Bar
 
-The navigation bar is located at the top and visible on every site. On the left, it shows the title of the website (`site.title`) followed by the links listed under the `links` property of the `navigation` property. See the [_Content_](#content) > [_Links_](#links) section below for the available properties per link. Please note that icons are ignored for the navigation bar.
+The navigation bar is located at the top and visible on every site. On the left, it shows the title of the website (`site.title`) followed by the links listed under the `links` property of the `navigation` property. See the [_Content_](#content) > [_Links_](#links) section below for the available properties per link. Icons are only shown when installed as an app (see below).
 
 Example:
 
@@ -287,12 +280,30 @@ conference:
       - name: Program
         relative_url: /program/
       - live: true
-      - name: Previous Editions
+      - name: About  # dropdown menu
         menu:
-          - name: 2020 (current)
-            disabled: true
-          - name: 2019
-            relative_url: /2019/
+          - name: Location
+            relative_url: /location/
+          - name: Code of Conduct
+            relative_url: /code-of-conduct/
+          - name: Contact
+            absolute_url: mailto:info@example.org
+```
+
+With several [_Editions_](#editions), a menu to switch between them appears at the end of the navigation bar, labelled with the page's edition. A link with `menu: editions` places it among the links instead (see [_Links_](#links)). The `editions` property under the `navigation` property adapts it:
+
+- `name` labels the menu instead of the edition; a link's own `name` wins.
+- `hide: true` removes the menu at the end, but not a link with `menu: editions`.
+
+```yaml
+conference:
+  navigation:
+    editions:
+      name: Editions
+    links:
+      - name: Program
+        relative_url: /program/
+      - menu: editions
 ```
 
 Optionally, a logo or link of your organization hosting the conference can be shown on the right side of the navigation bar. It is activated through the `logo` property under the `navigation` property containing
@@ -315,7 +326,7 @@ conference:
       url: 'https://github.com'
 ```
 
-The navigation bar automatically collapses when the available space is too small (e.g., on a smaller screen). The breakpoints are given by [Bootstrap](https://getbootstrap.com/docs/5.3/layout/breakpoints/). The default breakpoint is `md` (collapsing if the screen width is smaller than 992px). It can be adapted by setting the `breakpoint` property under the `navigation` property to either `sm`, `md`, `lg`, or `xl`.
+The navigation bar automatically collapses when the available space is too small (e.g., on a smaller screen). The breakpoints are given by [Bootstrap](https://getbootstrap.com/docs/5.3/layout/breakpoints/). The default breakpoint is `md` (collapsing if the screen width is smaller than 768px). It can be adapted by setting the `breakpoint` property under the `navigation` property to either `sm`, `md`, `lg`, or `xl`.
 
 When installed as a progressive web application (see the [_Progressive Web App (PWA)_](#progressive-web-app-pwa) section below), the navigation bar moves to the bottom. In PWA mode, it displays link icons and ignores links with `live: true`. Please note that the navigation bar has a limited width and no vertical scrolling. To hide an entry in this mode, set `pwa_hide: true` on its link.
 
@@ -331,7 +342,7 @@ conference:
         relative_url: /supporters/
 ```
 
-### Meta Data for Search Engines and Link Previews
+### Meta Data
 
 The theme automatically includes the necessary `<meta>` tags to ease link previewing when sharing links based on the [Open Graph protocol](https://ogp.me/) (used by all major social networks and messenger apps) and [Twitter Cards](https://developer.x.com/en/docs/x-for-websites/cards/overview/abouts-cards) (used by X). These tags control how a link is shown when shared via different platforms and apps. The theme also includes [Schema.org](https://schema.org/) JSON-LD structured data to help search engines better understand and display the conference and its talks, potentially showing event cards, speaker information, and enhanced search listings.
 
@@ -360,7 +371,7 @@ conference:
         open_graph: "facebook_preview.png"  # inside /assets/images/
 ```
 
-#### Meta Data for Search Engines
+#### Structured Data (Schema.org)
 
 Support for [Schema.org](https://schema.org/) JSON-LD structured data is organized under the `schema_org` property part of the `meta` property. It can be disabled by setting `disable` to `true`. Different schemas are generated depending on the page type, and these schemas are interconnected. The following schemas are generated:
 - `ConferenceEvent` (main and program page)
@@ -402,6 +413,7 @@ Optionally, the following properties can be added under the `schema_org` propert
 
 ```yaml
 conference:
+  meta:
     schema_org:
       disable: false  # Set to true to disable Schema.org JSON-LD structured data
       event_status: "scheduled"  # Options: scheduled, cancelled, postponed, moved_online
@@ -419,31 +431,7 @@ conference:
       img: "conference.png"  # inside /assets/images/
 ```
 
-### Main Landing Page
-
-The main landing page is shown at the root of the website to greet new visitors. To show it you need to create a `index.md` file in the root of your website's folder and specify its layout as `layout: home`.
-
-The main page states your site's title (`site.title`) or a logo instead. The logo can be configured through the `header` property of the main page's FrontMatter containing
-
-- a `img` property specifying the path to the image file relative to the `/assets/images/` folder.
-- optionally a `img_dark` property for a dark mode version of the logo, which will be automatically displayed when the user's system is in dark mode. If not specified, the regular `img` will be used in both light and dark modes.
-
-The title/logo on the main page is followed by a description of your site (`site.description`) and the content of your `index.md` file. It ends with an optional list of link buttons. See the [_Content_](#content) > [_Links_](#links) section below for the available properties per link.
-
-```yaml
-layout: home
-header:
-  img: "main_logo.png"
-  img_dark: "main_logo_dark.png"  # optional: dark mode version
-links:
-  - name: Program
-    relative_url: /program/
-  - name: Tickets
-    disabled: true
-    absolute_url: ''
-```
-
-### Information Boxes & Modals
+### Information Bars & Modals
 
 The theme supports two types of information displays: banners at the top of the page (`bars`) and dialog popups (`modals`). Both can be used to inform your visitors about important news and announcements.
 
@@ -511,14 +499,14 @@ This can be further extended if some talks have an associated live stream: When
 
 To activate these functionalities, each day in the `program.yml` file must contain a `date` property (see section [_Content_](#content) > [Schedule / Program](#schedule--program) below) and the `live` property has to be set in the configuration file containing
 
-- how long a pause between two consecutive talks has to be for the live indication to pause (`stop`),
+- optionally, how long a pause between two consecutive talks has to be for the live indication to pause (`stop`, default: `240`), and
 - optionally, under the `streaming` property:
   - if streaming should be enabled (`enable`), and if enabled
-  - how many minutes the stream goes active before a talk (`prepend`),
-  - how many minutes the stream stays active after a talk (`extend`),
-  - how long a pause between two consecutive talks has to be for the stream to pause (`pause`),
+  - how many minutes the stream goes active before a talk (`prepend`, default: `5`),
+  - how many minutes the stream stays active after a talk (`extend`, default: `5`),
+  - how long a pause between two consecutive talks has to be for the stream to pause (`pause`, default: `60`),
   - if the stream is only loaded once the visitor clicks a button, as the streaming provider receives the visitor's IP address (`click_to_load`, default: `true`; set to `false` for self-hosted streams), and
-  - an external (absolute) link to which the user will be redirected instead of opening the modal (`external`),
+  - an external (absolute) link to which the user will be redirected instead of opening the modal (`external`).
 
 ```yaml
 conference:
@@ -535,7 +523,7 @@ conference:
 
 ### Progressive Web App (PWA)
 
-The theme includes built-in support for Progressive Web App (PWA) functionality, allowing your conference website to be installed on users' devices and work offline. Once a visitor opened the site, all pages (program, talks, speakers, rooms, …) and all files below `assets/` (stylesheets, scripts, images, fonts) are available offline. Documents (`documents/`) and map tiles are not. Pages and data are always loaded fresh when online, so schedule changes reach visitors right away (falling back to the stored copy if the network does not answer within 3 seconds, e.g. on a crowded conference Wi-Fi). When the site is rebuilt, installed apps only download what changed: the theme's bundles are versioned by their content, all other files are revalidated. PWA functionality is disabled by default. To enable it, multiple manual steps are necessary to add the necessary files:
+The theme includes built-in support for Progressive Web App (PWA) functionality, allowing your conference website to be installed on users' devices and work offline. Once a visitor opened the site, all pages (program, talks, speakers, rooms, …) and all files below `assets/` (stylesheets, scripts, images, fonts) are available offline. Documents (`documents/`, with [editions](#editions) `<id>/documents/`) and map tiles are not. Pages and data are always loaded fresh when online, so schedule changes reach visitors right away (falling back to the stored copy if the network does not answer within 3 seconds, e.g. on a crowded conference Wi-Fi). When the site is rebuilt, installed apps only download what changed: the theme's bundles are versioned by their content, all other files are revalidated. PWA functionality is disabled by default. To enable it, multiple manual steps are necessary to add the necessary files:
 
 1. Enable and optionally customize the functionality in your `_config.yml`:
    ```yaml
@@ -546,7 +534,7 @@ The theme includes built-in support for Progressive Web App (PWA) functionality,
        # Theme color for the PWA (default: Bootstrap primary color, #0d6efd)
        theme_color: "#0d6efd"
 
-       # Background color for the PWA (default: Bootstrap primary color, #ffffff)
+       # Background color for the PWA (default: white, #ffffff)
        background_color: "#ffffff"
 
        # PWA icons configuration
@@ -592,9 +580,9 @@ The theme includes built-in support for Progressive Web App (PWA) functionality,
 > [!NOTE]
 > Please note that when installed as a PWA, the navigation bar moves to the bottom and includes icons. See the [_Navigation Bar_](#navigation-bar) section above for more information.
 
-### Talk Settings
+### Tracks & Tags
 
-Talks can optionally be organized into tracks, where each track groups talks under a common subject. Tracks are visually distinct across the website, especially in the program, by a unique color. Additionally, each talk can have one or more associated tags. Both tracks and tags are linked via the talk's Front Matter (refer to the [_Content_](#content) > [_Talks_](#talks) >  section below for more details).
+Talks can optionally be organized into tracks, where each track groups talks under a common subject. Tracks are visually distinct across the website, especially in the program, by a unique color. Additionally, each talk can have one or more associated tags. Both tracks and tags are linked via the talk's Front Matter (refer to the [_Content_](#content) > [_Talks_](#talks) section below for more details).
 
 To define available tracks, add the `tracks` property under the `talks` property in the configuration file. This property is a list of tracks, with each track requiring:
 
@@ -631,10 +619,34 @@ conference:
     # Talk tags
     tags:
       - name: No recording
-        icon: video-slash
+        icon: camera-video-off-fill
+```
+
+### Landing Page
+
+The main landing page is shown at the root of the website to greet new visitors. To show it you need to create a `index.md` file in the root of your website's folder and specify its layout as `layout: home`.
+
+The main page states your site's title (`site.title`) or a logo instead. The logo can be configured through the `header` property of the main page's Front Matter containing
+
+- a `img` property specifying the path to the image file relative to the `/assets/images/` folder.
+- optionally a `img_dark` property for a dark mode version of the logo, which will be automatically displayed when the user's system is in dark mode. If not specified, the regular `img` will be used in both light and dark modes.
+
+The title/logo on the main page is followed by a description of your site (`site.description`) and the content of your `index.md` file. It ends with an optional list of link buttons. See the [_Content_](#content) > [_Links_](#links) section below for the available properties per link.
+
+```yaml
+layout: home
+header:
+  img: "main_logo.png"
+  img_dark: "main_logo_dark.png"  # optional: dark mode version
+links:
+  - name: Program
+    relative_url: /program/
+  - name: Tickets
+    disabled: true
+    absolute_url: ''
 ```
 
-### Location Settings
+### Location Page
 
 To help users find your venue, an [OpenStreetMap](https://www.openstreetmap.org/) container displaying a map can be shown on the location page as well as the address of the venue. You can define the initial position of the map by setting the default zoom level `default_zoom`, the center coordinates `home_coord`, and the map provider for the tiles `map_provider`. Alternative map providers can be found [here](https://leaflet-extras.github.io/leaflet-providers/preview/).
 The map contains small control buttons to zoom in and out, center the map back to the initial position, and show the visitor's current location (has to be manually activated and granted by the visitor).
@@ -644,12 +656,13 @@ To protect the visitors' privacy, the map is only loaded once the visitor clicks
 Location settings are configured directly in the Front Matter of the location page (the page with `layout: location`). The location page's Front Matter supports the following properties:
 
 - `title`: The title shown in the navigation bar for the location section (defaults to "Location")
-- `hide`: Set to `true` to hide the location page and all room links (default: `false`). Hidden rooms still need to exist in the `_rooms/` directory as references.
+- `hide`: Set to `true` to hide the location page and all room links (default: `false`). The page then only redirects to the home page. Hidden rooms still need to exist in the `_rooms/` directory as references.
 - `map`: Map configuration object with the following properties:
   - `home_coord`: Center coordinates of the map (e.g., `47.37808, 8.53935`)
   - `default_zoom`: Initial zoom level (e.g., `17`)
   - `map_provider`: Tile provider (default: `"OpenStreetMap.Mapnik"`)
   - `click_to_load`: Load the map only after the visitor's consent (default: `true`)
+  - `script`: Script adapting the map, e.g. adding markers (see below)
 - `postal_address`: Postal address displayed on the location page and used in schema.org structured data. Can contain:
   - `name`: Venue name (e.g., "Zentralwäscherei")
   - `street`: Street address (e.g., "Neue Hard 12")
@@ -681,32 +694,24 @@ map:
 Welcome to our conference venue!
 ```
 
-The map is based on the [Leaflet](https://leafletjs.com/) JavaScript library. The map object can be customized by adding additional layers with markers, text, or shapes. To do so, edit the `assets/js/main.js` file in your project:
-
-1. The conference JavaScript bundle (`conference.bundle.js`) is automatically loaded and provides all necessary libraries
-2. Await the initialization of the theme's object using `window.conference.awaitReady()`
-3. Fetch the map object and verify it is set (while the JavaScript code is executed on each page, the map object will only exist on the location page). The returned promise resolves once the visitor loaded the map.
-4. Modify the map.
-
-The following example for `assets/js/main.js` adds a simple marker to the map:
+The map is based on the [Leaflet](https://leafletjs.com/) JavaScript library. To add markers, text, or shapes, name a script in `map.script`, relative to `assets/js/` (e.g. `script: maps/venue.js` for `assets/js/maps/venue.js`). Once the visitor loaded the map, the theme calls the script's default export with the map object (Leaflet is available as `L`):
 
 ```javascript
-window.conference.awaitReady().then(async () => {
-    const map = await window.conference.map.getMap();
-
-    if (map) {
-        let main_station = L.marker([47.37785, 8.54035], {
-            icon: L.divIcon({
-                className: '',
-                html: '<span class="bi bi-train-front" aria-hidden="true"></span> Main Station',
-                iconSize: [120, 56]
-            })
-        }).addTo(map);
-    }
-});
+// assets/js/maps/venue.js
+export default function (map) {
+    L.marker([47.37785, 8.54035], {
+        icon: L.divIcon({
+            className: '',
+            html: '<span class="bi bi-train-front" aria-hidden="true"></span> Main Station',
+            iconSize: [120, 56]
+        })
+    }).addTo(map);
+}
 ```
 
-### Program Settings
+With several [editions](#editions), each edition's location page names its own script. Alternatively, `assets/js/main.js` gets the map with `await window.conference.map.getMap()` after `await window.conference.awaitReady()` (resolves once the visitor loaded the map, with `null` on pages without map).
+
+### Program Page
 
 Program settings are configured directly in the Front Matter of the program page (the page with `layout: program`). The program page's Front Matter supports the following properties:
 
@@ -725,15 +730,91 @@ show_alltimes: true
 ---
 ```
 
+### Editions
+
+One site can hold several editions of a conference, e.g. the current one and past ones as archive. Every edition lives below its own folder (`/2026/`, `/2025/`, …), the site's root forwards to the current edition. Without `editions`, the site holds a single edition as described in the rest of this document.
+
+List the editions in `_config.yml` under `conference.editions`. The current edition is the first one with `current: true`, else the first one of the list. Its `id` names the edition's folders, its `name` labels it in the menu to switch between editions (default: its id).
+
+An edition inherits the site's settings and can override some of them. An override replaces the site's setting as a whole, all others are kept; e.g. an edition with its own `navigation.links` keeps the site's `navigation.logo`.
+
+| Setting | In `_config.yml` | Per edition |
+|---|---|---|
+| `title`, `description` | Jekyll, top level | yes |
+| `url`, `baseurl`, `timezone` | Jekyll, top level | no |
+| `meta.link_preview`, `meta.schema_org` | `conference` | yes |
+| `navigation.logo`, `navigation.links`, `navigation.breakpoint`, `navigation.editions` | `conference` | yes |
+| `info.bars`, `info.modals` | `conference` | yes |
+| `talks.tracks`, `talks.tags` | `conference` | yes |
+| `lang`, `custom_style`, `show_errors`, `pwa` | `conference` | no |
+| `live` | `conference` | no, current edition only |
+
+Settings in a page's Front Matter (e.g. of the [_Landing Page_](#landing-page) or the [_Program Page_](#program-page)) belong to its edition anyway, as every edition has its own pages.
+
+```yaml
+conference:
+  editions:
+    - id: "2026"
+      current: true
+      title: My Conference 2026
+    - id: "2025"
+      name: 2025 (Archive)
+      title: My Conference 2025
+      talks:
+        tracks:
+          - name: Workshops
+            color: warning
+```
+
+Mark each page and entry with its edition by folder, with one pair of `defaults` per edition (in addition to the layouts of the collections, see [_Collection URLs_](#collection-urls)):
+
+```yaml
+defaults:
+  - scope:
+      path: "2026"     # pages, e.g. 2026/program/index.md
+    values:
+      edition: "2026"
+  - scope:
+      path: "_*/2026"  # talks, speakers and rooms, e.g. _talks/2026/keynote.md
+    values:
+      edition: "2026"
+      permalink: /2026/:collection/:title/
+```
+
+With `show_errors`, pages report a page or entry whose `edition` doesn't match its folder, e.g. due to a forgotten `defaults` entry.
+
+The content of each edition is then placed as follows:
+
+```
+index.md                  layout: editions (forwards to the current edition)
+2026/index.md             layout: home
+2026/program/index.md     layout: program (likewise talks/, speakers/, location/, …)
+2026/documents/           files of links (slides/, bio/, …)
+_talks/2026/              talks (likewise _speakers/2026/, _rooms/2026/)
+_data/programs/2026.yml   schedule
+```
+
+Talks, speakers and rooms are looked up within their edition only, so names may repeat across editions (e.g. a speaker attending every year). Links with `relative_url` point into the page's edition, e.g. `/program/` to `/2026/program/`. Live indications, live streams and the offline app (PWA) cover the current edition only. To point visitors of a past edition to the current one, give it an info bar (see [_Information Bars & Modals_](#information-bars--modals)), e.g. `info: {bars: [{title: Archive, color: secondary, text: "Go to the [current edition](/2026/)."}]}` in its `editions` entry. Files below `assets/` (styles, scripts, images) and `_sass/` are shared by all editions.
+
+Other addresses, e.g. a former `/program/`, show the site's 404 page. To forward them to the current edition on an Apache web server, create a `.htaccess` file in the root of your project:
+
+```yaml
+---
+layout: htaccess
+---
+```
+
+It forwards addresses that don't exist but do exist in the current edition, e.g. `/program/` to `/2026/program/`, and follows the current edition on its own. Below the Front Matter, you can add your own rules. It assumes the site lies at `baseurl` below the web server's document root. Other hosts (e.g. GitHub Pages, Netlify, nginx) ignore the file and need their own redirects.
+
 
 ## Content
 
-The different talks, speakers and rooms are stored as a collection of files. Each file contains a small header in form of a YAML block (called [FrontMatter](https://jekyllrb.com/docs/front-matter/)) used to store additional information beside a description.
+The different talks, speakers and rooms are stored as a collection of files. Each file contains a small header in form of a YAML block (called [Front Matter](https://jekyllrb.com/docs/front-matter/)) used to store additional information beside a description.
 The schedule defining when and in which room a talk takes place is stored as a [YAML data file](https://jekyllrb.com/docs/datafiles/).
 
 ### Schedule / Program
 
-The schedule of the conference linking the talks with the rooms and indicating when each talk takes place and how long it lasts, is set in the `_data/program.yml` file. It contains a list of days, whereby each day contains a list of rooms, whereby each room contains a list of talks.
+The schedule of the conference linking the talks with the rooms and indicating when each talk takes place and how long it lasts, is set in the `_data/program.yml` file (with several [editions](#editions): `_data/programs/<id>.yml` per edition). It contains a list of days, whereby each day contains a list of rooms, whereby each room contains a list of talks.
 
 Each day consists of
 
@@ -747,7 +828,7 @@ Each room consists of
 - the room's `name` (must correspond to one of the room identifiers), and
 - a list of talks (`talks`) which also can be empty `[]`.
 
-The order of the rooms in the list defines the order of the rooms as shown in the schedule on the program page. For the live-streaming or the room overview the order of the rooms is alphabetical but can be adapted via the [main configuration file](https://jekyllrb.com/docs/collections/#sort-by-front-matter-key).
+The order of the rooms in the list defines the order of the rooms as shown in the schedule on the program page. Elsewhere (e.g. live streams or the room links on the location page), rooms follow their first appearance in the program, unless they set `order` (see [_Rooms_](#rooms)).
 
 Each talk consists of
 
@@ -839,7 +920,8 @@ links:
 Each room is represented by a file in the `_rooms/` directory. It must begin with valid [YAML Front Matter](https://jekyllrb.com/docs/frontmatter/) containing
 
 - the room's `name`
-- optionally, `hide: true` if the room's page should not be linked to, and
+- optionally, `hide: true` if the room's page should not be linked to,
+- optionally, its position (`order`, a number) where rooms are listed outside the program, otherwise rooms follow their first appearance in the program, and
 - optionally under the `live` property, a URL pointing to a live stream for the given room during the conference (see the section [_Configuration_](#configuration) > [_Live Indications & Streaming_](#live-indications--streaming) above), either:
   - as an `absolute_url`, or
   - a `relative_url`.
@@ -876,13 +958,14 @@ Using the `file:` indicator, the
   - the site's base address followed by `/documents/slides` and the value for _talks_,
   - the site's base address followed by `/documents/bio` and the value for _speakers_, or
   - the site's base address followed by `/documents` and the value for all remaining types.
-- the link's `icon:` is set to `file-alt`.
+  - With several [editions](#editions), the edition's id precedes `/documents`, e.g. `/2026/documents/slides`.
+- the link's `icon:` is set to `file-earmark-text`.
 
 Using the `video:` indicator, the
 
 - link address is set to an absolute address as given by the value.
 - the link's `iframe:` attribute is set to `true` to embed the video in a popup-like modal having a default iframe ratio of 24:11.
-- the link's `icon:` is set to `video`.
+- the link's `icon:` is set to `camera-video-fill`.
 
 Additionally, a _talk_ link can also have the following property:
 
@@ -895,35 +978,11 @@ Additionally, a _navigation bar_ or _main landing page_ link can also have the f
   - If `name_inactive` is set, its value is used as a placeholder text while the conference is **not** live. If `name_inactive` is an empty string, "Live Stream" is shown instead.
   - If streaming is enabled and any URL property is omitted, a click on the link will open the streaming modal (see section [_Configuration_](#configuration) > [_Live Indications & Streaming_](#live-indications--streaming) above).
 - `menu` containing another list of links. This creates a dropdown menu of multiple sublinks, while the URL of the parent link is ignored. The sublinks have the same properties as regular links.
+  - With `menu: editions`, the dropdown menu lists the [editions](#editions) instead. Without `name`, it is labelled with `navigation.editions.name`, else the page's edition. It is not shown with a single edition.
 
-#### Import link files
-
-There exists a Python file in this repository, `_tools/import_resources.py`, which can be used to import resources such as slides and other documents from [pretalx.com](https://pretalx.com/p/about/)) via its API. It automatically downloads all files, stores them and updates the links of the talks concerned.
-
-1. Copy the files `_tools/import_resources.py` and `_tools/requirements.txt` from this repository
-
-2. Create a virtual environment and activate it
-
-   ```bash
-   python -m venv .venv
-   source .venv/bin/activate
-   ```
-
-3. Install the requirements
-
-   ```bash
-   pip install -r _tools/requirements.txt
-   ```
-
-4. Execute the script, e.g., to show the help type
+### Pages
 
-   ```bash
-   python _tools/import_resources.py --help
-   ```
-
-### Overview Pages
-
-For each of the three collections, there exists a dedicated layout giving an overview of all items in the collection. Furthermore, there exists a layout to show the program as a time schedule. Simply create an empty page and associate the corresponding layout with it:
+The overviews of talks and speakers, the location with its rooms, and the program as a time schedule each have a dedicated layout. Simply create a page and associate the corresponding layout with it:
 
 - `talks/index.md` with `layout: talk-overview`
 - `speakers/index.md` with `layout: speaker-overview`
@@ -932,13 +991,6 @@ For each of the three collections, there exists a dedicated layout giving an ove
 
 They can be empty but should contain the `layout` property in the Front Matter header.
 
-If you choose a different location for the overview pages you must:
-
-- for the `talks` and `speakers` overview files, adapt the URL of the two collections as described further above in the section [_Configuration_](#configuration) > [_Collection URLs_](#collection-urls), and
-- for the `location` and `program` files, adapt the corresponding `url` parameter as described further above in the sections [_Configuration_](#configuration) > [_Location Settings_](#location-settings) and [_Configuration_](#configuration) > [_Program Settings_](#program-settings).
-
-### Additional Pages
-
 Additional static pages can easily be added as files and linked to via navigation bar or main landing page.
 
 
@@ -965,7 +1017,7 @@ The `assets/css/` directory contains:
 - `map.bundle.css`: Leaflet map styles, loaded together with the map
 - `main.scss`: For user-modifiable custom styles.
 
-Including `assets/css/main.scss` in your project is optional. If included, it must begin with a [FrontMatter](https://jekyllrb.com/docs/front-matter/) header for Jekyll recognition:
+Including `assets/css/main.scss` in your project is optional. If included, it must begin with a [Front Matter](https://jekyllrb.com/docs/front-matter/) header for Jekyll recognition:
 
 
 ```scss
@@ -992,7 +1044,7 @@ The `assets/css/` directory contains:
 - `map.bundle.css`: Leaflet map styles, loaded together with the map
 - `main.scss`: For additional custom styles.
 
-Including `assets/css/main.scss` in your project is optional. If included, it must begin with a [FrontMatter](https://jekyllrb.com/docs/front-matter/) header for Jekyll recognition:
+Including `assets/css/main.scss` in your project is optional. If included, it must begin with a [Front Matter](https://jekyllrb.com/docs/front-matter/) header for Jekyll recognition:
 
 ```scss
 ---
@@ -1002,7 +1054,7 @@ Including `assets/css/main.scss` in your project is optional. If included, it mu
 // ...
 ```
 
-#### Custom SCSS
+### Full Custom Build (Custom SCSS)
 
 Compile your Bootstrap framework by modifying [Bootstrap variables](https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults). This provides complete control over Bootstrap's SCSS variables, enabling source-level customization.
 
@@ -1058,7 +1110,7 @@ To use the icon font in your own content or JavaScript instead (e.g. `<i class="
 ```
 
 
-## JavaScript
+## Custom JavaScript
 
 The theme includes a pre-built JavaScript bundle (`assets/js/conference.bundle.js`). This bundle is automatically included in the theme gem, pre-compiled, and minified, requiring no build tools for end users. Please do not modify this file directly.
 
@@ -1076,7 +1128,7 @@ To add custom JavaScript, edit the `assets/js/main.js` file in your project. Thi
   - `conference.infobox`: Dismissal of information boxes and modals
   - `conference.darkmode`: Dark mode according to the system preference
   - `conference.pwa`: Service worker registration (if PWA is enabled)
-  - `conference.config`: Settings of the modules, e.g. `conference.config.baseurl`
+  - `conference.config`: Settings of the modules, e.g. `conference.config.baseurl`, `conference.config.edition` (the page's edition id, `null` without editions) and `conference.config.edition_current`
   - `conference.awaitReady()`: Promise-based initialization helper
 - `window.bootstrap`: Bootstrap components (Alert, Collapse, Dropdown, Modal, Tab)
 - `window.L`: Leaflet map library (once the map is loaded)
@@ -1167,9 +1219,11 @@ To modify the theme's source code and rebuild:
    This compiles:
    - `_js/` → `assets/js/conference.bundle.js`
    - `_css/` → `assets/css/conference.bundle.css`, `assets/css/conference-only.bundle.css` and `assets/css/map.bundle.css`
+
    This generates:
    - `_includes/icons/`: one include per Bootstrap Icon (inline SVG)
    - `_data/conference_assets.yml`: content hashes of the bundles (cache busting)
+
    This copies:
    - `_css/` + any SASS file from the different framework libraries → `_sass`
    - Webfonts → `assets/webfonts/` (for sites using the icon font themselves)
@@ -1181,7 +1235,7 @@ To modify the theme's source code and rebuild:
 
 ### Tests
 
-The tests build the example site in `test/fixture/` (containing edge cases such as quotes and markup in names, overnight talks, hidden entries, live streams, PWA and a map) and run on every pull request:
+The tests build the example site in `test/fixture/` (containing edge cases such as quotes and markup in names, overnight talks, hidden entries, live streams, PWA and a map) and the site with two editions in `test/fixture-editions/`, and run on every pull request:
 
 ```bash
 npm run build                         # theme bundles