Replaces the line of links to previous events with cards after the 40C3 start page: each card has the event's logo (designs.events.ccc.de) in its heading bar, the motto, full name, dates and venue. 40C3 is greyed out as in progress; the other cards link to their tours. The cards reuse the theme's own colours -- the link colour for the motto and the heading and text colours for the rest -- on the hairline border and 0.25rem corners of the start page's cards. The logo credits that a licence asks for are shown in the page footer. The events shortcode reads data/events.yaml; the README documents it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
131 lines
7.8 KiB
Markdown
131 lines
7.8 KiB
Markdown
# 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. With JavaScript enabled, screens up to 666px
|
||
wide use a flat, borderless full-width menu button at the bottom and a scrollable
|
||
panel above it. The language link spans the panel's content width, includes the
|
||
translation icon, and uses the same font size as the menu links.
|
||
The page reserves space for the button so it does not cover content.
|
||
|
||
## 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
|
||
days:
|
||
- day: 1
|
||
date: "2025-12-27"
|
||
tours:
|
||
- { time: "11:30", tour: xfel, lang: deen }
|
||
- { 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 tour as fully booked. Other values are ignored.
|
||
|
||
For the events managed with Hackertours-Admin, the data file is generated by its website sync; don't edit it by hand.
|
||
|
||
Wide screens get one column per day on an hour grid, with tours that start at the same time side by side. The first column shows the hour wherever the first day has no tour in it. On narrow screens a day picker shows one day at a time, starting with today's day during the event.
|
||
|
||
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: 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 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 `assets/`. It must be a photo Hugo can resize (JPEG, PNG, WebP…), not SVG. |
|
||
| `alt` | yes | What the image shows. It is the thumbnail's alt text and the caption in the lightbox. |
|
||
| `credit` | no | Photographer and licence, shown under the thumbnail and in the lightbox. |
|
||
|
||
Hugo crops the thumbnails to squares (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, `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 [assets/img/events/Sources.txt](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 (``); 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.
|