Website Overview

This document provides a technical overview of the Brainhack School website infrastructure. It is intended for developers and maintainers. The main website repository is hosted at: https://github.com/school-brainhack/school-brainhack.github.io and the website is live at: https://school-brainhack.github.io

Goals

The Brainhack School website serves several purposes:

Central hub for course materials, lectures, and projects
Archive of past editions
English-only content
Static and easily deployable via GitHub Pages

We use Hugo for its static site generation, GitHub Pages compatibility, and scalability, despite its… eccentricities.

Directory Layout (as of 2025)

├── config.yaml                 # Site configuration
├── content/                   # Markdown-based content
│   └── en/                    # English pages
│       └── sites/             # One folder per local site (each with image + index.md)
├── data/                      # Structured data for modules, instructors, etc.
│   └── en/
│       ├── clients/           # YAML files defining sponsor entries (1.yaml, 2.yaml, ...)
│       ├── instructors.yaml   # List of global team members
│       └── carousel/          # Slides for homepage carousel (data_science.yaml, etc.)
├── static/                    # Static assets (img, css, etc.)
│   └── img/                   # Logos, favicons, media
├── layouts/                   # Custom Hugo templates
│   └── partials/, _default/, etc.
├── themes/                    # Contains hugo-universal-theme
├── public/                    # Output folder (auto-generated)
├── .github/workflows/         # GitHub Actions workflows

Updating `config.yaml`

This file contains the core Hugo configuration.

Top-Level Fields

baseURL: "https://school-brainhack.github.io/"
languageCode: "en"
title: "Brainhack School"
theme: "hugo-universal-theme"
defaultContentLanguage: "en"
style: green
logo: "img/logo_brainhack_2025.png"
logo_small: "img/logo-small_2025.png"

Disabling Sponsors Section

To hide the sponsors section (labeled “Clients” in the theme), locate the following block in config.yaml and set enable: false:

clients:
  enable: true
  title: Sponsors
  subtitle: ""

Change to:

clients:
  enable: false

This will disable the rendering of the sponsors block from the homepage.

Editing Sponsors

Sponsor entries are defined in separate YAML files located in data/en/clients/:

data/en/clients/
├── 1.yaml
└── 2.yaml

Each file typically contains:

title: Sponsor Name
image: "img/sponsor-logo.png"
url: "https://sponsor-website.com"

To add or remove sponsors, simply create, edit, or delete these numbered .yaml files.

Editing the Global Team

The list of instructors and organizers shown as the “Global Team” is stored in a single YAML file:

data/en/instructors.yaml

Each entry includes tags like:

- name: Lune Bellec
  gh: pbellec
  email: lune.bellec@criugm.qc.ca
  website:
  affiliation: University of Montreal
  urlaff: https://umontreal.ca

Supported tags: name, gh (GitHub handle), email, website, affiliation, urlaff, twitter, week, weight, and content.

💡 Image: if gh is defined, the image is pulled from GitHub. Otherwise, add a custom image to static/img/instructors/.

To remove someone from the team, delete their entry. To reorder, use weight or simply rearrange the list.

Editing the Homepage Carousel

The top homepage carousel is one of the signature visual features of the site. Each slide is defined in a separate YAML file under:

data/en/carousel/

Examples include:

├── code.yaml
├── brainhack_school.yaml
├── hpc.yaml
├── ml.yaml
├── neuroimaging.yaml
├── open_data.yaml
└── visu.yaml

The file brainhack_school.yaml is typically used for the first (main) slide and must be updated each year.

Sample structure:

weight: 0
title: "Brainhack School"
description: >
  <ul class="list-style-none">
    <li>Worldwide</li>
    <li>2025</li>
  </ul>
image: "img/carousel/fig_data_science.png"

You can control the order of the slides with the weight field. Lower values appear first.

Images must be stored in static/img/carousel/.

Managing the List of Sites

Each participating site has its own folder and landing page under:

content/en/sites/

Example structure:

