Customization

Hudocs organizes its styling using CSS cascade layers (@layer) and semantic design tokens defined through CSS custom properties in _tokens.scss. You can customize the look and feel of your documentation without modifying the theme’s core files.

Overriding Styles #

To customize styles, create an assets/scss/_custom.scss file in your Hugo project:

my-project/
├── assets/
│   └── scss/
│       └── _custom.scss
└── hugo.toml

Because Hudocs imports _custom.scss outside of cascade layers, unlayered rules in your custom file naturally take precedence over theme styles without requiring high-specificity selectors or !important.

SCSS Variables #

Hudocs defines base color variables using Sass !default flags. You can override these variables before the theme rules are evaluated:

// assets/scss/_custom.scss
$primary: #2563eb;
$secondary: #7c3aed;

CSS Design Tokens #

All visual properties in Hudocs are mapped to CSS custom properties defined in :root. You can customize them in your _custom.scss by targeting :root (for light mode or universal values) or :root.dark (for dark mode).

Layout and Dimensions #

These variables control the page layout, spacing, and component dimensions:

Typography #

Brand Colors #

Brand tokens define primary and secondary accent roles and their corresponding container tints:

Surfaces and Backgrounds #

Surfaces define backgrounds for the page, containers, menus, and elevated elements:

Text and Borders #

Feedback and Status #

These tokens style hint alerts, statuses, and validation messages:

Data Type Badges #

Used by the type shortcode to classify programming language types:

Code Blocks and Syntax Highlighting #

These tokens control code block backgrounds, text, and selection colors:

Customization Example #

Below is a complete example of an assets/scss/_custom.scss file that sets a custom font, adjusts the primary color palette, and updates background surfaces:

// 1. Override SCSS variables
$primary: #0284c7;

// 2. Override CSS tokens
:root {
  --font-primary: 'Poppins', sans-serif;
  --header-height: 64px;

  // Custom light surfaces
  --surface: #ffffff;
  --surface-container: #f8fafc;
}

:root.dark {
  // Custom dark surfaces
  --surface: #0f172a;
  --surface-container: #1e293b;
  --primary: #38bdf8;
}