Theme Configuration

This post covers all configuration options available in the Mono theme. For a getting started guide, see Getting Started with Mono.

Theme Configuration

Theme-wide settings are specified in hugo.toml. This file controls the overall behavior and appearance of Mono.

Site Parameters

The [params] section defines site metadata, features, and appearance:

[params]
  author = "Your Name"
  description = "Site description for SEO"

  # Features
  showToC = true                  # Site-wide Table of Contents (override per-page)
  show_updated = true             # Show visible "Updated" line when lastmod differs from date
  dateFormat = "Jan 2, 2006"      # Go reference layout applied to post dates

  # Home page
  homePostCount = 3               # Number of recent posts on the home page
  homeProjectCount = 3            # Number of projects on the home page

  # SEO
  favicon = "images/favicon.svg"
  og_image = "images/og.png"      # Default Open Graph image (override per-page)

  # Math (KaTeX only). Leave off to opt in per-page via `math: true` front matter.
  katex = false

  # Search
  enableSearch = true             # Show header search icon and build /search/

  # Custom assets
  customCSS = ["css/custom.css"]
  customJS = ["js/custom.js"]

Language

Mono includes translations for UI elements in five languages. Set the default language at the top level of hugo.toml:

defaultContentLanguage = "en"  # en, es, fr, de, zh

Translation files are located in the theme’s i18n/ folder. To add a new language or customize translations, create an i18n/ folder in our site root and add a file like i18n/pt.toml for Portuguese. Hugo merges site-level translations with theme defaults.

Table of Contents

The Table of Contents appears on the right side of posts on desktop, or as a collapsible section on mobile.

Global default in hugo.toml:

[params]
  showToC = true

Depth configuration in hugo.toml controls which heading levels appear:

[markup.tableOfContents]
  startLevel = 2  # The page title is the h1, so content starts at h2
  endLevel = 3    # Include h2 and h3 (stop at h4+)
  ordered = false # Use bullets (true = numbered list)

Per-page override in front matter in a specific post:

---
showToC: false  # Disable for this specific page
---

Date Display

The dateFormat parameter uses Go’s reference time format. The reference date is Mon Jan 2 15:04:05 MST 2006 — we arrange these components however we want:

Setting show_updated = true displays a “last modified” date when posts have a lastmod field in their front matter.

Math Rendering

Mono ships with KaTeX for math rendering. Use $...$ for inline math and $$...$$ for display math.

There are two ways to enable it:

Per-page (recommended) — add math: true to the front matter of any post that uses math. KaTeX then only loads on pages that need it:

---
math: true
---

Site-wide — set katex = true in [params]. Every page loads the KaTeX runtime, even pages without math. Only use this if you have math in most of your posts.

To customize KaTeX configuration, edit layouts/partials/head.html.

Search

Search provides instant client-side filtering across all posts using Fuse.js. It requires a JSON index:

[params]
  enableSearch = true

[outputs]
home = ["HTML", "RSS", "JSON"]

The JSON output generates a search index at public/index.json (accessible at /index.json, e.g., http://localhost:1313/index.json during development).

Social Links

Social links display in the footer with icons. Each entry needs a name (for accessibility), URL, and icon identifier:

[[params.social]]
  name = "GitHub"
  url = "https://github.com/username"
  icon = "github"
[[params.social]]
  name = "Twitter"
  url = "https://twitter.com/username"
  icon = "twitter"

Supported icons: github, twitter, bluesky, linkedin, google-scholar, instagram, threads, mastodon.

To display social links inline within content:

{{< social-links >}}

Syntax Highlighting

Hugo uses Chroma for syntax highlighting. One setting is essential for dark/light mode switching:

[markup.highlight]
  noClasses = false

Setting noClasses = false outputs CSS classes instead of inline styles, allowing the theme to control syntax colors and switch them automatically with dark/light mode.

Code block features (see Code Blocks for examples):

Markup Configuration

The [markup] section controls how Hugo processes Markdown:

[markup]
  [markup.tableOfContents]
    startLevel = 1
    endLevel = 2
    ordered = false

  [markup.highlight]
    noClasses = false  # Required for theme color switching

  [markup.goldmark.renderer]
    unsafe = true      # Allow raw HTML in Markdown

  [markup.goldmark.parser.attribute]
    block = true       # Enable {#custom-id} syntax on headings

Why unsafe = true? Hugo strips HTML from Markdown by default. We enable it to allow <figure>, <video>, and other HTML elements in posts.

Why block = true? This enables custom heading IDs:

## My Section {#custom-anchor}

Then link to it with [link text](#custom-anchor).

RSS Feed

RSS lets readers subscribe to updates. Enable it in [outputs]:

[outputs]
home = ["HTML", "RSS", "JSON"]

The feed is generated at public/index.xml (accessible at /index.xml, e.g., http://localhost:1313/index.xml during development).

Front Matter Reference

Front matter is the YAML block at the top of each content file that configures individual pages:

---
title: "Post Title"
date: 2025-03-10
lastmod: 2025-03-12             # Shows "Updated" date if show_updated=true
description: "SEO description"
summary: "Short summary for list pages"
tags: ["tag1", "tag2"]
showToC: true                   # Override global ToC setting
math: true                      # Load KaTeX on this page only
author: "Guest Author"          # Override site-level author for this post
og_image: "images/post-og.png"  # Override site-level og_image for this post
banner:
  src: "banner.jpg"             # Relative to post bundle or static/
  alt: "Image description"
  caption: "Optional caption"
---