Theming & Appearance

Customize the visual style of your HugoBlox site. Configure themes, colors, typography, layout, and icons.

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

Visual Editor Available

The easy way: Use Ownable CMS to configure your site's appearance visually in VS Code - no YAML editing required!

Install Ownable CMS →

Build Your Theme Visually

Preview font packs, colors, and layout options — then copy the config to your site.

What

This guide focuses on visual appearance (colors, fonts, layout).

Site Identity (Name, Logo, SEO) → Site Configuration
Menu Links → Header Configuration
Page Content → Block Builder

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

New to HugoBlox? The defaults work great out of the box. Start with a theme pack and customize as you go.

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

Try them out! Enable the theme picker in your header to let visitors preview all themes:

header:
  theme_picker: true

Mix & Match

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

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

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 using font packs — curated sets of heading, body, and code fonts.

hugoblox:
  typography:
    pack: "modern"  # modern | academic | editorial | geometric | humanist | developer | system

Pack	Fonts	Performance
`modern` (default)	Inter + JetBrains Mono	Best — fully bundled, no network requests
`academic`	Lora + Source Serif 4	Good — Google Fonts CDN
`geometric`	Montserrat + Poppins	Good — Google Fonts CDN
`system`	OS native fonts	Instant — no download

You can also override individual font families, bundle your own fonts locally for privacy/performance, or create entirely custom font packs.

Typography Guide

Font packs, bundled fonts, Google Fonts, custom families, weights, and sizing

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"

Most users don't need this. Theme packs provide great defaults. Only override surfaces if you need exact brand colors that theme packs don't provide.

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/:

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

SVG preferred for logos and icons - they scale perfectly and support dark mode.

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

Build Your Theme Visually

Configuration Overview

Theme Packs

Quick Setup

Built-In Theme Packs

Mix & Match

Custom Colors

Brand Colors

Mode-Specific Colors

Typography

Typography Guide

Layout Tokens

Border Radius

Spacing Density

Avatar Shape

Advanced: Surface Colors

Icons & Assets

Auto-Detected Assets

Custom CSS

Extend & Hooks Guide

Examples by Use Case

Academic Researcher

Research Lab

Tech Startup

🙋 Theming FAQ

Typography Guide

Theme Builder

Ownable CMS

Site Configuration

Block Builder

Extend & Hooks

Was this page helpful?

On this page