hugo-theme-lucent — Hugo Blog Template

SHA-256: 5c382ce1e8fa0bfa114349106e69ada9538f2b52a019f287916bb3367c19ed4a

2026-10-13T06:31:25.512Z

# Lucent

A clean, fast and feature-rich blog theme for [Hugo](https://gohugo.io/).
Single-column, typography-first, zero JavaScript frameworks.

## Features

- 🌗 **Dark / light mode** — follows the system preference, remembers the visitor's choice, no flash on load
- 🔍 **Client-side search** — Hugo-generated JSON index + ~150 lines of vanilla JS, no dependencies
- 📑 **Table of contents** — collapsible, per-post toggle
- 🗂 **Archive page** grouped by year, and a **tag cloud** with counts
- 🔗 **Related posts** via Hugo's built-in content relations
- ⏱ **Reading time, word count, last-updated** meta
- 📋 **Copy button on code blocks**, syntax highlighting themed for both modes, `hl_lines` support
- 📊 **Reading progress bar** and back-to-top button
- 🖼 **Image lightbox**, lazy loading, `<figure>` captions from image titles
- 🧮 **KaTeX math** (opt-in per page or site-wide)
- 💬 **giscus comments** (lazy-loaded, theme-synced)
- 📈 **Analytics**: Plausible, Umami, or Google Analytics
- 🧩 **Shortcodes**: `notice` (note / tip / warning / danger), `details`, `quote`
- 🌍 **i18n** — English and Simplified Chinese included; CJK-friendly font stack
- 🔎 **SEO** — Open Graph, Twitter cards, JSON-LD, canonical URLs, RSS
- ♿ Skip link, focus styles, reduced-motion support, semantic HTML
- 📱 Fully responsive, print stylesheet included

Requires **Hugo ≥ 0.128** (standard edition is fine — no Sass).

## Quick start

```bash
hugo new site myblog && cd myblog
git init
git submodule add https://github.com/simple-is-awesome/hugo-theme-lucent themes/hugo-theme-lucent
cp themes/hugo-theme-lucent/exampleSite/hugo.toml .
cp -r themes/hugo-theme-lucent/exampleSite/content .
hugo server -D
```

Or preview the example site from inside this repo:

```bash
hugo server -s exampleSite --themesDir ../..
```

## Configuration

The example site's [`hugo.toml`](exampleSite/hugo.toml) documents every option.
The important non-obvious bits:

```toml
# Search needs the JSON output format on the home page:
[outputs]
  home = ["html", "rss", "json"]

# Syntax highlighting must use CSS classes (the theme ships light+dark colors):
[markup.highlight]
  noClasses = false

# Standalone images become <figure> elements:
[markup.goldmark.parser]
  wrapStandAloneImageWithinParagraph = false

# For math: keeps LaTeX out of markdown processing so KaTeX sees it intact.
# Write display math as $$…$$ and inline math as \(…\).
[markup.goldmark.extensions.passthrough]
  enable = true
  [markup.goldmark.extensions.passthrough.delimiters]
    block = [["\\[", "\\]"], ["$$", "$$"]]
    inline = [["\\(", "\\)"]]
```

### Theme params

| Param                 | Default          | What it does                                  |
| --------------------- | ---------------- | --------------------------------------------- |
| `description`         | —                | Site description (hero subtitle fallback, SEO) |
| `author`              | site title       | Byline, copyright, JSON-LD                    |
| `avatar`              | — (monogram)     | Home hero image, e.g. `images/avatar.png`     |
| `favicon`             | ✦ (inline SVG)   | Path to a favicon                             |
| `accent` / `accentDark` | indigo         | Accent color per mode, any CSS color          |
| `dateFormat`          | `Jan 2, 2006`    | Go date layout for post dates                 |
| `archiveDateFormat`   | `Jan 2`          | Date layout on the archive page               |
| `recentCount`         | `5`              | Posts on the home page                        |
| `showToc` / `tocOpen` | `true` / `true`  | Table of contents behavior                    |
| `showShare`           | `true`           | Share row under posts                         |
| `showReadingProgress` | `true`           | Top progress bar on posts                     |
| `math`                | `false`          | Load KaTeX site-wide                          |
| `hideCredits`         | `false`          | Hide the "Hugo · Lucent" footer credit        |
| `hero.title` / `hero.subtitle` | site title / description | Home hero text        |
| `socialIcons`         | —                | List of `{ name, url }` (see below)           |

Social icon names: `github`, `twitter`, `x`, `mail`, `rss`, `linkedin`,
`telegram`, `youtube`, `instagram`, `facebook`, `globe` — anything else
falls back to a link icon. Add `icon = "globe"` to override the glyph.

### Front matter

```yaml
title: "My post"
date: 2026-07-01
description: "Used for summaries and SEO."   # optional
tags: ["hugo"]
math: true        # load KaTeX for this page
showToc: false    # hide the TOC for this page
share: false      # hide the share row
comments: false   # disable giscus for this page
```

### Archives & search pages

Create two content files (the example site already has them):

```yaml
# content/archives.md
---
title: "Archive"
layout: "archives"
---

# content/search.md
---
title: "Search"
layout: "search"
---
```

### Comments (giscus)

Fill in the values from [giscus.app](https://giscus.app):

```toml
[params.comments.giscus]
  repo = "user/repo"
  repoId = "R_xxx"
  category = "Announcements"
  categoryId = "DIC_xxx"
```

### Chinese interface

Set `defaultContentLanguage = "zh-cn"` and the UI strings switch to the
bundled Simplified Chinese translations (`i18n/zh-cn.toml`).

## Shortcodes

```markdown
{{</* notice tip "Optional custom title" */>}}
Callout body with **markdown**.
{{</* /notice */>}}

{{</* details "Summary text" */>}}
Collapsible content.
{{</* /details */>}}

{{</* quote author="Ada Lovelace" source="Notes" url="https://…" */>}}
The quote itself.
{{</* /quote */>}}
```

## Credits

This theme is a work by **Claude Fable 5** (Anthropic's Claude Code).

## License

[MIT](LICENSE)