Labs

A directory named labs becomes a step-by-step workbook: each lab gets its own sidebar, its own progress bar, and prev/next navigation that stays inside the lab.

content/
  labs/
    _index.md
    getting-started/
      _index.md
      01-install.md
      02-build.md
    deploying/
      _index.md
      01-ship.md

Detection is by directory name, and labs is the only name that works. Unlike the docs collection, there are no synonyms.

Two structures

Sarde picks the structure by looking at the labs themselves. If any directory under labs/ has its own subdirectories, the collection is treated as a set of courses.

labs/
  getting-started/
    _index.md
    01-install.md
    02-build.md

labs/
  _index.md                # landing page: one card per course
  web-fundamentals/
    _index.md              # course page: one card per lab
    build-a-webpage/
      _index.md            # Lab 1: overview and learning objectives
      scaffold.md          # step, sidebar.order: 1
      add-styles.md        # step, sidebar.order: 2
      deploy.md            # step, sidebar.order: 3
    hello-world/
      _index.md            # Lab 2: a single-page lab
  python-essentials/
    _index.md
    cli-todo-app/
      _index.md            # Lab 1 again: numbering restarts per course
      project-setup.md
      add-commands.md
      testing.md

Both work with no configuration. Lab numbering restarts inside each course, so web-fundamentals and python-essentials both begin at Lab 1.

Step and lab order

Steps follow sidebar.order in their frontmatter, lowest first. A numeric filename prefix works too: 01-install.md sorts as sidebar.order: 1, and the prefix is dropped from the URL (/labs/getting-started/install/). When a file has both, the frontmatter value wins.

Labs inside a course, and courses inside labs/, are ordered the same way, by sidebar.order on their _index.md, then by title. A lab's number follows that order, so reordering labs renumbers them.

Single-page labs

A lab directory that contains only an _index.md is a complete lab. It gets its lab badge, a Step 1 of 1 progress bar, and a sidebar with just the Overview entry. Use it for short exercises that fit on one page, such as hello-world in the example above.

Layouts

Landing pages and lab pages use different layouts, which is what makes the collection read as a workbook rather than a flat set of docs.

Set layout in a page's frontmatter to override any of these.

Tags in a lab page's frontmatter appear under the title and link to their tag pages, as on docs pages.

Each card on a landing page shows a tile with the index page's sidebar.icon, or the initials of its title when there is no icon, followed by the title and description. A sidebar.badge on the index page appears on the card, so a course can carry the same level badge in labs/ as in its docs collection. Cards also show a count taken from what the directory holds: 2 labs for a course, 4 steps for a lab. The step count includes the Overview page, so it matches the Step 1 of 4 progress bar inside the lab, and a single-page lab reads 1 step. The wording comes from the labs.lab_count and labs.step_count translation strings. Add image to a lab's _index.md for a thumbnail above the card body.

Per-lab sidebar

Inside a lab, the sidebar lists only that lab. Other labs in the collection do not appear. The first entry is always Overview, linking to the lab's _index.md, followed by the steps in sidebar.order. The Overview label is the labs.overview translation string, so it follows the page language.

Prev/next stops at the lab boundary. The last step of one lab has no Next link into the following lab, so a reader finishing a lab returns to the landing page rather than falling into unrelated material.

Progress and lab number

Every page in a lab renders two indicators, both filled in automatically:

• A lab badge above the title reading Lab 1, numbered by the lab's position among its siblings.
• A progress bar reading Step 2 of 3, between the badge and the title.

The step count includes the Overview page. A lab with an _index.md and two steps reports three steps, and the Overview is step 1.

To rename the badge, set a label on the collection:

collections:
  labs:
    labs:
      label: "Exercise"

Pages then read Exercise 1. The word is used for the badge only; the progress bar always says "Step".

Learning objectives

Add learning_objectives to a lab's frontmatter to render a highlighted list at the top of the page:

---
title: Getting Started
learning_objectives:
  - Install the toolchain
  - Run the first build
---

The field takes a list of strings and works on any page in the collection, though it usually belongs on the lab's _index.md.

Defaults

The labs collection is configured on detection. Override any of it under collections.labs in sarde.yaml.