Skip to content

Bern Capitals · library

How the site works

For everyone who edits or extends berncapitals.ch: how pages are built from blocks, where content lives, and how a change gets online.

How the site works · Brand guide · Design system · Blocks · Site

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

LayerWhereWhat it decides
Design systemsite/design-system/Colours, fonts, spacing and a few shared components. See the design system and the brand guide.
Blockssite/blocks/<name>/Reusable sections: a page header, a news list, a league table, people cards. All of them are shown in the block library.
Contentsite/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:

FileAddress
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:

content/pages/geschaeftsstelle/trainings.json (shortened)json
{
  "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:

WriteGet
## HeadingSection heading (### and #### for smaller ones)
A blank lineNew paragraph
**bold** and *italic*bold and italic
[Spielplan](/spielplan/)a link
- itema bullet list (1. for numbered)
> Quotea pull quote in the marker font
![Alt text](/media/photos/action-jubel.jpg "Caption")a wide photo with caption
| a | b |a table
09.03.2023: Titlea 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:

A news list for the 1. Ligajson
{ "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:

The next games of one teamjson
{ "block": "agenda", "data": {
    "title": "Nächste Spiele",
    "games": { "$data": "swissunihockey/teams/429529.json#/games" }
} }

Adding a news article

  1. Put the photo into content/media/ (a JPEG of about 1600 px width is plenty).
  2. Copy an existing file in content/pages/news/ and give it a new file name: that becomes the address.
  3. 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).
  4. Write the text in the prose block.
  5. 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

CommandWhat it does
node site/build.mjs --checkValidates everything and writes nothing. Must end without errors or warnings.
node site/serve.mjs --watchPreview on http://localhost:4321, rebuilt on every change.
node site/sync.mjsFetches fresh games, tables and match reports (needs internet).
node site/deploy.mjsUploads a private preview.
node site/deploy.mjs --promoteMakes 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:

  1. A block is a folder with block.html, schema.json and example.json, plus optional block.css and block.mjs.
  2. 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.
  3. CSS selectors start with .b-<name> and use design tokens only: no colour codes, no font names. Reuse the .ds-* components.
  4. Every image gets a sizes attribute that says how wide it is shown.
  5. 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.