Course Template

The course template is a complete course website to copy and fill with your own material. It has two sample courses with lessons, assignments, schedules, and announcements, hands-on labs grouped by course, a course catalog, and a GitHub Actions workflow that publishes the site to GitHub Pages. See the live demo.

There are two ways to start from it, and both produce the same files:

Run sarde new site with --template course. The command downloads the template from the getsarde/sarde-templates repository, pinned to your Sarde version.
Clone that repository and copy its course/ folder.

Create a course site

Create the site and move into it:
Terminal window
```
sarde new site my-college --template course
cd my-college
```
→ The command prints the next step and explains how to turn on the GitHub Pages workflow. See Publish on GitHub Pages.
Start the dev server:
Terminal window
```
sarde dev
```
Open http://localhost:4727. The site rebuilds and the browser reloads each time you save a file.

To start from the repository instead, clone it, copy the course/ folder, and run the dev server inside the copy:

git clone https://github.com/getsarde/sarde-templates.git
cp -r sarde-templates/course my-college
cd my-college
sarde dev

What's in the template

my-college/
  sarde.yaml                   # site title, homepage hero, header links, plugins
  kazari.config.yaml           # code block options
  .github/
    workflows/
      deploy.yml               # publishes the site to GitHub Pages
  content/
    _index.md                  # homepage, with a link to each course
    announcements.md           # news for every course
    courses/
      _index.md                # course catalog at /courses/
      web-fundamentals/
        _index.md              # course overview and Course info card
        announcements.md       # news for this course
        schedule.md            # weekly plan
        html-basics.md         # lesson
        css-layout.md          # lesson
        assignments/
          _index.md
          build-a-page/          # a page bundle: the page and its files
            index.md
            rubric.pdf
            starter.zip
            screenshot.png
          style-a-card.md
      python-essentials/       # a second course with the same shape
    labs/
      _index.md                # one card per course
      web-fundamentals/        # the labs for one course
      python-essentials/
  public/
    favicon.ico                # placeholder icon, the Sarde logo
    files/
      syllabus.pdf             # site-wide file, linked as /files/syllabus.pdf
    images/                    # homepage hero images

Sarde detects courses as a docs collection and labs as the labs collection from their directory names, so neither needs configuration.

Courses

Each directory in content/courses/ is one course. With two or more courses, each one becomes a tab in the course switcher at the top of the sidebar, and the sidebar shows only the current course's pages. Tabbed Navigation explains how tabs work.

With a single course, tabs turn off, so the course switcher and the catalog disappear. To keep them for one course, turn tabs on in sarde.yaml:

sarde.yaml

collections:
  courses:
    tabs: true

Course overview

A course's _index.md is its overview page, listed as Overview at the top of the course sidebar. Its fields also appear outside the page:

Field	Shown in
`title`	Course switcher and catalog card
`description`	Course switcher menu, catalog card, and under the page title
`icon`	Tile in the switcher and on the catalog card, in place of the course's initials
`sidebar.badge`	Catalog card, for example Beginner

The overview ends with a Course info card for the instructor's contact details and office hours. It uses the card extension:

:::card[Course info](icon="user")
- **Instructor:** Your Name, [you@example.edu](mailto:you@example.edu)
- **Office hours:** Mondays 12:00 to 13:30 and Fridays 12:00 to 13:00, online
- **Syllabus:** [download the PDF](/files/syllabus.pdf)
- **Plan:** see the [schedule](/courses/web-fundamentals/schedule/) and the latest [announcements](/courses/web-fundamentals/announcements/)
:::

Pages in a course

The course sidebar lists Overview first, then the course's pages in sidebar.order:

Order	Page
1	`announcements.md`
2	`schedule.md`
3, 4	The lessons, `html-basics.md` and `css-layout.md`
5	The `assignments/` group

Give each new lesson a sidebar.order to place it. assignments/ is a sidebar group with its own _index.md, which sets the Assignment badge on the group. The assignments inside it are ordered the same way.

Files and images

The template shows the two places a file can live, which Images and Assets describes in full.

Next to the page. The Build a Page assignment is a directory, assignments/build-a-page/, whose index.md sits beside rubric.pdf, starter.zip, and screenshot.png. That makes it a page bundle: Sarde copies the three files with the page, and the screenshot gets responsive WebP variants and a blurred placeholder. The page links them by bare file name:

Grading follows the [rubric](rubric.pdf).
:::link-button[Download the starter files](href="starter.zip" icon="download" variant="secondary")
:::
![Example of a finished page](screenshot.png)

Write rubric.pdf, not ./rubric.pdf. A path that starts with ./ is resolved as a link to a page and fails the build. The URL of the page does not change when it becomes a bundle, so links to /courses/web-fundamentals/assignments/build-a-page/ keep working. Only index.md forms a bundle; files next to an _index.md are not copied.

In public/. public/files/syllabus.pdf is served at /files/syllabus.pdf and linked from the Course info card and the schedule. Use public/ for files that several pages share. Images placed there are served as they are, without responsive variants.

The course catalog

content/courses/_index.md is the catalog at /courses/, where the header's Courses link and the homepage's Browse Courses button lead. Its text appears above one card per course, in tab order. Each card shows the course's tile, description, and badge.

The catalog exists because that _index.md has a body. With frontmatter only, /courses/ redirects to the first course instead. See The collection root.

Schedules

Each course's schedule.md is a timeline with one entry per week:

