Theming & Appearance

HugoBlox gives you complete control over your site’s visual identity. Customize themes, colors, typography, and layout - all without touching CSS.

Configuration Overview

All appearance settings live in config/_default/params.yaml:

hugoblox:
  schema: "2.0"

  theme:         # Colors and design
  typography:    # Fonts and sizing
  layout:        # Spacing and shapes

Theme Packs

Theme packs provide coordinated color schemes for both light and dark modes.

Quick Setup

hugoblox:
  theme:
    mode: system    # light | dark | system (follows OS)
    pack: "default"

Built-In Theme Packs

Pack	Light Mode	Dark Mode
`default`	Modern indigo/emerald	Deep blue/teal
`minimal`	GitHub-inspired clean gray	GitHub dark
`solar`	Easy-reading yellowish	Deep teal (Solarized)
`contrast`	High contrast, accessible	Inverted high contrast

Pack	Light Mode	Dark Mode
`coffee`	Warm latte cream	Deep Americano
`matcha`	Creamy pale greens	Deep ceremonial green
`marine`	Light ocean blues	Deep sea tones
`retro`	Vintage warm paper	Midnight arcade

Pack	Light Mode	Dark Mode
`dracula`	Soft pastels	Classic Dracula purple/pink
`synthwave`	Light cyberpunk	Neon cyberpunk
`cupcake`	Playful pastels	Deep candy tones

Mix & Match Advanced

Use different packs for light and dark modes:

hugoblox:
  theme:
    pack:
      light: "minimal"   # Clean GitHub style for day
      dark: "dracula"    # Bold colors for night

Custom Colors

Override theme pack colors without creating a custom theme.

Brand Colors

hugoblox:
  theme:
    pack: "default"
    colors:
      primary: "indigo"      # Main brand color
      secondary: "emerald"   # Accent color
      neutral: "slate"       # Gray scale choice

Tailwind Palettes
Custom Hex

Use any Tailwind color name:

Vibrant: red · orange · amber · yellow · lime · green · emerald · teal · cyan

Cool: sky · blue · indigo · violet · purple · fuchsia · pink · rose

Neutral: slate · gray · zinc · neutral · stone

HugoBlox automatically generates all shades (50-950).

Use exact brand colors:

colors:
  primary: "#6366f1"    # Your brand purple
  secondary: "#10b981"  # Your brand green

HugoBlox generates the complete shade scale automatically.

Mode-Specific Colors Advanced

Different colors for light vs dark mode:

hugoblox:
  theme:
    colors:
      primary: "blue"      # Default for both modes
    colors_light:
      secondary: "emerald" # Light mode accent
    colors_dark:
      secondary: "teal"    # Dark mode accent

Typography

Control fonts and text sizing across your site.

hugoblox:
  typography:
    font: "sans"  # sans | serif | native
    size: "md"    # sm | md | lg | xl

Font Families

Value	Font	Style	Performance
`sans`	Inter	Modern, clean	Good (web font)
`serif`	Roboto Slab	Traditional, academic	Good (web font)
`native`	System fonts	OS-native	Best (no download)

Choosing a font:

Academic/Traditional: Use serif for a scholarly feel
Modern/Tech: Use sans for clean readability
Performance-Critical: Use native for instant loading

Text Size Scale

Value	Base Size	Use Case
`sm`	14px	Dense content, dashboards
`md`	16px	Recommended for general sites
`lg`	18px	Readability focus, blogs
`xl`	20px	Large screens, accessibility

Layout Tokens

Fine-tune spacing and visual style.

hugoblox:
  layout:
    radius: "md"           # Border radius
    spacing: "comfortable" # Content density
    avatar_shape: circle   # circle | square | rounded

Border Radius

Value	Effect	Best For
`none`	Sharp corners (0)	Minimal, editorial sites
`sm`	Subtle (4px)	Professional, corporate
`md`	Balanced (8px)	Recommended
`lg`	Soft (12px)	Friendly, approachable
`full`	Pill shapes	Playful, modern apps

Spacing Density

