Customization

Override Templates

Hugo provides a robust mechanism for template overriding. If the default layout or functionality of a specific theme component does not meet your requirements, you can override it by recreating the file at the equivalent path within your project's root directory.

This approach ensures that your customizations remain intact while allowing the underlying theme to be updated independently.

Usage Example

Customize Footer
You can modify the theme's default footer without altering the original theme files, follow these steps:
1. Locate the target partial in the theme directory: themes/hugo-yore/layouts/_partials/footer.html
2. Create a corresponding file in your project root: layouts/_partials/footer.html
3. Implement your custom HTML within this new file.

Customize Syntax Highlighting Style

These commands generate CSS to chroma.css, overriding the theme's built-in chroma.css.

# Mac/Linux
(echo 'html[data-theme=light] {'; hugo gen chromastyles --style=emacs; echo '}') > assets/css/chroma.css
(echo 'html[data-theme=dark] {'; hugo gen chromastyles --style=evergarden; echo '}') >> assets/css/chroma.css

# Windows PowerShell
# This command cannot run in CMD; it must run in PowerShell
@("html[data-theme=light] {"; (hugo gen chromastyles --style=emacs); "}") | Add-Content -Path "assets/css/chroma.css"
@("html[data-theme=dark] {"; (hugo gen chromastyles --style=evergarden); "}") | Add-Content -Path "assets/css/chroma.css"

See all available styles in the Hugo's documentation.

Extend Templates

Yore provides reserved partial hooks within the _partials directory, allowing for content injection at specific locations. This method is preferred over full template overrides when appending or prepending code.

Available Extension Points

Files in layouts/_partials:

extend-head.html: Injected in the <head>, after main CSS and before all deferred JavaScript.
extend-body-end.html: Injected immediately before the closing </body> tag.
comment.html: Injected in the article pages.
page/content-before.html: Injected before {{ .Content }} in the page template.
page/content-after.html: Injected after {{ .Content }} in the page template.

Files in assets:

css/custom.css: Loaded at the end of all CSS files and bundled into the full CSS.

Usage Examples

Site Verification and Search Console

To add site verification tags for Google Search Console or other services, edit layouts/_partials/extend-head.html:

layouts/_partials/extend-head.html
<meta name="google-site-verification" content="YOUR_VERIFICATION_CODE" />

<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

Injecting Conditional Assets

To load specific stylesheets for pages under the /events path, edit layouts/_partials/extend-head.html:

layouts/_partials/extend-head.html
{{ if hasPrefix .Page.Path "/events" }}
  {{ with resources.Get "css/events.css" }}
    {{ $eventsCSS := . | minify | fingerprint }}
    <link rel="stylesheet" href="{{ $eventsCSS.RelPermalink }}" integrity="{{ $eventsCSS.Data.Integrity }}">
  {{ end }}
{{ end }}

Stale Content Warning
Use layouts/_partials/page/content-before.html to display a notification if an article has not been updated for over a year:
layouts/_partials/page/content-before.html
```
<div id="stale-warning"></div>
<script src=...>
```

Customize CSS

Important

CSS customization is intended for advanced users.

Yore provides an assets/css/custom.css entry to include your own stylesheets. This file is loaded at the end of all CSS files and bundled into the full CSS.

Understanding Yore's 3-layered CSS architecture facilitates more effective customization.

Concept

Tailwind and the typography plugin are responsible for the major layout framework, and the color/padding/margin of components are also set by Tailwind utilities. All other CSS settings are loaded by Hugo pipes as plain CSS instead of being compiled into the Tailwind bundle.

This is Yore's CSS file architecture:

assets/css
├── schemes
│   ├── avocado.css
│   ├── blowfish.css
│   └── ...
├── tailwind
│   ├── components
│   │   ├── admonition.css
│   │   └── code.css
│   ├── compiled.css
│   ├── main.css
│   ├── theme.css
│   └── typography.css
├── layout-2col.css
├── layout-3col.css
├── main.css
└── ...

And this shows how they are loaded:

	---
config:
  layout: elk
---
graph TB
    BASE["schemes/FILE_NAME.css<br>Layer 1: Define raw color values"]
    SEM["tokens.css<br>Layer 2: Semantic naming"]
    COMP["xxx.css<br>other CSS components"]
    CUSTOM["custom.css<br>"]

    IMPORT["import to main.css"]

    TW_TOKEN["tailwind/theme.css<br>Layer 3: Tailwind classes<br>Define Tailwind suffixes"]
    TW_PROSE["tailwind/typography.css<br>Configure prose styles"]
    TW_MAIN["tailwind/main.css<br>Main Tailwind entry file"]
    TW_COMPILED["tailwind/compiled.css<br>Compiled plain CSS"]

    FINAL["📦 main-bundle.css"]

    BASE ==> | #64;import | IMPORT
    SEM ==> | #64;import | IMPORT
    TW_COMPILED ==> | #64;import | IMPORT  
    COMP ==> | #64;import | IMPORT
    CUSTOM ==> | #64;import | IMPORT
    IMPORT --> | Hugo css.Build | FINAL

    TW_MAIN --> |compile to plain CSS outside Hugo| TW_COMPILED
    TW_TOKEN --> TW_MAIN
    TW_PROSE --> TW_MAIN

