Themes

If you just want to change a few colors or swap a font, Colors & Fonts covers that. A theme is the next step: a coherent visual identity that goes beyond individual tweaks.

What a theme is (and isn’t)

In Xanthan, a “theme” is simply a single CSS file that overrides the defaults. There’s no theme marketplace, no plugin system, no configuration wizard. You create a .css file, put your style overrides in it, and link it in your site’s header. That’s it.

This is deliberately different from platforms like WordPress or Squarespace, where “theme” means a complex package of templates, scripts, and settings that you install and configure. In Xanthan, the structure of your site—layouts, includes, navigation—stays the same. A theme only changes how things look: colors, fonts, spacing, borders, shadows. You’re writing CSS, not installing software.

This keeps things transparent and portable:

How Themes Work

CSS files load in order, and later files override earlier ones:

  1. base.css (defaults)
  2. typography.css, nav.css, cards.css (component styles)
  3. Your theme file (overrides everything above)

Your theme file only needs to include what you’re changing—everything else is inherited from the defaults.

Option A: Simple Theme (Colors & Fonts Only)

Best for: A different palette without changing layout or structure.

Xanthan includes simple-theme.css as a starting point. It shows how to define a color palette and map it to semantic variables.

To create your theme:

  1. Copy assets/css/themes/simple-theme.css to assets/css/themes/my-theme.css
  2. Edit the color values in the :root section
  3. Activate it in _config.yml by adding or setting theme_css to the file name without .css: 
    theme_css: my-theme

Example from simple-theme.css:

:root {
  /* Your color palette */
  --ocean-blue: #2c5f7c;
  --cloud-white: #f7f9fb;
  --pearl: #e8eef2;

  /* Map to semantic variables */
  --bg-page: var(--cloud-white);
  --accent-primary: var(--ocean-blue);
  --text-body: var(--charcoal);
}

The file includes detailed comments explaining each variable.

Option B: Reference-Based Theme (Image to Palette)

Best for: Turning a place, object, archive, artwork, or photograph into a coherent visual system.

canyon-wall.css shows this approach. It was built from a Grand Canyon wall palette: red stone, dark vegetation, pale granite, trail dust, and shadow gray. The file keeps those colors named, then maps them to Xanthan’s semantic variables.

The important design choice is that the visual reference does not take over the site. Canyon red becomes a stratum line—headings, borders, and emphasis. Dark green and shadow gray do the structural work of links, navigation, and body text.

To use canyon-wall.css:

  1. In _config.yml, add or set: 
    theme_css: canyon-wall
  2. Save and refresh

Example from canyon-wall.css:

:root {
  /* Named palette */
  --canyon-red: #9f4a35;
  --ponderosa-green: #2f4938;
  --granite-white: #f3efe5;

  /* Semantic roles */
  --bg-page: var(--granite-white);
  --accent-primary: var(--ponderosa-green);
  --accent-border: var(--canyon-red);
}

This is the recommended pattern for most custom themes: name your colors first, then decide what job each one performs.

Option C: Advanced Theme (Full Customization)

Best for: Changing visual styles beyond colors—typography, navigation, component styling.

Study dark-energy.css to see what’s possible. It demonstrates:

To use dark-energy.css:

  1. In _config.yml, add or set: 
    theme_css: dark-energy
  2. Save and refresh

To create your own advanced theme:

Copy assets/css/themes/dark-energy.css as a starting point and modify the element overrides to match your design vision.

Included Themes

Canyon Wall (canyon-wall.css) - A stronger variable-only theme drawn from Grand Canyon colors. Good for showing how visual references become semantic color systems.

Terra Cotta (terra-cotta.css) - A warm, earthy simple theme. Good for showing how small variable changes can preserve Xanthan’s default structure while shifting mood.

Simple Theme (simple-theme.css) - A teaching scaffold for creating your own variable-only theme from scratch.

Dark Energy (dark-energy.css) - An advanced theme that changes variables and adds custom element styling.

Activate any theme by setting theme_css in _config.yml to the theme file name without .css.

Best Practices

Switching Themes

To switch between themes, edit _config.yml and add or change theme_css:

The loading code lives in _includes/html/html-head.html, but most users do not need to edit that file.

Troubleshooting

Theme not showing:

Some elements unchanged:

Next Steps