认识 Kuan：为中文长文设计的 Hugo 主题

Kuan 是一款为中文写作和阅读设计的 Hugo 主题。它把页面留给内容，同时提供细致的目录、进度、主题色和图片交互。

阅读体验#

文章标题和正文可以使用同一套色彩体系。目录可以在桌面端伴随阅读，也可以在移动端折叠。图片点击后进入灯箱，代码、表格、无序列表和待办事项都有与主题颜色协调的样式。

配色包含经典、海洋、森林、深秋、赛博朋克和交易行。读者可以在主题设置页中选择明暗模式与配色，并保存字体及动画偏好。

按栏目设置卡片与连续阅读#

card 和 continue 是栏目级选项，应设置在栏目目录的 _index.md 中。它们会统一应用于该栏目下的文章，而不是逐篇设置。例如，要将 content/notes/ 栏目设为卡片样式并加入连续阅读，在 content/notes/_index.md 中写入：

yaml
---
title: 随笔
description: 主题示例文章与阅读体验。
weight: 1
card: true
continue: true
---

card: true 会把文章标题、日期和摘要放在主题色块中。continue: true 会将该栏目文章加入按日期从新到旧排列的连续阅读流，并启用阅读导航、进度提示和按需加载。两个选项可分别启用。

文章页只需保留文章自身的信息和文章级选项，例如：

yaml
---
title: 一篇示例文章
date: 2026-09-27
toc: true
math: false
comments: false
---

连续阅读最多预先准备五篇文章。新文章靠近视口时再呈现淡入效果；文章之间的阅读进度与顶部导航会随当前文章切换。

安装主题#

推荐把主题作为 Git 子模块放进 Hugo 站点：

git submodule add https://github.com/461c/hugo-theme-kuan.git themes/kuan

然后在 Hugo 配置文件中设置：

yaml
theme: kuan
languageCode: zh-CN
title: 我的站点
hasCJKLanguage: true

taxonomies:
  topic: topics

markup:
  tableOfContents:
    startLevel: 2
    endLevel: 4

params:
  brandName: 我的站点
  description: 站点说明
  toc: true
  math: false
  fonts:
    enabled: false

Hugo 0.125.0 或更高版本适用。将示例配置复制到站点后，可按需调整站点名称、描述、导航、字体和评论配置。

撰写文章#

在 content/栏目/ 下创建 Markdown 文件。文章日期、摘要、目录及文章级功能都写在文章 Front Matter 中：

yaml
---
title: 新文章
date: 2026-09-27
description: 文章摘要
topics: [随笔]
toc: true
math: false
comments: false
---

正文使用标准 Markdown。图片灯箱会自动适配普通 Markdown 图片；也可为文章启用 KaTeX 数学公式或 Giscus 评论。

本地预览#

在主题仓库根目录运行：

ln -s ../.. exampleSite/themes/kuan
hugo --source exampleSite server

打开本地 Hugo 服务器，即可查看示例首页和这篇介绍文章。连续阅读示例还包含下一篇文章，方便测试流式浏览。