The site is generated from plain files. Nobody edits HTML: you describe a page as a list of blocks with their data, and the build turns that into the finished site. Every block knows exactly which data it accepts, so a mistake stops the build with a clear message instead of breaking the page.
Three layers
| Layer | Where | What it decides |
|---|---|---|
| Design system | site/design-system/ | Colours, fonts, spacing and a few shared components. See the design system and the brand guide. |
| Blocks | site/blocks/<name>/ | Reusable sections: a page header, a news list, a league table, people cards. All of them are shown in the block library. |
| Content | site/content/ | The pages themselves, the menu and footer, photos and documents. |
Editors only ever touch content. New kinds of sections are new blocks. The design system changes rarely and on purpose.
A page is a file
Every file in content/pages/ becomes one page, and its path is the address:
| File | Address |
|---|---|
| content/pages/index.json | / |
| content/pages/teams.json | /teams/ |
| content/pages/geschaeftsstelle/trainings.json | /geschaeftsstelle/trainings/ |
| content/pages/news/<slug>.json | /news/<slug>/ |
A page names its template, a title, a short description for search engines and, per region, the blocks to show in order:
{
"template": "page",
"title": "Trainings",
"description": "Trainingszeiten aller Teams der Bern Capitals.",
"regions": {
"main": [
{ "block": "page-hero", "data": { "eyebrow": "Geschäftsstelle", "title": "Trainings" } },
{ "block": "training-schedule", "data": { "…": "…" } },
{ "block": "cta-band", "data": { "title": "Mittrainieren?", "link": { "label": "Kontakt", "href": "/geschaeftsstelle/" } } }
]
}
}
Which fields a block accepts is listed in the block library under «Data fields».
Regions: header, main, footer
The page template has three regions. main is set by each page. header (logo and menu) and footer («Wohin als Nächstes?», sponsors, contact) are set once in content/site.json and appear on every page. A page can still set a region itself; an empty list removes it.
The menu, the sponsors and the end-of-page suggestions are therefore edited in one place: content/site.json.
Writing text
Longer text goes into a prose block, written in a small, safe form of Markdown:
| Write | Get |
|---|---|
| ## Heading | Section heading (### and #### for smaller ones) |
| A blank line | New paragraph |
| **bold** and *italic* | bold and italic |
| [Spielplan](/spielplan/) | a link |
| - item | a bullet list (1. for numbered) |
| > Quote | a pull quote in the marker font |
|  | a wide photo with caption |
| | a | b | | a table |
| 09.03.2023: Title | a dated entry, e.g. for a blog-like page |
Three or more headings automatically get a numbered «Auf dieser Seite» list beside the text on wide screens. The first short paragraph is set as a lead.
Lists that fill themselves
Some data is not typed into the page but pulled in during the build.
News lists. Every article in content/pages/news/ carries a meta object (date, teaser, photo, team tags). A block can ask for all articles, or those of one team, newest first:
{ "block": "news-archive", "data": {
"title": "News Herren 1. Liga",
"articles": { "$pages": { "dir": "news", "tag": "herren-gf-1-liga", "limit": 10 } }
} }
A new article file therefore shows up on the home page, in /news/ and on its team's pages without touching those pages.
Games, tables and match reports come from Swiss Unihockey. node site/sync.mjs downloads them into content/data/ (never edit that folder by hand), and pages point at the part they need:
{ "block": "agenda", "data": {
"title": "Nächste Spiele",
"games": { "$data": "swissunihockey/teams/429529.json#/games" }
} }
Adding a news article
- Put the photo into content/media/ (a JPEG of about 1600 px width is plenty).
- Copy an existing file in content/pages/news/ and give it a new file name: that becomes the address.
- Change title, description and meta: date (YYYY-MM-DD), teaser, image, tags (e.g. herren-gf-1-liga) and kicker (the team name shown above the headline).
- Write the text in the prose block.
- Check, preview and publish (below).
Photos
Always reference the original file under /media/…. The build makes smaller copies (240 to 1200 px wide) and lets every phone download only the size it needs. Never edit, filter or recolour photos or the logo, and always describe the photo in the alt text.
Check, preview, publish
| Command | What it does |
|---|---|
| node site/build.mjs --check | Validates everything and writes nothing. Must end without errors or warnings. |
| node site/serve.mjs --watch | Preview on http://localhost:4321, rebuilt on every change. |
| node site/sync.mjs | Fetches fresh games, tables and match reports (needs internet). |
| node site/deploy.mjs | Uploads a private preview. |
| node site/deploy.mjs --promote | Makes the preview public. Only when the change is approved. |
When the build stops, it names the file, the block and the field, for example: content/pages/index.json → main[1] (agenda) /games/0/date: is not a valid date.
Rules for blocks
For people building new blocks:
- A block is a folder with block.html, schema.json and example.json, plus optional block.css and block.mjs.
- schema.json describes all data an editor can change, with a description on every field and no extra fields allowed. example.json must pass it; it is what the library shows.
- CSS selectors start with .b-<name> and use design tokens only: no colour codes, no font names. Reuse the .ds-* components.
- Every image gets a sizes attribute that says how wide it is shown.
- The framework (build.mjs, serve.mjs, sync.mjs, deploy.mjs, lib/, design-system/) changes only on purpose, never as a side effect of a block.
The full technical reference is site/README.md in the repository.