Value	Effect	Best For
`compact`	Tight spacing	Dense information, dashboards
`comfortable`	Balanced	Recommended for most sites
`spacious`	Generous whitespace	Premium feel, portfolios

Avatar Shape

Controls the shape of profile photos in author cards:

Value	Effect
`circle`	Round (default, traditional)
`square`	Sharp corners
`rounded`	Soft rounded corners

Advanced: Surface Colors

Override specific backgrounds and text colors (advanced users only).

hugoblox:
  theme:
    pack: default
    surfaces:
      background: "#ffffff"
      foreground: "#000000"
      header:
        background: "#f1f5f9"
        foreground: "#0f172a"
      footer:
        background: "#f3f4f6"
        foreground: "#0f172a"

Surface structure:

background - Main page background
foreground - Main text color
header.background - Navigation bar background
header.foreground - Navigation text color
footer.background - Footer background
footer.foreground - Footer text color

Icons & Assets

Auto-Detected Assets

HugoBlox automatically detects these files in assets/media/:

Directoryassets/
- Directorymedia/
  - logo.svg ← Site logo (navbar)
  - icon.svg ← Favicon
  - social.png ← Social share image (Open Graph)

No configuration needed! Just place the files and HugoBlox finds them.

Detection order:

Logo: logo.svg → logo.png → logo.jpg
Icon: icon.svg → icon.png
Social: social.png → social.jpg

Custom CSS

Need more control? Add custom styles without modifying theme files.

Create custom CSS file
```
assets/css/custom.css
```

Add your styles

/* Override CSS variables */
:root {
  --custom-var: value;
}

/* Custom classes */
.my-element {
  color: var(--color-primary-500);
}

File is automatically loaded

HugoBlox includes custom.css if it exists.

Extend & Hooks Guide Advanced customization: hooks, component overrides, and Tailwind.

Examples by Use Case

Academic Researcher

hugoblox:
  theme:
    pack: minimal      # Clean, professional

  typography:
    font: serif        # Academic feel
    size: md

  layout:
    spacing: comfortable

Research Lab

hugoblox:
  theme:
    pack: default
    colors:
      primary: "#8C1515"  # University brand color

  header:
    cta:
      enable: true
      text: "Join Us"
      url: "/careers/"

Tech Startup

hugoblox:
  theme:
    mode: dark
    pack: synthwave     # Bold, modern

  typography:
    font: sans
    size: lg

  layout:
    radius: lg
    spacing: spacious

🙋 Theming FAQ

Can I use any Google Font?

Yes. While we provide optimized defaults (Inter, Roboto Slab), you can use any Google Font. Add the font import to assets/css/custom.css and reference it in your CSS.

Why isn't my favicon updating?

Browser caching. Browsers cache favicons aggressively. Open your site in an Incognito/Private window or hard refresh (Cmd+Shift+R / Ctrl+F5). Also ensure the file is in assets/media/, not static/.

Can I create a completely custom theme?

Yes. Define exact hex codes for colors and surfaces in params.yaml. HugoBlox generates all shades and CSS variables automatically.

How do I remove 'Powered by HugoBlox'?

This is a Pro feature. HugoBlox Pro subscribers can optionally hide the attribution. Open source users keep the link to support the project (many Pro users do too!).

Do I need to know CSS?

No. The params.yaml configuration handles 90% of customization. You only need CSS for highly specific visual overrides.

Do themes work on mobile?

Yes, automatically. All HugoBlox themes are fully responsive. Typography, spacing, and navigation adapt automatically to phone and tablet screens.

Can I preview themes before choosing?

Yes! Enable header.theme_picker: true to show a dropdown that lets you (and visitors) preview all theme packs instantly.

What's the difference between 'colors' and 'surfaces'?

Colors are your brand (primary/secondary). Surfaces are where they appear (backgrounds and text). Most users only need to configure colors - theme packs handle surfaces automatically.

HugoBlox Studio Visual theme editor for VS Code - no YAML needed

Site Configuration Menus, footers, features, and integrations

Block Builder Build custom page layouts visually

Extend & Hooks Custom CSS, JS, and component overrides