Brand and appearance

This page assumes the site already builds (Quick start). Start in hugo.yml for the name, logo, page width and footer. To select an existing system or site font, use params.ui.fonts; section accent colours also have configuration keys.

Add icons under static/. Use assets/scss/_variables_project.scss for SCSS variables and assets/scss/_styles_project.scss for custom styles or new @font-face declarations only when needed. Do not edit files inside the theme directory: an upgrade replaces them.

Visual presets

OINK 1.2.0 defaults to Paper: warm paper backgrounds, ink text, blue links, Plex Sans, heading hairlines and framed tables. Slate keeps OINK’s existing cool blue-gray identity. Enable reader choice with:

params:
  ui:
    preset: paper
    preset_menu: true
    dark_mode: true

The theme default for preset_menu is false. Choose preset: slate to keep the previous appearance. Preset and mode are saved separately; selecting the site default (identified in its tooltip) restores the site policy. All styles use one stylesheet and local fonts.

Ink and Terminal are available as explicit opt-ins in OINK 1.2.0:

params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    dark_mode: true

Ink uses black/white surfaces, red markers, square panels and underlined prose links. Terminal uses mono controls/headings, teal links, amber accents and compact desktop navigation; its long-form prose stays sans-serif. Both support light/dark mode and reuse existing fonts. The menu shows four compact style buttons in a two-column grid, each with a colored icon and no experiment badge. preset_menu: true offers Paper, Slate and the site default; it does not opt into every experiment. Set preset: ink or preset: terminal to make an experiment the site default, even without a reader menu. See the experiment record for tested scope and remaining design work.

Custom dark brand rules using only [data-bs-theme='dark'] have lower specificity than Paper’s dark palette. Retain Slate, or scope those rules to [data-td-preset='paper'][data-bs-theme='dark']. Font configuration and section theme_color overrides keep their precedence in every preset. Print remains light on white paper.

Site name

The site name appears in the navbar, the browser title and the footer. A multilingual site writes one per language:

title: Product Docs

languages:
  en:
    title: Product Docs
    label: English
    locale: en-US
    weight: 1
  zh:
    title: 产品文档
    label: 简体中文
    locale: zh-CN
    weight: 2

The top-level title is the fallback, and languages.<lang>.title wins.

Logo and wordmark

The theme ships assets/icons/logo.svg and uses it by default. To replace it, put the icon file in the site’s assets/ or static/ and point the configuration at it.

params:
  logo: images/product-mark.svg
  wordmark: logo.svg

• params.logo is the square mark, shared by the navbar, the sidebar and the footer. Under assets/ it goes through Hugo’s resource pipeline (and can be fingerprinted); under static/ it is published as is. Either way the path is relative to the assets/ or static/ root.
• params.wordmark is the horizontal wordmark. Once set, the navbar uses it instead of “icon + site name”, falling back to params.logo when the screen is too narrow. Left unset, “icon + site name” stays.

Crop the source SVG tight to the artwork, or the sizes will not line up. An SVG needs a viewBox, and its colours should inherit currentColor or hold enough contrast in both light and dark.

This site leaves both unset: the navbar pairs the theme’s own assets/icons/logo.svg with the site title, drawn in the display font.

favicon

The favicon has no parameter. The theme scans the site’s static/ directory for conventional filenames and emits the matching <link> on every page for whichever it finds:

A sufficient minimum is favicon.ico plus favicon.svg plus apple-touch-icon.png. A file with a size suffix has to be square (NxN) or it is not recognized.

Generate these with any graphics tool. The theme needs no Node.js, and Hugo simply publishes what is already in static/.

Extra head metadata such as a Web App Manifest is outside the scan; emit it yourself through the layouts/_partials/hooks/head-end.html hook. To change the discovery rules themselves (a different directory, more filenames), override layouts/_partials/favicons.html in the site’s layouts/.

Accent colour and palette

