Customizing

Layout toggles

Hide the sidebar, drop the progress bar, change the prose width.

Six boolean params and one width param control the major layout decisions. Flip them in hugo.toml to suppress chrome you don’t need.

All toggles #

[params]
  defaultMode     = "auto"     # "light" | "dark" | "auto"
  showThemeToggle = true       # sun/moon button in the header
  showSidebar     = true       # left workshop nav on workshop pages
  showToc         = true       # right-rail "On this page"
  showProgress    = true       # gradient reading-progress bar
  showLightTrails = true       # decorative gradient streaks in hero/footer
  contentMaxWidth = "720px"    # prose column width on workshop pages

When to flip each #

defaultMode #

auto honors prefers-color-scheme on first visit; the user can override via the toggle and their choice persists in localStorage. Set to "dark" if you’re shipping a black-tie product (Splunk, Datadog, observability tooling tends to look right in dark). "light" if you want a more bookish feel.

showThemeToggle #

Hide the sun/moon button when you’ve decided your site is one-mode-only. Combine with defaultMode = "dark" (or "light") to commit fully to a single mode.

showSidebar #

Defaults to true. Hide it for sites where every page is a top-level resource (more like a blog than a multi-chapter workshop). When the page has no siblings, the sidebar is automatically suppressed even with this true.

showToc #

Right-rail “On this page” auto-generated from H2/H3 headings. Hide for landing pages or pages with little structure. Auto-suppresses when the page has no headings. Override per-page with show_toc = false (or true) in front matter — see Front matter » show_toc . Note: [params] uses camelCase (showToc), front matter uses snake_case (show_toc).

showProgress #

The gradient bar at the top of the page that fills as you scroll. Useful on long workshop pages, distracting on short marketing pages. Defaults to true.

showLightTrails #

The decorative gradient blobs in the top-right of the hero and bottom-left of the footer. Pure decoration — set to false for a flatter, less editorial look.

contentMaxWidth #

The prose column cap on workshop pages. Default is 720px which works for IBM Plex Sans at the default body size. Bump up if you want denser pages, down if you want a more book-like feel.

Workshop version badge #

The site footer can render a shields.io badge showing the latest release tag from a GitHub repo — handy for workshop content that ships in versioned drops.

[params]
  versionBadgeRepo  = "splunk/observability-workshop"   # owner/repo on GitHub
  versionBadgeColor = "FF007F"                          # hex without the leading #

The badge appears between the copyright and “Built with Hugo” line in the footer, on every page. Leave versionBadgeRepo empty (the default) to omit the badge entirely. The repo must be public — the badge is generated by shields.io fetching from the GitHub Releases API.

Repo link & copyright #

Two params control the chrome that points back at your source repo and the legal text in the footer. Both are footer-adjacent (and one is also header-adjacent), and both should be set early — they’re the first things readers notice if they’re wrong.

[params]
  repoURL   = "https://github.com/your-org/your-workshop"
  editURL   = "https://github.com/your-org/your-workshop/edit/main/exampleSite/"
  copyright = "© {year} Your Company. All rights reserved."

repoURL #

Repo home (https://github.com/owner/name). Two places use it:

• A small GitHub icon appears in the site header, linking out to the repo. Useful for open-source workshop content where readers may want to file issues or star the repo.
• Section landing pages get a “View on GitHub” button next to the “Browse pages” CTA — same destination.

Leave empty to suppress both. Not restricted to GitHub — any URL works, but the icon is the GitHub mark, so other hosts will look odd.

editURL #

Per-page “Edit this page on GitHub” link rendered at the bottom of every workshop page. The theme appends the page’s .File.Path to whatever you set, so the URL must end at the directory that contains your content tree. For example, if your content lives at content/en/workshops/foo.md in repo your-org/workshop, set:

editURL = "https://github.com/your-org/workshop/edit/main/content/"

The link auto-suppresses on pages that don’t have a backing source file (generated index pages, taxonomies). Leave empty to omit the link entirely.

copyright #

The text in the footer’s bottom-left, next to “Built with Hugo”. HTML is allowed (the value is passed through safeHTML), so you can include entity references like © for the copyright symbol or wrap parts in <a> tags.

The literal token {year} is substituted with the current year at build time — use it instead of hard-coding so the footer doesn’t go stale every January:

copyright = "© {year} Acme Corp. All rights reserved."

If you leave copyright unset, the footer falls back to © <year> <site title> — fine for personal projects, probably not what you want for anything with a legal department.

Per-page overrides #

Some toggles can be overridden per-page in front matter:

+++
title   = "..."
hidden  = true        # exclude from sidebar, TOC, search, prev/next
nopager = true        # render the page but suppress the prev/next pager
show_toc = false       # hide the right-rail TOC on this page only
+++

hidden: true is the canonical way to draft pages that should ship invisibly. nopager: true is for special pages (intro, outro, glossary) where prev/next doesn’t make sense. show_toc: false widens the content column on dashboard-style or landing pages.

Picking which sections appear on the home #

Two equivalent forms — pick whichever fits where you’d rather edit:

# hugo.toml — site-wide param (camelCase, matches other [params] keys)
[params]
  homeSections = ["workshops", "guides", "reference"]

# content/_index.md — page front matter (snake_case; takes precedence)
+++
title         = "..."
home_sections = ["workshops", "guides", "reference"]
+++

Without either, the home page lists all top-level sections by weight (filtering out anything with hidden: true). Set it to lock the order or hide specific sections from the home without hiding them everywhere. The page-front-matter form wins when both are set — handy if you want a different home selection per language without forking site params.

Misspelled paths get a build warning naming the missing section, so typos surface as WARN lines rather than silent gaps.