Configuration

Everything below goes in your site’s hugo.toml (or the YAML/JSON equivalent). The complete working example is this site’s own hugo.toml.

Required build settings#

[outputs]
  home = ["html", "rss", "searchindex"]

[markup.highlight]
  noClasses = false

• outputs.home — Hugo does not merge outputs from a theme. searchindex emits /index.json, the data source for the search modal; rss enables the RSS feed linked in <head>. Omit searchindex and the search trigger quietly does nothing.
• markup.highlight.noClasses = false — makes Chroma emit CSS classes so the theme’s light/dark-scoped code stylesheets apply. With the default true, every code block is frozen to inline Monokai colors.

Site params#

Example:

[params]
  description = "Docs for my project"

  [params.docs]
    editPage = true
    lastMod = true
    repoURL = "https://github.com/you/my-docs"
    repoBranch = "main"
    repoContentDir = "content"

  [params.brand]
    icon = "book"

  [params.footer]
    copyright = "© 2026 my project · [MIT](https://github.com/you/my-docs/blob/main/LICENSE)"

  [params.social]
    github = "you/my-docs"

Palette & CSS variables#

Pico v2 is styled entirely through --pico-* custom properties, so any of them can be overridden from hugo.toml — the theme emits them into a <style> block scoped to Pico’s own light/dark selectors (it wins by source order, no !important needed):

[params.style]
  primary = "#e01e5a"      # light theme: derives the --pico-primary-* family
  primaryDark = "#ff5c93"  # optional; dark theme falls back to `primary`

[params.cssvars]            # any --pico-* / --hd-* variable, both themes
  pico-border-radius = "0.4rem"
  pico-font-family = "Inter, system-ui, sans-serif"

  [params.cssvars.dark]     # dark-theme-only overrides (also .light)
    pico-code-background-color = "#0d1117"

primary is a shortcut: one color derives --pico-primary, -background, -border, -underline, -hover, -hover-background, -hover-border, -hover-underline and -focus (hover darker in light, lighter in dark). For exact control, set any family member directly in params.cssvars / params.cssvars.light / params.cssvars.dark — later declarations win. The full variable list lives in the Pico CSS variables docs.

Theme-level --hd-* variables work the same way — e.g. the hint accents --hd-hint-info, --hd-hint-note, --hd-hint-warning, --hd-hint-danger, --hd-hint-success, --hd-hint-tip are deliberately independent from the primary color.

Commonly overridden variables#

Pico’s defaults, for reference — the primary family is what params.style.primary/primaryDark derives:

Same in both themes:

Top navigation#

The header renders the primary menu plus the built-in search trigger and theme toggle:

[menu]
  [[menu.primary]]
    name = "Docs"
    pageRef = "/docs"
    weight = 10
  [[menu.primary]]
    name = "GitHub"
    url = "https://github.com/you/my-docs"
    weight = 20

Page front matter#

i18n#

The theme’s UI strings live in i18n/en.toml (nav labels, search placeholder, “On this page”…). Add languages the standard Hugo way and override any string by redefining the same key in your own i18n/ files.