Colour comes in two layers: Bootstrap’s semantic colours (Sass variables, at compile time) and OINK’s brand layer (CSS custom properties, at run time).

Change the semantic colours first; they decide the tone of buttons, links and callouts:

$primary: #315f8f;
$secondary: #b4762e;
$success: #2c7a4b;
$warning: #9a6700;
$danger: #b42318;

This file is loaded before Bootstrap and the OINK defaults, which is where Sass variables are overridden. To reference a variable or map Bootstrap has already defined, use _variables_project_after_bs.scss instead.

The brand layer is a set of CSS custom properties, and light and dark must be overridden in pairs or one mode leaks the original colour:

:root {
  --td-brand-copper: #a66722;
  --td-brand-mark-from: #1d588c;
  --td-brand-mark-to: #a66722;
}

[data-bs-theme='dark'] {
  --td-brand-copper: #e0a35c;
  --td-brand-mark-from: #7fb8e8;
  --td-brand-mark-to: #e0a35c;
}

The brand properties available are --td-brand-elev (overlay ground), --td-brand-silk (secondary text), --td-brand-copper and --td-brand-copper-dim (the accent and its muted form), --td-brand-line-strong (rules), --td-brand-header-bg (navbar background), --td-brand-shadow-sm / --td-brand-shadow-md (shadows), and --td-brand-mark-from / --td-brand-mark-to / --td-brand-mark-gradient (the brand gradient).

Section theme colour

The brand palette above sets the colour of the whole site. theme_color is the smaller instrument beside it: one hex that tints the accent grounds of the shell, so a reader can tell which part of the site they are standing in without being told.

params:
  ui:
    theme_color: '#6d28d9'
    theme_color_dark: '#a78bfa' # optional

It is more useful per section than site-wide. Written into a section root’s cascade, it gives that whole section an identity — a navy Docs beside a violet Blog and an orange Book — while the site default stays the brand colour:

cascade:
  theme_color: '#6d28d9'
  theme_color_dark: '#a78bfa'

Hugo resolves these cascade values on the section page as well as its descendants, so the pair is declared once. The same resolved pair drives the page’s accent and that section’s mark in the root switcher.

What it touches: the selected sidebar row and the greyed ground its neighbours take under the pointer, hover washes, the outline pill and its travelling rail and dot, a Book chapter’s headings under the pointer, tag and chip hovers, a content card’s hovered edge, a share button’s hover fill, text selection, focus rings, and each root’s mark in the sidebar switcher.

What it deliberately does not touch: prose links, external URLs, and inline code. Those are reading conventions, not brand surfaces — a page dense in identifiers should read as code and prose in every section, and a link should look like a link wherever it is. This is why the accent is its own custom property rather than a repaint of Bootstrap’s link colour.

The dark half is optional. Left out, it is derived by lightening the light colour toward white until it clears AA body text on the dark canvas, so a single-colour author cannot produce an unreadable dark palette. Name it yourself when the derived value no longer matches the brand hue you want. The light colour is the key: theme_color_dark on its own, or beside an invalid theme_color, colours nothing in either mode — the theme warns and keeps the default palette rather than tint dark mode alone.

A page inside a coloured section can decline the colour with the theme’s bare-boolean idiom: theme_color: false in front matter opts that page out — inherited dark half included — and reverts to the default palette without a warning. Any other non-hex value (a number, true, a named colour) warns.

Hugo merges params by key, so a page overriding theme_color inside a section whose cascade also sets theme_color_dark inherits that dark value. Override both, or neither.

Light and dark mode

The theme does not show a light/dark control by default. To enable it:

params:
  ui:
    dark_mode: true

The sun/moon icon shows the current state: sun for light, moon for dark. Click Appearance in the navbar or footer to open the Light / Dark / System radio group. It supports touch and keyboard; on phones it opens a bottom sheet. The preference is saved locally and synchronized across tabs. No saved choice means follow prefers-color-scheme. The inline head script applies the resolved mode before the stylesheet loads.