Tailwind is compiled into compiled.css when the theme is released, so users receive plain CSS. You do not need to install or run any Tailwind tooling to use the theme.

All files outside the tailwind folder are loaded as plain CSS, allowing you to override specific components without changing the Yore preset.

Variable Architecture

Yore uses a simple three-layer variable system to make theming predictable and easy to override:

Base Colors: Raw color values defined in schemes/.
Semantic Tokens: Purpose-based names defined in tokens.css.
Tailwind Tokens: Tailwind utilities mapped to semantic tokens in theme.css.

Because Tailwind utilities reference CSS variables, you can customize the entire theme by overriding variables, no rebuild required.

Base Colors

Schemes use an 11-step scale across three main color types:

:root {
  /* Neutral colors for backgrounds and text */
  --color-neutral-50: oklch(98.5% 0.003 60);
  /* ... steps 100 to 900 ... */
  --color-neutral-950: oklch(12% 0.004 35);

  /* Brand colors for main identity */
  --color-accent-50: oklch(97.5% 0.015 165);
  /* ... steps 100 to 900 ... */
  --color-accent-950: oklch(20% 0.03 165);

  /* Accent colors for highlights */
  --color-brand-50: oklch(98% 0.03 125);
  /* ... steps 100 to 900 ... */
  --color-brand-950: oklch(25% 0.06 125);
}

This is complete the same as Tailwind default levels. You can generate your own schemes using any Tailwind color generator, add them to custom.css in Yore's format, and a custom theme is easily created.

Yore natively supports the OKLCH color model, which allows you to define colors semantically. OKLCH separates colors into three components:

Lightness (L): How bright the color is
Chroma (C): How strong or vivid the color is
Hue (H): The color’s angle on the color wheel

OKLCH is much more predictable than RGB, where it is not possible to tweak a color by editing the RGB value. With OKLCH, you can adjust brightness, intensity, or hue independently, making it intuitive to adjust a certain just by value.

Learn more on the MDN documentation.

Semantic Tokens

assets/css/tokens.css defines all color nicknames. This avoids repeating color codes and ensures consistent appearance.

Example customization in assets/css/custom.css:

html[data-theme='light'] {
  --muted: red;
  --muted-foreground: brown;
}


html[data-theme='dark'] {
  --muted: green;
  --muted-foreground: lime;
}

Tailwind Tokens

Yore uses custom Tailwind tokens defined in assets/css/tailwind/theme.css.

Semantic tokens are integrated into Yore's custom Tailwind tokens. Instead of default classes like bg-red-50, Yore uses bg-CUSTOM_TOKEN to maintain thematic consistency across the site.

The class structure uses standard Tailwind prefixes (text-, bg-, border-) paired with the custom suffixes. This results in classes such as text-muted or bg-brand-foreground. Since theme.css references variables from tokens.css, you can modify specific colors via CSS variables without rebuilding Tailwind.

Building Your Own TailwindCSS

Info

This is more advanced than custom.css customization and requires pnpm and TailwindCSS.

Method 1: Tailwind CLI (Recommended)

You can also build your own Tailwind CSS if you need extra Tailwind classes.

Steps:

Install pnpm.
Copy package.json and assets/css/tailwind/ from the theme source.
Run pnpm i.
Use Tailwind classes like bg-red-500/87 and build with pnpm run build:css.
Confirm compiled.css includes bg-red-500\/87.

Tailwind v4 scans all project files, so Yore installed via Git submodule requires no additional setup. For Hugo module installation, vendor Yore first using hugo mod vendor.

Method 2: Hugo Pipe (Not Recommended)

Yore also supports Hugo's built-in css.TailwindCSS function. However, this method is not recommended for several reasons:

Inconsistency: The same CSS works perfectly with Tailwind CLI but requires extra configuration with Hugo Pipe.
Lack of Transparency: Hugo acts as a black box for Tailwind, making the build process less controllable.
Difficult Debugging: Troubleshooting is unintuitive due to the black box issue.
Maintenance: Method 1 only requires a simple manual diff sync during theme updates, whereas Method 2 requires debugging within the Hugo environment.

Steps:

Run pnpm install @tailwindcss/cli @tailwindcss/typography @tailwindcss/forms tailwind-scrollbar tailwindcss.
Configure hugo.yaml according to the Hugo documentation.
Set params.hugoTailwind: true in your hugo.yaml.

Customization

Override Templates

Usage Example

Extend Templates

Available Extension Points

Usage Examples

Customize CSS

Concept

Variable Architecture

Base Colors

Semantic Tokens

Tailwind Tokens

Building Your Own TailwindCSS

Method 1: Tailwind CLI (Recommended)

Method 2: Hugo Pipe (Not Recommended)

Backlinks

Article Connections