├── criugm/
│   ├── criugm.png
│   └── index.md
├── polytechnique/
│   ├── polytechnique.jpeg
│   └── index.md
├── toronto/
│   ├── toronto.png
│   └── index.md
└── _index.md              # Overview index for all sites

Each site folder must include:

an index.md file with the site’s description and metadata
a site logo/image referenced from the markdown (can be .jpg, .png, or .jpeg)

To add a new site:

Create a new subfolder under content/en/sites/
Add index.md with front matter
Add a representative image

💡 The _index.md file provides the parent page that lists all sites.

🔗 Registration Page (Hugo site)

To edit the registration page on the main website, update the Markdown file:

content/en/register.md

Embed the Google Form using standard HTML inside the markdown file, for example:

<iframe src="https://docs.google.com/forms/d/e/EXAMPLE_FORM_ID/viewform?embedded=true" width="100%" height="1200" frameborder="0" marginheight="0" marginwidth="0">Loading…</iframe>

Replace the EXAMPLE_FORM_ID with the actual form ID provided by Google.

🌐 Managing Past Editions

To ensure proper navigation between yearly editions of the website, it’s recommended to fork each year’s site into its own GitHub organization or repo (e.g. 2025-school-brainhack.github.io).

The past editions are referenced in the main site’s config (usually in the navigation menu) with entries like:

- parent: past
  name: 2024
  url: https://2024-school-brainhack.github.io/
- parent: past
  name: 2022
  url: https://2022-school-brainhack.github.io/
- parent: past
  name: 2021
  url: https://psy6983.brainhackmtl.org/
- parent: past
  name: 2020
  url: https://school2020.brainhackmtl.org/
- parent: past
  name: 2019
  url: https://brainhackmtl.github.io/school2019/
- parent: past
  name: 2018
  url: https://brainhackmtl.github.io/school2018/

When preparing a new edition:

Fork the current repository into a dedicated organization (e.g. 2025-school-brainhack)
Set GitHub Pages to publish from main or docs/
Update the past editions list on the main site

🧩 Sidebar Templates and Localised Content

The Brainhack School website uses custom sidebar templates based on page context:

layouts/partials/sidebar.html: Used on the project gallery
layouts/partials/sidebar_modules.html: Used for teaching modules
layouts/partials/sidebar_sites.html: Used for the list of participating sites

Each of these partials can be injected into the main layout depending on the active section.

Sidebar Content Source

Text blocks such as:

<p>{{ T "SidebarSub" | markdownify }}</p>

Reference the translation string with ID SidebarSub in the file i18n/en.yaml. This is part of Hugo’s i18n system, which was originally designed for multilingual support but is now also used as a message registry.

To update or remove this kind of string:

Open i18n/en.yaml
Edit the relevant id (e.g. SidebarSub)
Rebuild the site locally with hugo server -D

🗂️ The i18n File as a Message Registry

The file i18n/en.yaml contains a list of string identifiers and their English translations. While originally intended for multilingual support, it is now used to centralize fixed text elements like button labels, form fields, and sidebar messages.

Example entries:

- id: home
  translation: "Home"
- id: contactTitle
  translation: "Contact"
- id: contactForm
  translation: "Contact form"
- id: contactName
  translation: "Your Name"
- id: contactSend
  translation: "Send Message"

To locate uneditable static text, search this file using grep.

Technology Stack

Hugo (v0.108.0, extended edition)
GitHub Pages for deployment
GitHub Actions for CI/CD
YAML/Markdown for content and config
Optional: dart-sass-embedded for themes using SASS

Deployment Process

A GitHub Actions workflow (.github/workflows/hugo.yml) builds the site and uploads it to GitHub Pages.
Only commits to main trigger production builds.
Artifacts are built into public/ by Hugo.

Known Pain Points

Hugo’s layout system is inconsistent across content types
Theme (hugo-universal-theme) is dated
Hugo GitHub Action needs regular updating

Developer Tips

Use hugo server -D for local development with drafts
Use tree -L 2 liberally to stay sane and map your environment