方案简介

Toha 是一个面向个人作品集（personal portfolio）的 Hugo 主题，采用极简设计并完全响应式。它不是一个单一工具，而是一套完整的技术配方：以 Hugo extended（0.163.0+）为静态站点生成器，通过 Hugo Modules（基于 Go modules 机制）将主题作为模块依赖引入用户自己的仓库，再用 npm 管理主题所需的前端节点依赖，本地以 hugo server -w 热更新预览。主题内置经验时间线、成就画廊、文章侧边栏分类、Short Codes、多语言支持（22 种以上语言翻译）以及多种站点统计（GoatCounter、counter.dev、Google Analytics、Matomo/Piwik）与评论支持。适合希望快速拥有个人主页/博客/作品集的开发者，最简路径是直接 fork 官方示例站点 toha-example-site 再改配置即可上线。

亮点与能力

• 极简设计（Minimalist Design）
• 完全响应式（Fully Responsive）
• 多语言支持（Multiple Language Support）
• 精心设计的卡片（Carefully Designed Cards）
• 经验时间线（Experience Timeline）
• 成就画廊（Achievement Gallery）
• 侧边栏文章分类（Sidebar to Categorize the Posts）
• Short Codes 短代码
• 统计支持：GoatCounter、counter.dev、Google Analytics、Matomo/Piwik
• 评论支持（Comment Support）

组成与分工

• Hugo：静态站点生成器，要求 extended 版本 0.163.0 或更高；
• Hugo Modules：依赖管理机制，通过 go.mod 将 toha 主题作为模块引入，实现主题与站点内容解耦；
• Go 语言 1.19+：Hugo modules 运行所需；
• Node v18.x+ / npm 8.x+：hugo mod npm pack 生成 package. 后安装主题的前端依赖；
• GoatCounter / counter.dev / Google Analytics / Matomo(Piwik)：可选的站点统计分析服务；
• jdx/mise（仅主题开发）：统一安装 hugo、go、node 等工具到合适版本。

前置要求

运行本主题需要以下环境：

• Hugo Version 0.163.0 (extended) or higher
• Go language 1.19 or higher (require for hugo modules)
• Node version v18.x or later and npm 8.x or later.

若参与主题本地开发，可安装 mise 以简化依赖管理：

bash
mise install

该命令会安装 hugo、go、node 及运行项目所需的其他工具到合适版本。

实施步骤

1. 初始化 Hugo 模块

在仓库中初始化 Hugo modules，会生成 go.mod 文件：

bash
hugo mod init github.com//

2. 将主题加入模块依赖

在 hugo.yaml 中添加 module 段：

yaml

Use Hugo modules to add theme

module:
imports:

• path: github.com/hugo-toha/toha/v4

3. 更新模块

bash
hugo mod tidy

4. 生成 node 依赖配置

bash
hugo mod npm pack

5. 安装依赖

bash
npm install

6. 本地运行

bash
hugo server -w

首次运行站点使用默认参数，外观类似示例站点，但首页尚无板块，需按官方配置指南在配置文件中添加。

使用与配置要点

• 最简用法：直接 fork toha-example-site 示例仓库，然后按需修改配置；
• 首页各板块需在配置文件中显式配置后才会显示；
• 多语言：从 22 种可用翻译中选择，翻译方法参考官方文档，数据与文章格式可参考 example site 仓库；
• 统计：在配置中接入 GoatCounter、counter.dev、Google Analytics 或 Matomo/Piwik；
• 内容与数据：参照 example site 的 data 和 post 格式组织；
• 验证成功：本地运行 hugo server -w 后页面与 toha-example-site 相似即说明主题加载成功。

注意事项与常见问题

• 环境版本要求严格：Hugo 必须 extended 版本 0.163.0+，Go 1.19+ 仅在需要 hugo modules 时必需；
• 作者声明：'I am not a web developer. I have created this theme for my personal needs. So, it is reasonable to have some flaws in the codes.'，代码可能存在缺陷，遇到问题可开 issue 或 PR；
• 贡献原则：保持简单、与设计一致、尽量少用依赖、有耐心；
• 主题本地开发需先 fork 主题仓库，并通过 exampleSite 目录内的 hugo.yaml 修改配置、添加内容或数据；修改会即时反映在运行中的站点上。

优缺点

• ✓ 极简设计且完全响应式
• ✓ 支持多语言与统计分析
• ✕ 需 Hugo extended 0.16
• ✕ 作者自述非 Web 开发者，代码或有缺陷

出处

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