基于 Hugo 模块化的高级极简响应式博客主题方案

方案简介

基于 Hugo 模块化的高级极简响应式博客主题方案。Hugo 提供静态站点生成与模块机制，Bootstrap 提供样式图标，Dart Sass 编译主题样式

亮点与能力

• Accessibility（无障碍）
• Atom feeds 与 RSS feeds
• Bootstrap styles and icons
• 面包屑（Breadcrumbs）、菜单、目录（Table of contents）
• 暗色/亮色配色方案（Dark/Light color scheme）
• 多种 shortcode：Code、Email、Figure、Gallery、Icon、Image、Quote、Tab、Vimeo、YouTube
• 图片像素密度、缩略图、尺寸断点
• 国际化与本地化、RTL 右到左语言支持
• 数学排版（Math typesetting）与搜索
• 作者、博客、分类、系列、标签等分类体系
• SEO 与 JSON-LD schema 自动生成
• 单栏响应式设计，支持 Safari 与 Firefox Reader View
• 经 PageSpeed 与 W3C Validator 验证

组成与分工

• Hugo：静态站点生成器，要求 extended 版本且至少 0.141.0，负责内容渲染、shortcode、feeds、搜索等；通过 Hugo Modules 管理主题依赖。
• Paige：本主题模块，提供极简响应式布局、Bootstrap 样式封装、大量可覆盖的 paige 参数与 shortcode。
• Dart Sass：编译主题的 Sass/SCSS 样式（因此 Hugo 必须 extended 版）。
• Bootstrap：提供样式与图标体系，包括 alert class 等。
• hugo.toml：站点与主题配置文件，配置 markup.highlight、module.imports 及 [paige] 参数。

前置要求

• 安装 Hugo（必须 extended 版本，且至少 0.141.0）与 Dart Sass。

Homebrew on Mac：
sh
$ brew install hugo sass/sass/sass

Chocolatey on Windows：
sh
$ choco install hugo-extended sass

Snap on Linux：
sh
$ sudo snap install dart-sass hugo

实施步骤

1. 安装 Hugo 与 Dart Sass

见前置要求中的三条平台安装命令。

2. 创建站点

sh
$ hugo new site yoursite

3. 创建文章

sh
$ cd yoursite
$ hugo new yourpost.md

4. 配置你的模块

sh
$ sh
$ cd yoursite
$ hugo mod init github.com/youraccount/yoursite
$ cat >>hugo.toml < [markup.highlight]
noclasses = false
style = "github"
EOF

5. 配置 Paige 模块

sh
$ sh
$ cd yoursite
$ hugo mod get github.com/willfaught/paige@latest
$ cat >>hugo.toml < [[module.imports]]
path = "github.com/willfaught/paige"
EOF

6. 开发运行

sh
$ cd yoursite
$ hugo server --buildDrafts

7. 生产构建

sh
$ cd yoursite
$ hugo --environment production --minify

使用与配置要点

主题参数通过 hugo.toml 中单一参数对象配置，可在站点或页面级覆盖。常用示例：

toml
[paige]
enable_math = false # Enables math typesetting for this page
exclude_feeds = false # Excludes this page from feeds
exclude_search = false # Excludes this page from search
style = "" # CSS included in a stylesheet for this page

[paige.alert]
message = "" # Markdown displayed before the page body for this page
type = "primary" # Bootstrap alert class for this page

[paige.pages] 提供大量 disable_* 开关控制内容与展示（作者、日期、目录、字数、上下篇等），以及标题级别调整与 JSON-LD schema 配置：

toml
[paige.pages]
disable_authors = false
disable_toc = false
full_width = false # Whether the page body fills the page width
disable_auto_schema = false # Disables the automatic JSON-LD schema generation

自定义扩展点：analytics 代码放入 yoursite/layouts/_partials/paige/site-last.html；评论代码放入 yoursite/layouts/_partials/paige/page-body-last-page.html。更新主题使用：

sh
$ cd yoursite
$ hugo mod get github.com/willfaught/paige@latest

注意事项与常见问题

• Hugo 必须是 extended 版本且至少 0.141.0。
• Paige 使用 Semantic Versioning，当前主版本为 0，会不定期出现破坏性变更，更新后必须测试你的站点。
• 默认一切功能都启用，很可能不是你想要的，可参考 minimal look 章节决定禁用哪些。
• 默认页面主体横跨整个容器（几乎占满窗口），可通过 narrow look / narrow-and-wide look 章节自定义。
• 面包屑、集合、章节与页面链接足以浏览任何站点，因此可以安全禁用菜单；仅有少量根级章节且无嵌套时，仅用菜单导航也可行。

优缺点

• ✓ 极简响应式设计
• ✓ 模块化安装易更新
• ✕ 主版本 0 存在破坏性变更
• ✕ 默认全开启需自行精简

出处

本方案挖掘自开源项目 willfaught/paige，方案内容与实施命令均来自其 README 原文。