Page anatomy
This page documents how workshop pages are structured: front matter, file naming and folder ordering. Copy these conventions when you add pages to your own lab.
Every page starts with a YAML front matter block delimited by ---. Never begin a page with a # heading - the title comes from the front matter.
Source:
1
2
3
4
---
title: "Page Title"
weight: 10
---| Field | Type | Description |
|---|---|---|
title | string | Page title shown in the navigation sidebar |
weight | number | Controls page ordering (lower appears first) |
| Field | Type | Description |
|---|---|---|
linkTitle | string | Shorter title shown in the navigation menu when the full title is too long |
::alert[A chapter front matter field is not part of the current Workshop Studio content reference, so this template does not use it. Page grouping is done with folders and weight, not a chapter flag. If you have seen chapter: true in an older Hugo-based workshop, treat it as legacy and rely on title + weight instead.]{type="info" header="A note on "chapter""}
- Every content file is named
index.en.mdfor a section landing page, or<name>.en.mdfor step pages (for examplestep-1.en.md). - The
.ensegment is the locale code.en-USisen. Other locales use their own suffix (for examplepage.ja.md). - Every folder under
content/must contain at least oneindex.en.md, or the build fails. - Folder and file names use kebab-case:
getting-started,lab-1,step-2a.
Ordering within a level is controlled entirely by weight. Use increments of 10 for both sections and pages so you can insert new content later without renumbering.
1
2
3
4
5
6
7
8
9
10
11
12
content/
├── index.en.md # weight: 0 (landing page)
├── getting-started/
│ ├── index.en.md # weight: 10
│ └── ide-setup.en.md # weight: 20
├── lab-1/
│ ├── index.en.md # weight: 20 (section landing page)
│ ├── step-1.en.md # weight: 10
│ ├── step-2.en.md # weight: 20
│ └── conclusion.en.md # weight: 90
├── conclusion.en.md # weight: 90
└── cleanup.en.md # weight: 100A section's landing page is its index.en.md; its step pages are weighted relative to each other inside that folder.
At the repository root, alongside content/:
| Path | Purpose |
|---|---|
contentspec.yaml | Workshop configuration (required, at the root) |
content/ | All Markdown pages |
static/ | Images referenced as /static/.... External images are blocked |
assets/ | S3-uploaded downloadable files (scripts, documents), referenced with /builds/static. Never put downloads in static/ |
Link between pages with root-relative paths (no locale suffix, no index).
Source:
1
See the [getting started](/getting-started) section for setup instructions.