For the dark palette without the control, write dark_mode: { show_menu: false, enable: true }; dark_mode: false (the default) enables neither.

Custom components need readable hover, focus, disabled and selected states in both modes, with at least 4.5:1 contrast for body text and 3:1 for large text.

Fonts

The typography policy is selected at build time; visual preset switching chooses its bundled faces:

params:
  ui:
    typography: technical # technical | system

• technical (the default): Paper uses IBM Plex Sans for interface, body and display text; Slate uses Inter for interface/body and Chakra Petch for display. Both use Chakra Petch for the wordmark and IBM Plex Mono for code. Chinese and emoji use platform fallbacks. Plex Sans and Inter include local Latin, Cyrillic, Greek and Vietnamese subsets. No Google Fonts request is made.
• Experimental fonts: Ink uses Inter for UI, prose and headings; Terminal uses IBM Plex Mono for controls/headings and Plex Sans for prose. Both reuse existing code fonts. Explicit fonts.ui still supplies the main face; use fonts.body for a separate prose face.
• system: the interface, display, metadata, print and monospace roles all fall back to the platform stack, and the browser requests no brand font. The font files still ship with the theme; they are simply not referenced.

An invalid value warns and falls back to technical, so an ordinary hugo server stays usable; publishing gates run --panicOnWarning, which is where that warning becomes a hard failure. The chosen value is written to <html data-td-typography="…"> and can be confirmed in the browser.

Custom fonts

The font roles are eight CSS custom properties. Override them rather than hunting for component selectors:

ui is the main face: body resolves through it and heading through body, so a single line moves the interface, the prose and the headings together.

From configuration

To swap font families and nothing else, skip SCSS and write params.ui.fonts:

params:
  ui:
    fonts:
      # The main face: interface, body and headings follow it
      ui: "'Source Han Sans SC', 'PingFang SC', sans-serif"
      # Monospace needs a CJK fallback, or mixed code blocks stop aligning
      code: "'Sarasa Mono SC', 'Noto Sans Mono CJK SC', monospace"

These are family names, not font files. The theme never downloads or loads a font because of this key: a family here must be one the reader already has, or one the site declared in an @font-face of its own. End every list with a generic family (sans-serif, monospace, serif) — that is where a reader without your face lands.

Values are gated to plain font family syntax: quoted names, bare identifiers, a leading hyphen (-apple-system), and names spelled in any script (苹方 is a family name). Semicolons, braces, parentheses, url() and angle brackets do not pass. An unknown role or an unsafe value warns and is dropped on its own; the rest of the map still ships. A site that sets nothing gets no style element in <head> at all.

The block renders after the stylesheet, which is what lets an authored face outrank the typography preset at equal specificity.

From a stylesheet

To ship a font file of your own, or to change the face for one kind of content only, use a stylesheet. Put the .woff2 in the site’s static/webfonts/, declare the face in the project stylesheet, then rewrite the roles:

@font-face {
  font-family: 'My Sans';
  font-display: swap;
  font-style: normal;
  font-weight: 400 800;
  src: url('../webfonts/my-sans-variable.woff2') format('woff2');
}

:root {
  --td-ui-font-family: 'My Sans', 'Noto Sans SC', sans-serif;
  --td-body-font-family: var(--td-ui-font-family);
  --td-heading-font-family: var(--td-ui-font-family);
  --td-display-font-family: var(--td-heading-font-family);
}

Roles inherit by ordinary CSS rules, so changing the font for one kind of content needs no component selectors either:

body.td-blog {
  --td-body-font-family: 'My Serif', 'Noto Serif SC', serif;
  --td-heading-font-family: var(--td-body-font-family);
}

A monospace stack needs a CJK fallback, or mixed code blocks fail to align:

:root {
  --td-code-font-family: 'My Mono', 'Sarasa Mono SC', 'Noto Sans Mono CJK SC', monospace;
}

A site migrating from Docsy need not change how it writes this. The old Sass variables still feed the corresponding roles, still work from _variables_project.scss, and take precedence over the preset defaults:

