Local Setup (for Developers)

This option gives you a full local working environment in which you can preview all changes in the browser as you write. Recommended for structural changes, larger amounts of new content, or technical development.

What You Need

Installation on Windows

winget install --id Git.Git
winget install --id Hugo.Hugo.Extended
winget install --id GoLang.Go
winget install --id Microsoft.VisualStudioCode

Restart the terminal afterwards so that the newly installed programmes are available in PATH.

Verify the installation:

git --version
hugo version
go version

Installation on macOS

brew install git hugo go

Installation on Linux (Ubuntu/Debian)

sudo apt install git golang
# Hugo Extended is obtained from GitHub Releases (the apt version is often too old):
wget https://github.com/gohugoio/hugo/releases/download/v0.155.3/hugo_extended_0.155.3_linux-amd64.deb
sudo dpkg -i hugo_extended_0.155.3_linux-amd64.deb

Content structure – multiple repositories

SAMT-BU Docs uses content modules: content from different teams and pilots lives in separate GitHub repositories and is mounted automatically into the site at publication time. You do not need to clone all repositories to see the full site – Hugo fetches any missing modules from GitHub automatically.

Scenario A – Preview the full site only

Clone samt-bu-docs and start the server. Hugo fetches content from all module repositories automatically.

git clone --recurse-submodules https://github.com/SAMT-X/samt-bu-docs.git
cd samt-bu-docs
hugo server

Open http://localhost:1313/ in the browser.

Scenario B – Edit content in one specific repository

If you only want to edit content in, for example, samt-bu-pilot-2, you only need to clone that repository:

git clone https://github.com/SAMT-X/samt-bu-pilot-2.git
cd samt-bu-pilot-2
# edit files in content/
git add .
git commit -m "Description of the change"
git push

The site updates automatically at docs.samt-bu.no within about one minute. No local Hugo server is required.

Scenario C – Full local development across all repositories

If you want to edit content in several modules and see the changes live locally, clone all repositories as sibling folders and use the included helper script:

# Clone all repositories side by side
git clone --recurse-submodules https://github.com/SAMT-X/samt-bu-docs.git
git clone https://github.com/SAMT-X/samt-bu-pilot-1.git
git clone https://github.com/SAMT-X/samt-bu-pilot-2.git
# ... and so on for the modules you want to work with

# Start the local server (the script finds local clones automatically)
cd samt-bu-docs
tools/hugo-local.sh

The script reads hugo.toml, detects which modules you have cloned locally, and starts Hugo with those pointing to your local files. Modules you have not cloned are still fetched from GitHub.

samt-bu-docs/            ← always clone this one
samt-bu-pilot-1/         ← clone the ones you want to edit
samt-bu-pilot-2/
...

Including drafts:

tools/hugo-local.sh --drafts

Writing Content

Content files are standard Markdown files with a small header at the top (frontmatter):

---
title: "Page title"
weight: 30
---

Your content begins here in standard Markdown.

## Heading

A paragraph with **bold text** and *italic text*.

• title – page title displayed in the menu and at the top of the page
• weight – sort order (lower number = higher in the menu)
• draft: true – add this to hide the page from publication until it is ready

Saving and Publishing Changes

git add content/path/to/file/_index.en.md
git commit -m "Brief description of what you changed"
git push

GitHub Actions builds and publishes automatically after 1–2 minutes.

No write access to the repository? Create a pull request instead: git checkout -b my-contribution → make changes → git push origin my-contribution → open a PR on GitHub.

Useful Commands

Synchronisation and Conflict Handling

When several contributors work at the same time – or when someone saves a change via the browser interface while you have a local copy – the repositories can fall out of sync.

The Helper Scripts

Recommended workflow:

Before you start:   sync-all
While working:      commit frequently  →  push-all
When you are done:  sync-all

What sync-all Does

Manual Conflict Resolution

cd "<path to repo>"
git pull --rebase
# Open the file and look for conflict markers:
#   <<<<<<< HEAD  ← your version
#   =======
#   >>>>>>> abc1234  ← remote
# Delete the markers, keep the correct content.
git add <filename>
git rebase --continue
git push

go.mod / go.sum Conflicts

git pull --rebase
git checkout --theirs go.mod go.sum
hugo mod tidy
git add go.mod go.sum
git rebase --continue
git push

UUID Workflow and Rejected Pushes

GitHub Actions automatically commits UUID fields after pushing new files. If you push twice in quick succession:

git pull --rebase && git push

Prevention:

git add <files> && git commit -m "..." && git pull --rebase && git push