Theme Customization

Learn how to customize the Freedom theme’s colors, fonts, spacing, and layout. Override theme.css for site-wide changes, or use hugo.yaml configuration for page-specific customizations.

Overview #

Freedom theme provides three ways to customize its appearance:

1. Override theme.css (Recommended) - For site-wide theme customization.
2. Use hugo.yaml configuration - For kind/section/type specific overrides.
3. Use Page Front Matter - For a single page specific overrides.

Method 1: Override theme.css #

The preferred way to customize the theme is to create your own theme.css file in your site’s assets/css/ directory. This file will automatically override the default theme variables.

Create assets/css/theme.css in your project root:

/* Theme colors */
:root {
  /* Light theme (default) */
  --bg-color: #ffffff;
  --text-color: #222222;
  --accent-color: #007acc;
  --link-color: #0000ee;
  --link-visited: #551a8b;

  /* Font families */
  --body-font: 'Inter', 'Segoe UI', Arial, sans-serif;
  --header-font: 'Montserrat', 'Segoe UI', Arial, sans-serif;
  --code-font: monospace;
  
  /* Dark theme palette */
  --dark-bg-color: #212121;
  --dark-text-color: #F0F0F0;
  --dark-accent-color: #2b89c8;
  --dark-link-color: #6b9eff;
  --dark-link-visited: #b392ff;

  /* Spacing */
  --spacing-xxs: 0.125rem;
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  --spacing-xxl: 2.5rem;

  --page-width: 768px;
}

Common Customizations #

Brand Colors #

:root {
  --accent-color: #e63946;
  --link-color: #457b9d;
  --dark-accent-color: #f1faee;
  --dark-link-color: #a8dadc;
}

Minimal Monochrome #

:root {
  --bg-color: #ffffff;
  --text-color: #000000;
  --accent-color: #000000;
  --link-color: #000000;
  --dark-bg-color: #000000;
  --dark-text-color: #ffffff;
  --dark-accent-color: #ffffff;
  --dark-link-color: #ffffff;
}

Wider Layout #

:root {
  --page-width: 1200px;
}

Method 2: Configuration-Based Overrides #

Use hugo.yaml configuration when you need different themes for specific page kinds, sections, types.

When to Use Configuration-based Overrides:

• Landing pages with unique branding
• Special sections (e.g., documentation vs blog)
• Specific page kinds (e.g., home page vs regular pages)

Site-Wide Configuration #

Add to hugo.yaml (only if you can’t use theme.css):

params:
  theme:
    ## Override only what you need
    accentColor: "#ff6b6b"
    linkColor: "#4dabf7"
    darkAccentColor: "#ff8787"
    darkLinkColor: "#74c0fc"

Section-Level Configuration #

Override theme for all pages in a section:

params:
  section:
    usage:  ## Section name
      theme:
        accentColor: "#00ff00"

Kind-Level Configuration #

Override theme for specific page kinds (home, page, section, taxonomy, term):

params:
  kind:
    home: ## Kind name
      theme:
        accentColor: "#ff00ff"
        pageWidth: "1200px"

Type-Level Configuration #

Override theme for specific page types (the type field in front matter, defaults to section name):

params:
  type:
    blog:  ## Type name
      theme:
        accentColor: "#ff6b6b"
        linkColor: "#e91e63"

Method 3: Page Front Matter #

Override theme for a specific individual page by adding theme directly in its front matter:

---
title: "Special Page"
params:
  theme:
    bgColor: "#ff0000"
    textColor: "#ffffff"
    linkColor: "#00ff00"
    darkBgColor: "#0000ff"
    darkTextColor: "#ffffff"
    darkLinkColor: "#00ffff"
---

This method takes highest priority and overrides all other configuration methods for that specific page only.

When to Use Page-Level Configuration:

• Unique landing pages or special promotional pages
• One-off themed content (e.g., holiday specials)
• Testing new color schemes before applying site-wide
• Pages with specific branding requirements

Configuration Hierarchy #

Configuration resolution follows this priority (highest to lowest):

1. Page front matter: Front matter params in individual pages (Method 3).
2. Type → Section → Kind → Site level: Using hugo.yaml (Method 2).
3. Site Wide Configuration: Using theme.css (Method 1)
4. Defaults: Built-in defaults (check below)

Available Variables #

All CSS custom properties can be overridden via either method:

Light Theme Colors #

Dark Theme Colors #

Typography #

Spacing #

Layout #

Background Images #

Note: Background images are placed in the assets/ folder and referenced by filename. The theme automatically handles resource resolution and URL generation.

Chroma Codeblock Theming #

Choose a style from chroma style gallery. Download theme using below command -

## light theme
hugo gen chromastyles --style=solarized-light > assets/css/chroma/light.css

## dark theme
hugo gen chromastyles --style=solarized-dark > assets/css/chroma/dark.css

That’s it, you have set a chroma syntax highlighting style for both dark and light mode respectively.

Best Practices #

For Site-Wide Themes #

1. Create assets/css/theme.css in your project
2. Copy variables from themes/freedom/assets/css/theme.css
3. Modify only the values you want to change
4. Keep unmodified variables for documentation

For Page-Specific Themes #

1. Use sparingly - only when truly needed
2. Override minimal variables to maintain consistency
3. Document why specific pages need custom themes
4. Test both light and dark modes

Color Accessibility #

Always test your customizations in both light and dark mode using the theme toggle ( / ). Ensure good contrast and readability:

• Use a contrast checker for WCAG compliance
• Minimum ratio: 4.5:1 for normal text
• Minimum ratio: 3:1 for large text (18pt+)

Typography Best Practices #

When overriding fonts:

• Provide fallback fonts in your stack
• Use web-safe fonts or import from CDN
• Test load times with custom fonts
• Wrap font names with spaces in quotes

Troubleshooting #

theme.css Not Working #

Make sure the file is in the correct location:

your-site/
└── assets/
    └── css/
        └── theme.css  ← Must be here

Note: This file will override default theme.css, so make sure you copy entire file into above folder and then tweak your required variables.

Config Values Not Applying #

Ensure values are properly quoted in YAML:

## ✅ Correct
theme:
  bgColor: "#ff6b6b"

## ❌ Incorrect (missing quotes)
theme:
  bgColor: #ff6b6b

Fonts Not Loading #

Wrap font families with spaces in quotes:

## ✅ Correct
bodyFont: "'Open Sans', sans-serif"

## ❌ Incorrect  
bodyFont: "Open Sans, sans-serif"

Or in CSS:

/* ✅ Correct */
--body-font: 'Open Sans', sans-serif;

/* ❌ Incorrect */
--body-font: Open Sans, sans-serif;

Background Not Loading #

Background image must be placed in following locations -

• assets/ for global configuration.
• content/section/post1/assets/ for page level configuration.

In assets/css/theme.css make sure you add image location as -

/* ✅ Correct */
--bg-image: url("assets/bg_image.jpg");

/* ❌ Incorrect */
--bg-image: "assets/bg_image.jpg";

In hugo.yaml you can simply add them as -

/* ✅ Correct */
bgImage: "assets/bg_image.jpg"