hugo-theme-liquid — Hugo Blog Template

SHA-256: 927ddbc4e5fec4237bb1a5bd22f29d9dc1d5d9817c817c218a98dffacbfc05c3

2026-10-12T07:08:05.952Z

# Hugo Theme Liquid

ENGLISH ｜ [简体中文](README.zh-CN.md)

Hugo Theme Liquid is a quiet, responsive blog theme for Hugo. It combines a readable editorial layout with progressive liquid-glass surfaces that fall back to ordinary CSS when advanced browser effects are unavailable.

**Live demo:** [demo.liquid.wych.xyz](https://demo.liquid.wych.xyz)

## Features

- Responsive home, article, section, taxonomy, and 404 layouts
- Hugo-native pagination, table of contents, RSS, and Markdown rendering
- Categories and tags with configurable taxonomy names
- Article metadata: publication date, last modified date, reading time, word count, and previous/next navigation
- Light, Dark, and System appearance modes with persisted user preference
- Progressive Liquid Glass enhancement with CSS fallback, reduced-quality mode, and reduced-motion support
- Responsive code blocks, tables, images, long links, and long words
- Basic SEO metadata: title, description, canonical URL, Open Graph, and article metadata
- Semantic HTML, keyboard focus styles, accessible controls, and no-JavaScript core navigation
- No React, Vue, Tailwind, or third-party runtime dependency

## Requirements

- Hugo 0.128.0 or later
- A Hugo site configuration file named hugo.yaml, hugo.toml, or config/_default/*
- Go 1.18 or later when using Hugo Modules or building the included exampleSite

## Installation

### Git submodule

From an existing Hugo site:

~~~bash
git submodule add https://github.com/wych/hugo-theme-liquid themes/hugo-theme-liquid
~~~

Add the theme name to the site configuration:

~~~yaml
theme: "hugo-theme-liquid"
~~~

### Local copy

Copy this repository into your site's themes/ directory and set theme: "hugo-theme-liquid" in the site configuration.

### Hugo Module

From the root of an existing Hugo site, initialize the site as a Hugo Module:

~~~bash
hugo mod init github.com/your-account/your-site
~~~

Add the theme as a module import:

~~~yaml
module:
  imports:
    - path: github.com/wych/hugo-theme-liquid
~~~

Pin the release and tidy the module files:

~~~bash
hugo mod get github.com/wych/[email protected]
hugo mod tidy
~~~

Hugo Modules require Go 1.18 or later.

## Quick start

The included demo runs directly from this repository:

~~~bash
cd exampleSite
hugo server
~~~

Build the demo for production with:

~~~bash
hugo --minify
~~~

The exampleSite can be used to preview the current theme locally.

## Minimal site configuration

This is a starting point for a new Hugo site. Copy it into the site's configuration and add your own content.

~~~yaml
baseURL: "https://example.com/"
locale: "en-US"
title: "My Hugo site"
theme: "hugo-theme-liquid"

menu:
  main:
    - name: "Home"
      url: "/"
      weight: 10
      params:
        icon: home
    - name: "Posts"
      url: "/posts/"
      weight: 20
      params:
        icon: article

taxonomies:
  tag: tags
  category: categories

pagination:
  pagerSize: 10
  path: page

markup:
  tableOfContents:
    startLevel: 2
    endLevel: 3

outputs:
  home:
    - HTML
    - RSS

params:
  mainSection: "posts"
  author: "Site Demo"
  description: "A short description of my site."
  appearance:
    defaultTheme: auto
    enableThemeToggle: true
  home:
    showProfile: true
    showRecentPosts: true
    recentPostsLimit: 10
  article:
    showToc: true
    showReadingTime: true
    showWordCount: true
    showLastModified: true
    showPrevNext: true
~~~

For a complete configuration example, see [exampleSite/hugo.yaml](exampleSite/hugo.yaml).

## Configuration

### Site identity and branding

The theme reads these values from params:

| Parameter | Purpose |
| --- | --- |
| author | Display name and SEO author value |
| handle | Optional handle below the display name |
| tagline | Optional profile tagline |
| bio | Optional profile biography |
| description | Site-wide SEO and RSS fallback description |
| copyright | Footer text |
| logo | Optional logo image path |
| logoText | Text mark used when no logo image is configured |
| avatar | Optional avatar image path |
| favicon | Optional favicon path |
| themeColor / themeColorDark | Browser theme colors for light and dark modes |
| image / images | Site-wide Open Graph image fallback |

github and email provide simple social-link fallbacks. For multiple links, use params.social:

~~~yaml
params:
  social:
    - name: "GitHub"
      url: "https://github.com/"
      icon: github
      newTab: true
~~~

Leave these values empty or omit them if the site should not display social or email links.

### Home page and taxonomy

~~~yaml
params:
  mainSection: "posts"       # Takes precedence over mainSections when both exist.
  mainSections: [posts]       # Optional list of sections aggregated on the home page.
  taxonomy:
    tag: tags                 # Must match the site-level taxonomy name.
    category: categories
  tags: []                    # Optional explicit home-page tag cloud.
  home:
    showProfile: true
    showRecentPosts: true
    recentPostsLimit: 0       # 0 uses pagination.pagerSize; positive values override it.
~~~

If params.tags is empty, the home page derives the tag cloud from existing taxonomy terms. The params.taxonomy.tag and params.taxonomy.category values allow custom taxonomy names.

### Article options

~~~yaml
params:
  article:
    showToc: true
    showReadingTime: true
    showWordCount: true
    showLastModified: true
    showPrevNext: true
~~~

The legacy params.toc.enabled, params.articleMeta.*, and params.colorScheme.* settings remain supported for compatibility. The newer article, appearance, and enableThemeToggle values take precedence when present.

### Liquid Glass

Liquid Glass is progressive enhancement. The readable CSS surface remains active when JavaScript is disabled, when the browser lacks the required filter capabilities, or when a lower quality is selected.

~~~yaml
params:
  liquidGlass:
    enabled: true
    quality: auto              # auto | full | reduced | css
    articleQuality: reduced    # full | reduced | css
    fullComponents:
      - navbar
    mode: standard             # standard | prominent
    interaction: true
    pauseOnScroll: true
    displacementScale: 9
    blurAmount: 0.5
    saturation: 145
    aberrationIntensity: 2
    elasticity: 0.15
~~~

quality is the global quality ceiling. fullComponents is the allow-list for named full-quality components; the current theme names its desktop and mobile navigation navbar. articleQuality controls article cards independently. glass-heavy surfaces use the prominent visual mode. Conservative optical values are recommended for consistent performance across browsers.

### Appearance and accessibility

~~~yaml
params:
  appearance:
    defaultTheme: auto         # auto | light | dark
    enableThemeToggle: true
~~~

The theme follows prefers-color-scheme in auto mode and stores an explicit user choice in localStorage. prefers-reduced-motion: reduce disables or reduces decorative motion and advanced interaction without hiding core content.

## Content model

Create articles in a section listed by mainSection or mainSections, usually content/posts/:

~~~yaml
---
title: "A readable post"
date: 2026-01-01
description: "A short summary used by cards and metadata."
categories:
  - Notes
tags:
  - Hugo
  - Writing
image: "cover.jpg" # Page-bundle resource or a path under static/.
draft: false
---
~~~

Markdown supports headings, paragraphs, emphasis, links, blockquotes, ordered and unordered lists, nested lists, inline code, fenced code blocks, tables, horizontal rules, and images. Start article body headings at level 2 when the template already provides the page title as the main h1.

Page-bundle images are resolved before static paths for article images and Open Graph metadata. Images remain constrained to the content width.

## License

Hugo Theme Liquid is released under the MIT License. See [LICENSE](LICENSE) for the full license text.