Entry title: the week and its topic.
Heading: a guiding question in bold on the first line, which the timeline styles as the entry's heading.
Items: a list where each item opens with an icon for its type.

content/courses/web-fundamentals/schedule.md

:icon[book-open] Lesson · :icon[flask-conical] Lab · :icon[pencil] Assignment · :icon[users] In class
:::timeline
== Week 1: HTML structure
**How is a web page put together?**
- :icon[calendar] Sep 7 to 13
- :icon[book-open] [HTML Basics](/courses/web-fundamentals/html-basics/)
- :icon[flask-conical] [Hello World](/labs/web-fundamentals/hello-world/)
- :icon[users] Course kickoff and setup check
:::

→ The first line is the legend. In each entry, the icons replace the list bullets. See Icon lists.

Long courses

A timeline is always open, which reads well for a few weeks. For a full semester, a list of collapsible weeks keeps the page short. Put each week in a :::details block titled with its topic, inside an :::accordion(independent), and add open to the current week:

:::accordion(independent)
:::details[Week 1: HTML structure]
- :icon[calendar] Sep 7 to 13
- :icon[book-open] [HTML Basics](/courses/web-fundamentals/html-basics/)
:::
:::details[Week 2: CSS layout] open
- :icon[calendar] Sep 14 to 20
- :icon[book-open] [CSS Layout](/courses/web-fundamentals/css-layout/)
:::
:::

Icon lists work inside details panels too.

Announcements

The template posts announcements in three places:

Course announcements: each course's announcements.md holds its news, newest first, one ### heading per item.
Site-wide announcements: content/announcements.md holds news for every course and links to each course's announcements and schedule. The header's Announcements link opens it.
Banner: a one-line strip above the header, from the announcements plugin.

The sample banner appears only on one course's lessons and labs, through show_on:

sarde.yaml

plugins:
  config:
    announcements:
      items:
        - id: web-fundamentals-assignment-1
          message: "Web Fundamentals: Assignment 1 is due at the end of week 2."
          type: info
          show_on:
            - /courses/web-fundamentals/**
            - /labs/web-fundamentals/**

The template's sarde.yaml also lists every default plugin under plugins.enabled before announcements and telescope, because a plugins.enabled list replaces the default set rather than adding to it. Placement explains how the banner strip behaves.

Labs

content/labs/ groups the labs by course, with one directory per course and one directory per lab inside it. Lab numbers restart in each course. web-fundamentals/hello-world/ is a single-page lab: it has only an _index.md. The _index.md of each course directory carries the same sidebar.badge as the course itself, so the cards on /labs/ match the ones on /courses/. Labs covers the structure, step order, progress bars, and learning objectives.

Hero: homepage.hero in sarde.yaml sets the homepage title, subtitle, images, and two buttons, Browse Courses (/courses) and View Labs (/labs).
Header links: the header lists the Courses and Labs collections, followed by the header.links entries for Announcements and Tags.
Homepage content: content/_index.md links to each course with a card.
Quick navigation: the Telescope plugin is on, so Ctrl+/ (Cmd+/ on Mac) opens a quick search that jumps to any page by name.

Reading aids

The template's sarde.yaml enables three plugins that help with long lessons and labs, listed under plugins.enabled with the others:

Scroll to Top: a button at the bottom of the screen that returns to the top of the page, shown after the reader scrolls down.
Reading Progress: a bar under the header that fills as the reader scrolls, and an estimated reading time under the page title. Both appear on lessons, assignments, schedules, announcement pages, and lab steps, but not on course overviews, lab introductions, or the catalog.
Focus Mode: Shift+F or the button at the bottom right hides the sidebar and table of contents on course and lab pages. It works on screens at least 1024 pixels wide.

To turn one off, remove it from plugins.enabled.

Replace the sample content

In sarde.yaml, set site.title, site.description, and site.url, then change the hero text and buttons under homepage.hero.
Replace the sample courses in content/courses/, and update the catalog text in content/courses/_index.md.
Replace the sample labs in content/labs/.
Update content/announcements.md, each course's announcements.md and schedule.md, and the banners under plugins.config.announcements in sarde.yaml.
Update the course links in content/_index.md.
Replace public/favicon.ico, the Sarde icon, with your own. Sarde picks up a favicon.svg, favicon.ico, or favicon.png in public/ without any configuration.
Replace the placeholder files: rubric.pdf, starter.zip, and screenshot.png in content/courses/web-fundamentals/assignments/build-a-page/, and public/files/syllabus.pdf.
Search the content/ directory for the word "Replace". Most sample pages open with a sentence that starts with it, which marks text you have not replaced yet.

The sample lessons and labs also show Markdown extensions and code-block options in context. Using Extensions and Code Blocks document each one.

Publish on GitHub Pages

.github/workflows/deploy.yml builds the site and publishes it to GitHub Pages on every push to main.

Push the site to a GitHub repository.
In the repository, open Settings > Pages and set Source to GitHub Actions.
Push to main, or run the workflow from the Actions tab.

→ The site is published at https://<owner>.github.io/<repository>/.

The workflow reads the site's address and base path from GitHub Pages and passes them to Sarde, so sarde.yaml needs no deployment settings, and a custom domain set under Settings > Pages works the same way. Until Pages uses GitHub Actions as its source, the workflow fails on every push. If you host the site elsewhere, delete the workflow file. GitHub Pages and Deploying cover other options.