hackertours/README.md
Vincent Mahnke 1c88d25508
All checks were successful
/ build (push) Successful in 1m59s
/ accessibility (push) Successful in 3m54s
Tour pages: size the few-seats note like the book button, add a warning sign
The note now has the "Book now" button's font, padding and border, so
both are the same height, and starts as far in as the button and the
calendar links, so the three line up on narrow screens as well. Like
the button's shopping cart, it gets an icon: a warning triangle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:21:24 +01:00

373 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Hackertours Web Site
## Complete the checkout
We need the submodule for the theme, so update/clone the submodules:
```shell
git submodule update --init --recursive
```
## Run in dev mode
```shell
hugo server --buildFuture --buildDrafts
```
Then open http://localhost:1313
The header uses the logo dimensions in `hugo.yaml` in both languages, without
shrinking the logo to fit the text. Screens up to 666px wide swap the main menu
and the language link in the header for a bottom navigation bar
(`themes/hackertours/layouts/_partials/mobilemenu.html`), with one entry per menu
item plus one for the language switch. The page reserves space for the bar so it
does not cover content.
## Themes
The site's design is a stack of Hugo themes, set in `hugo.yaml`. For a file
that exists in more than one of them, the first theme in the list wins:
```yaml
theme:
- hackertours-40c3
- hackertours
- zen
```
- `themes/zen` is the [Zen theme](https://github.com/frjo/hugo-theme-zen) as a
submodule, unmodified. To update it, check out a newer release tag in the
submodule and commit the new pointer.
- `themes/hackertours` is the Hackertours design, kept in this repository: all
templates, shortcodes, CSS, JavaScript, translations and icons. To change
something in Zen, put a file with the same path here; for example,
`assets/css/mobilemenu.css` and `assets/js/mobilemenu.js` replace Zen's mobile
menu with the bottom navigation bar.
- `themes/hackertours-40c3` is the design for 40C3, after the 40C3 style guide
(PR #67): colours, the Jersey 10 and Hack fonts, square corners, and the
40C3 logo in the footer. It contains only what differs from the generic
design: `assets/css/_custom.css` and `assets/css/_events.css` replace the
generic ones, `assets/css/_schedule-40c3.css` adjusts the schedule, and
`static/site.webmanifest` has the 40C3 colours.
An event design adds to the page through two hooks, which are empty in
`themes/hackertours`: `layouts/_partials/event-design/head.html` (fonts,
`theme-color`) and `layouts/_partials/event-design/footer.html` (the event
logo). Changes to the generic `_custom.css` or `_events.css` don't reach the
40C3 design, which has its own copies of those files, so make them there too if
they matter during the event.
### Switching back to the generic design
After 40C3, remove `hackertours-40c3` from `theme` in `hugo.yaml`:
```yaml
theme:
- hackertours
- zen
```
You can leave `themes/hackertours-40c3` in the repository, or delete it. To
preview the generic design without changing `hugo.yaml`, run
`hugo server --buildFuture --theme hackertours,zen`.
Content, `data/` and the site-specific files in `static/` (logo, favicons, map
data) stay at the top level of the repository. Don't add `layouts/`, `assets/`
or `i18n/` there: Hugo lets them override every theme.
## Brand spelling check
Hugo builds check content source lines for the name `Hackertours` in any other
casing and report the file and line as build errors for pages included in the
build. URLs, email addresses, social handles, Matrix room addresses and
Markdown link destinations are excluded. Commented-out content is checked too,
so it is ready to publish.
For an intentional exception, add `<!-- hackertours-lint-ignore -->` at the
end of a Markdown line, or `# hackertours-lint-ignore` at the end of a YAML
front matter line. This ignores that entire source line, so keep unrelated
occurrences on other lines.
## Shortcode: Language badge
Use the `lang` shortcode to mark whether a tour is in German, English or bilingual. It renders a small superscript badge next to the text, with details when hovered over or parsed by a screenreader.
- German: `{{< lang de >}}`
- English: `{{< lang en >}}`
- Bilingual: `{{< lang deen >}}`
## Shortcode: Tour schedule
The tour overview of an event (`content/*/<event>/_index.md`) shows the schedule with `{{< schedule >}}`. It reads `data/schedule/<event>.yaml`, which is shared by both languages:
```yaml
fewseats: [xfel]
days:
- day: 1
date: "2025-12-27"
tours:
- { time: "11:30", tour: xfel, lang: deen, status: fewseats }
- { time: "12:00", tour: city-walk, lang: de }
```
- `tour` is the slug of the tour page in the event section. The card shows that page's title, without the event prefix, and links to it.
- `lang` is `de`, `en` or `deen`, or a list of these. It renders the same badge as the `lang` shortcode.
- `time` is `HH:MM` with a leading zero (`09:30`). Tours are sorted by time, so their order in the file doesn't matter.
- `title` (optional) replaces the page's title on the card, with one entry per language: `title: { de: "Hafen am Abend", en: "Harbour by Night" }`.
- `status` (optional): `soldout` marks the date as fully booked; `fewseats` highlights "Nur wenige Plätze über" / "only a few seats left" next to the time, for a date on sale with 5 seats or fewer. Other values are ignored.
- `fewseats` (optional, top level): slugs of the tours with only a few seats left as a whole. Their cards get a small "only a few seats left" badge below the title, except on dates that have a `status` of their own, so a card never says it twice. A date can be `fewseats` without its tour being in the list, and the other way round.
- With JavaScript at viewport widths of at least 667px, the first local photo in the tour page fills the right 40% of its card behind a fade when it has alt text; its gallery credit remains visible.
For the events managed with Hackertours-Admin, the data file is generated by its website sync; don't edit it by hand.
With JavaScript, narrow screens show a day picker, starting with today's day during the event. Wider screens list days under their headings, hiding past days until the event ends. Before and after the event, all days are shown. Dates use the visitor's local time. Without JavaScript, narrow screens show all days stacked; wide screens show a column per day on an hour grid.
For a different event than the page's section, pass its name: `{{< schedule 39c3 >}}`.
Without a data file, or without any tours in it, the shortcode renders nothing and the build logs a warning. To silence it, for example for an upcoming event, add `warning-schedule-empty` to `ignoreLogs` in `hugo.yaml`.
## Shortcode: Tour date
`{{< tour-date >}}` is one date in the list of dates on a tour page. Hackertours-Admin writes the facts as parameters, and the shortcode formats them the same way on every page: day and date, time, the date's own title, language, a note, and on a new line the "only a few seats left" note, the "Book now" button and the calendar links. Use it inside a list item:
```markdown
* Touren:
* {{< tour-date day=1 date="2026-12-27" time="13:30" lang="de" title=`Piraten!?` book=`https://…/40c3ht/229/` duration=180 >}}
* {{< tour-date day=2 date="2026-12-28" time="12:55" lang="deen" note=`Die Tour wird auf Deutsch präsentiert, …` book=`https://…/40c3ht/227/` status="fewseats" >}}
```
renders (on the German page)
> * Touren:
> * Tag 1 (27.12.) **13:30 Uhr** *Piraten!?* auf Deutsch\
> [Jetzt buchen] [iCal Download | Google Calendar]
> * Tag 2 (28.12.) **12:55 Uhr** auf Deutsch und Englisch – Die Tour wird auf Deutsch präsentiert, …\
> Nur wenige Plätze über [Jetzt buchen] [iCal Download | Google Calendar]
| Param | Required | Content |
|---|---|---|
| `date` | yes | `YYYY-MM-DD` |
| `time` | yes | Start time `HH:MM`, local time in Hamburg |
| `day` | no | Day number of the event (`0` for the day before day 1). Shown as "Tag 1 (27.12.)" / "Day 1 (27 December)". Leave it out for dates grouped under a day heading, as in `* Tag 1 (27.12.):` followed by the times. |
| `lang` | no | `de`, `en` or `deen`: "auf Deutsch", "auf Englisch", "auf Deutsch und Englisch" / "in German", "in English", "in German and English". Anything else stops the build. |
| `title` | no | The date's own title, in italics after the time, in the page's language. |
| `note` | no | Text after the language, after a dash, in the page's language. Markdown is allowed. |
| `book` | no | The date in the ticket shop, for the "Book now" button. |
| `duration` | no | Length in minutes, for the calendar entry (see "Shortcode: Calendar entry"). |
| `status` | no | `soldout` strikes the date through and adds "ausgebucht" / "fully booked", without the button and the calendar links. `fewseats` adds the highlighted "Nur wenige Plätze über" / "only a few seats left", with a warning sign, before the button. Other values are ignored, as in the schedule. |
Use backticks around values that contain double quotes. The wording is in the theme's i18n files (`tour_date_*`, `fewseats`, `schedule_soldout`).
## Shortcode: Few seats left
`{{< fewseats >}}` says "Nur wenige Plätze über" / "only a few seats left" for the tour as a whole, as a small badge, when the page's front matter has
```yaml
params:
fewseats: true
```
Hackertours-Admin puts it on its own line, right before the list of dates. It shows nothing without `params.fewseats: true`, and nothing when a date on the page already says so (a `tour-date` with `status="fewseats"`), so the page doesn't say it twice. The tour lists (the event's overview page, the home page, the tour-map's list of locations) show the same badge from `params.fewseats`, without the shortcode.
## Shortcode: Calendar entry
`{{< calendar >}}` adds a small pill after a tour date with a calendar icon and two links: "iCal download", a calendar file (`.ics`) for that date, and "Google calendar", which adds the date in Google Calendar. `tour-date` includes it; for a hand-written list of dates, use it on its own:
```markdown
* Tag 1 (27.12.) **17:30 Uhr** {{< calendar date="2026-12-27" time="17:30" duration="210" >}}
```
| Param | Required | Content |
|---|---|---|
| `date` | yes | `YYYY-MM-DD` |
| `time` | yes | Start time `HH:MM`, local time in Hamburg |
| `duration` | no | Length in minutes. Without it, `duration` of the tour in `tours` in the schedule file is used (see "Map data in the schedule file"); without either, the calendar entry has no end time and the build logs a warning with the ID `warning-calendar-duration`. |
| `title` | no | Title of the calendar entry. Without it, the `title` of this date in the schedule file is used, then the page title. |
The `.ics` file is in the iCalendar format (RFC 5545), which Apple Calendar, Outlook, Thunderbird and most other calendar apps open directly. The Google calendar link is there because the Google Calendar app on Android can't open downloaded `.ics` files.
The icon is `regular/calendar-plus` from [Font Awesome Free](https://fontawesome.com/search?ic=free), kept in [themes/hackertours/assets/vendor/fontawesome/](themes/hackertours/assets/vendor/fontawesome/). Other templates can use any of its icons with `{{ partial "fa-icon.html" "solid/ship" }}`: it inlines the SVG, decorative and in the text colour. The icons are CC BY 4.0; the attribution is the comment inside each SVG, which the partial keeps.
Each entry starts at the time given, in Hamburg time, at the Hackertours desk (with `map.origin` from the schedule file as the address, if there is one). Its description is the tour summary and a link to the tour page. The files are generated next to the tour page, one per date and language, e.g. `/de/40c3/tour-of-the-giants/tour-of-the-giants-2026-12-27-1730.ics`.
## Shortcode: Book now
`{{< book >}}` adds a "Book now" button with a shopping cart icon after a tour date, linking to that date in the ticket shop. `tour-date` includes it; for a hand-written list of dates, use it on its own, before the calendar pill:
```markdown
* Tag 1 (27.12.) **13:00 Uhr** {{< book url="https://…/hackertours/40c3ht/100/" >}} {{< calendar date="2026-12-27" time="13:00" >}}
```
| Param | Required | Content |
|---|---|---|
| `url` | yes | The date in the ticket shop |
The button text is `book_now` in the theme's i18n files. The icon is `solid/cart-shopping` from Font Awesome Free (see "Shortcode: Calendar entry").
## Shortcode: Tour map
`{{< tour-map >}}` on an event's overview page shows a map of the tour locations, with the routes from the Congress, on OpenStreetMap. For a different event than the page's section, pass its name: `{{< tour-map 39c3 >}}`. It uses [Leaflet](https://leafletjs.com), which is kept in [themes/hackertours/assets/vendor/leaflet/](themes/hackertours/assets/vendor/leaflet/).
- Each tour gets a marker in its colour, with its `icon` in white, and its route as a line; walking legs are dotted. Clicking a marker or a route shows the tour title, linked to the tour page, and the directions.
- The map shows all tours at once. Scroll-wheel zoom only starts after clicking into the map, so the page still scrolls normally.
- The map is only created when it scrolls near the visible part of the page, so visitors who don't scroll down load no map tiles. That also means the accessibility check (pa11y) doesn't see the map: it would otherwise report the text above the map, because axe wrongly takes the clipped map tiles to overlap it. Check changes to the map's markers and controls by hand, e.g. with the axe browser extension.
- Without JavaScript, and for screen readers, it shows a list of the tours with their directions and a link to each location on openstreetmap.org.
- If a text is missing in the page's language, the other language is used.
- Without any tours with `geo`, the shortcode renders nothing and the build logs a warning with the ID `warning-tour-map-empty`.
### Map data in the schedule file
A map of an event shows where each tour takes place and how to get there from the Congress. The data for it goes into the same file as the schedule, `data/schedule/<event>.yaml`, next to `days`. Like the schedule, it is shared by both languages; anything that people read comes with a `de` and an `en` version.
```yaml
map:
origin: # where all routes start, shown with its own marker
name: { de: "Congress (CCH)", en: "Congress (CCH)" }
geo: { lat: 53.561450, lon: 9.986360 }
icon: computer
tours:
miniatur-wunderland: # tour slug, as in days[].tours[].tour
geo: { lat: 53.543843, lon: 9.988765 }
color: "#32cd32"
icon: tram-stop
directions:
de: |
- Ab S Dammtor mit dem Bus 4 Richtung Osakaallee.
- Am Rathausmarkt in die U3 Richtung Schlump umsteigen.
- An der U Baumwall aussteigen, über den Kanal, links am Kanal entlang bis zum Eingang.
en: |
- From S Dammtor take bus 4 towards Osakaallee.
- At Rathausmarkt change to the U3 towards Schlump.
- Exit at U Baumwall, cross the canal and walk left alongside it to the entrance.
route: # from map.origin to geo, one entry per leg
- { mode: walk, polyline: "…" }
- { mode: bus, line: "4", polyline: "…" }
- { mode: subway, line: "U3", polyline: "…" }
- { mode: walk, polyline: "…" }
days:
# … as described under "Shortcode: Tour schedule"
```
`tours` has one entry per tour slug that should appear on the map. A slug can be in `tours` without being scheduled, and the other way round; scheduled tours without an entry simply don't appear on the map.
| Field | Required | Content |
|---|---|---|
| `geo` | yes | Meeting point or venue: `lat` and `lon` in decimal degrees (WGS 84), six decimals are plenty. Write it even though the tour page has the same value in `params.geo`; the map only reads this file. |
| `color` | no | Colour of the marker and the route, as a CSS colour (`"#32cd32"` or `LimeGreen`). Pick colours that differ between tours. |
| `icon` | no | Name of an icon for the marker, see "Map icons" below. Without it, or with an unknown name, the marker is a plain coloured circle; an unknown name also logs a build warning. |
| `directions` | no | How to get there from the origin, per language (`de`, `en`) as Markdown, usually a short list of steps. |
| `route` | no | The way from `map.origin` to `geo` as a list of legs in travel order. Without it the tour only gets a marker. |
| `duration` | no | Length of the tour in minutes, used by the calendar entries when the `calendar` shortcode doesn't pass one. |
Each leg in `route` has:
- `mode`: `walk`, `bus`, `subway` (U-Bahn), `train` (S-Bahn, regional train), `ferry` or `other`. The map can draw walking legs differently from rides.
- `line` (optional): the line name as signposted, for example `"4"`, `"U3"` or `"S2"`.
- The geometry, in one of two forms:
- `polyline`: an [encoded polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) as returned by most routing services. Add `precision: 6` if it was encoded with six decimals instead of the default five.
- `coordinates`: a list of `[lon, lat]` pairs (GeoJSON order), handy for hand-drawn routes exported from uMap or geojson.io.
Legs should join up: each leg starts where the previous one ends, and the first leg starts at `map.origin`.
`map.origin` is usually the same for all tours of an event, so it is written once. It takes `name` (per language), `geo` and an optional `icon`.
### Map icons
Marker icons come from three public-domain (CC0) icon sets for maps, kept in [themes/hackertours/assets/vendor/icons/](themes/hackertours/assets/vendor/icons/):
| Set | Icons | Browse |
|---|---|---|
| `osmic` | 154 | [OSMIC](https://github.com/gmgeo/osmic), or the files in `themes/hackertours/assets/vendor/icons/osmic/` |
| `maki` | 211 | [Maki](https://labs.mapbox.com/maki-icons/) |
| `temaki` | 557 | [Temaki](https://rapideditor.github.io/temaki/docs/) |
`icon` takes the file name without `.svg`, for example `ferry` or `railway-halt`. The name is looked up in `osmic`, then `maki`, then `temaki`; some names exist in more than one set, so to pick a specific set, put its name in front: `maki:garden`, `temaki:binoculars`. uMap's pictograms are OSMIC and Maki icons with the same names, and this lookup order picks the same icon as uMap for every one of them, so `icon` values copied from uMap work unchanged.
Only the icons a page uses end up in it, so the size of the sets doesn't matter. To update a set, replace its folder with the SVG files of a newer version; each folder has a README with the version it came from.
### The 39C3 tour map (uMap)
The 39C3 overview pages embed a map with the `map-39c3` shortcode ([themes/hackertours/layouts/_shortcodes/map-39c3.html](themes/hackertours/layouts/_shortcodes/map-39c3.html)). It is an iframe of the uMap map [39c3 Hackertours](https://umap.openstreetmap.fr/en/map/39c3-hackertours_1329184), which was created by the uMap user WinstonS in December 2025. The map has no other editors, so only that account can change it. Nothing about the map is stored in this repository apart from the embed code.
How the map is built:
- The background is the "Jawg Dark" tile layer.
- Layer 1 holds a single marker for the Congress (CCH).
- Each tour has its own layer, named after the tour (`Alsterdampfer`, `MiWuLa`, `XFEL`, …), with two features of the same colour:
- A marker at the venue, with a pictogram icon. Its name is an HTML link to the English tour page, and its description lists the directions from the Congress (English only).
- A line named "Way to …" from the Congress area (mostly S Dammtor) to the venue, with the same directions as its description.
- The lines were most likely drawn by hand with uMap's line tool rather than calculated by a routing service: most of them start near S Dammtor, but each at a slightly different point, the vertices are spaced irregularly (30 to 100 m on average, up to several hundred metres), and the XFEL route consists of two separately drawn pieces. The routes combine walking, bus, U-Bahn and S-Bahn.
To change the map, edit it on uMap (as the owner, or after the owner adds you as an editor); the website picks up changes immediately because the iframe loads the live map. When adding a layer, its ID has to be added to the `datalayers` parameter in the embed URL, which uMap's "Share" panel generates.
The uMap data has been converted into this format in [data/schedule/39c3.yaml](data/schedule/39c3.yaml), with English directions only and each route as one leg of mode `other`. To get the data out again, for example after changes on uMap:
- A single layer as GeoJSON: `https://umap.openstreetmap.fr/en/datalayer/1329184/<layer-id>/`. The layer IDs are listed in the `datalayers` parameter of the embed URL.
- The whole map: the "Download" option in uMap's share panel exports all layers as one GeoJSON file.
In the GeoJSON, `coordinates` are already in `[lon, lat]` order, the colour and icon are in each feature's `properties._umap_options`, and the directions are in `properties.description`.
## Shortcode: Image gallery
`{{< gallery >}}` shows a page's photos as square thumbnails, two per row on wide screens and one per row on narrow ones. Clicking a thumbnail opens the full image in a lightbox with its caption (or alt text) and credit; with more than one image, arrows (on screen, the arrow keys, or swiping) move between them, and Escape, the close button or a click beside the image closes it.
```markdown
{{< gallery >}}
{{< gallery-image src="hafenrundfahrt1.jpg" alt="Containerschiffe „HMM Dublin“ und „Ever Greet“ im Hafen" credit="© Wikipedia-User CC BY-SA 4.0 Shotbyp4ul" >}}
{{< gallery-image src="hafenrundfahrt2.jpg" alt="Das Speicherstadtrathaus" credit="© Wikipedia-User CC BY-SA 3.0 Magnus Manske" >}}
{{< /gallery >}}
```
| Param | Required | Content |
|---|---|---|
| `src` | yes | The image: a file in the page's folder, or a path in `themes/hackertours/assets/`. It must be a photo Hugo can resize (JPEG, PNG, WebP…), not SVG. |
| `alt` | yes | What the image shows, for people who can't see it. It names the thumbnail's link, so it can't be empty, and is shown in the lightbox when there is no caption. |
| `caption` | no | Context for everyone, shown under the thumbnail and in the lightbox. Say something the alt text doesn't: screen readers read both, so the same text would be heard twice. |
| `credit` | no | Photographer and licence, appended to the caption under the thumbnail and in the lightbox. |
`{{< gallery ratio="original" >}}` keeps each image's own aspect ratio instead of cropping it to a square; a gallery with a single image then spans the full width, as on the home page. Without `ratio` (or with `ratio="square"`), the thumbnails are square.
Hugo crops the square thumbnails (keeping the most interesting part of the picture) at build time; the lightbox shows the original file. Without JavaScript, a thumbnail links to the original file. A missing image, a missing `alt` or a `gallery-image` outside a `gallery` stops the build with an error that names the page.
## Shortcode: Event cards
The home page (`content/*/_index.md`) lists the events as cards with `{{< events >}}`, modelled on the cards of the [40C3 start page](https://events.ccc.de/congress/2026/infos/startpage.html). It reads `data/events.yaml`, which is shared by both languages, and shows the events in the order of the file, newest first:
```yaml
events:
- event: 39c3
title: { de: 39. Chaos Communication Congress, en: 39th Chaos Communication Congress }
motto: Power Cycles
start: "2025-12-27"
end: "2025-12-30"
venue: CCH
```
- `event` is the name of the event's section (`content/*/<event>/`), which the card links to. The card's heading shows it in capitals (`39C3`); `name` (optional) replaces that.
- `title` is the event's full name, with one entry per language, or one for both: `title: Easterhegg 2025`.
- `motto` and `venue` are shown as they are.
- `start` and `end` are `YYYY-MM-DD`. The card shows the range in the page's language, as on the 40C3 start page: `27.–30. Dezember 2025`, `27–30 December 2025`. Leave out `end` for a one-day event.
- `status` (optional): `inprogress` greys the card out, without a link, and marks it "In Vorbereitung" / "In progress", for an event whose tours aren't online yet. Remove it once the event's section exists.
- `credit` (optional) names the logo's authors and licence in Markdown, shown in the page footer, for logos whose licence asks for it.
The heading shows the event's logo, `themes/hackertours/assets/img/events/<event>.svg`, in the text colour. The SVG's own colours are ignored, only its shape counts, so use a version without a background. Where each logo comes from, and its licence, is listed in [themes/hackertours/assets/img/events/Sources.txt](themes/hackertours/assets/img/events/Sources.txt).
An event without a section, that isn't in progress either, gets a greyed-out card without a link, and the build logs a warning, as it does for a missing logo. Without a data file, or without any events in it, the shortcode renders nothing and the build logs a warning; to silence it, add `warning-events-empty` to `ignoreLogs` in `hugo.yaml`.
## Accessibility check
CI runs [pa11y-ci](https://github.com/pa11y/pa11y-ci) with the axe and HTML_CodeSniffer rules for WCAG 2 AA on every push and pull request, in its own job (`accessibility`), so findings show up without blocking the deploy. To run the same check locally (needs Node.js, Python 3 and Chrome or Chromium):
```shell
./scripts/pa11y.sh
```
The script builds the site, serves it on `localhost:8080` and checks every page in the sitemaps, except the past events and the individual news posts, which are kept as they were. The list of skipped sections is `EXCLUDE` in [scripts/pa11y.sh](scripts/pa11y.sh); the rules are in [.pa11yci.json](.pa11yci.json). pa11y only checks the light colour scheme.
Some things to keep in mind when writing pages:
- Give every image an alt text that says what it shows. The image title is the photo credit (`![Alt text](photo.jpg "© Photographer")`); it is shown below the image.
- Headings in a page start at `##`; `#` is the page title.
- Don't put information only into images, like directions on a map; write it out as text as well.