Docsy’s three Google Fonts variables — $td-enable-google-fonts, $td-google-font-name and $td-web-font-path — are no longer read by the theme. Leaving them in _variables_project.scss breaks nothing and does nothing: what ships with the theme is IBM Plex Sans, Inter, Chakra Petch and IBM Plex Mono, and no preset requests anything from Google Fonts. The print role --td-print-font-family follows the body role, and the theme ships no separate font for paper.

YAML accepts font family names only — neither a remote font URL nor arbitrary CSS. Font files and styles must both be auditable local inputs, and an ordinary build makes no network request for a font.

Page width

params:
  page_width: normal # normal | wide | full

page_width controls the overall shell width and can be overridden per page or per section by cascade. Book pages additionally have reading_width (slim / normal / wide), which changes the reading measure of the body rather than the shell. An invalid value in either key warns and falls back during ordinary preview; the warning fails a publishing build with --panicOnWarning.

Footer

params:
  ui:
    footer_style: fat # fat | slim | none
  copyright:
    authors: '[The product team](https://example.com/)'
    from_year: 2026
    to_year: present
  footer_center_info: 'Powered by [Oink](https://oink.pgsty.com)'

• fat (the default): a multi-column link grid plus the copyright line;
• slim: the copyright line only;
• none: no footer at all.

Page front matter (including a section cascade) can override it; this site’s documentation section uses footer_style: slim. An unrecognized value warns and falls back to fat in ordinary preview; strict publishing rejects the warning.

The grid’s data lives in data/footer/<language>.yaml — see Navigation and menus. With fat configured but no data, it degrades to slim automatically, so it can be enabled before the content exists.

params.copyright accepts a Markdown string, or a map of authors / from_year / to_year (present means this year). footer_center_info is inline Markdown in the centre of the footer, and setting it explicitly to an empty string hides that region.

SCSS entry points, and what not to do

A site’s SCSS overrides join the theme’s single style bundle, and a production build still emits one fingerprinted stylesheet with an integrity attribute. Three entry files go under the site’s assets/scss/:

The compilation order is: Bootstrap functions → project variables → OINK defaults and Bootstrap → post-Bootstrap project variables → OINK components and the brand layer → project styles.

The CSS interface has a defined boundary. The eight font roles in Fonts and the --td-brand-* properties are public, and the theme keeps their names and meanings across minor versions. Component aliases such as --td-asciinema-font-family promise only to work within that component, and undocumented variables such as the --td-shell-* family are implementation detail that may be renamed or removed at any time.

What not to do:

• Do not edit any file inside the theme directory (hugo mod overwrites it);
• Do not @import the theme’s internal partials individually — they are not a public Sass interface and their import order may change;
• Do not override baseof.html to change one colour. Use a design variable where one exists, and otherwise write the narrowest selector that works;
• Do not reference a remote stylesheet or a font CDN.

For additional third-party CSS, publish a local resource through the layouts/_partials/hooks/head-end.html hook rather than writing a <link> in Markdown.

Verify

hugo --printPathWarnings --panicOnWarning

• The build prints Total in … with no ERROR and no WARN;
• The page source has data-td-typography="technical" (or your chosen preset) on <html>;
• In the browser the navbar shows your logo and site name, and the tab shows your favicon;
• Switch to dark mode and look again at body text, tables, callouts, code blocks and focus rings. A colour change is easy to verify in only one mode;
• Switch language and confirm the site name changes with it.

To verify the font change, inspect a paragraph’s font-family in the browser’s developer tools. It should include your declared family. Check the rendered font as well to confirm that the local file or system fallback is being used.

Related

• Configuration — types and defaults of the brand parameters
• Navigation and menus — navbar menu, page actions and footer data
• Layouts and page types — shell, sidebar and table of contents
• Images — images in the body, light/dark pairs and captions
• Home and landing pages — hero, sections and landing data