基于 VitePress Teek 主题移植的 Hugo 静态网站主题，专为技术博客和文档站点设计。

Hugo Teeker Theme 是将流行的 VitePress Teek 主题完整移植到 Hugo 平台的静态网站主题项目。适用于构建个人技术博客、文档库、知识管理系统等场景。

在线预览: https://wiki.xxdevops.cn

• 🎨 精美设计 - 移植自 VitePress Teek，保留原主题的精美界面
• 📱 响应式布局 - 完美适配桌面、平板、移动设备
• 🚀 极速构建 - 基于 Hugo 的快速构建引擎
• 📚 三栏文档模式 - 左侧目录导航 + 中间正文 + 右侧页内TOC
• 🔍 强大搜索 - 集成 Algolia 全文搜索
• 💬 评论系统 - 内置 Twikoo 评论支持
• 📊 数据统计 - 支持百度统计、Google Analytics、不蒜子
• 🎯 功能丰富 - 代码高亮、图片懒加载、分享按钮、暗色模式等

• 首页 - Hero背景图自动轮播、打字机效果副标题、分类卡片展示
• 文章页 - 文章统计、分享按钮、版权声明、上下篇导航
• 文档页 - 三栏布局、侧边栏折叠、页内目录高亮、面包屑导航
• 归档页 - 按时间归档的文章列表
• 分类/标签页 - 分类和标签聚合页面

• 搜索 - Algolia 全文搜索，支持中文分词
• 评论 - Twikoo 评论系统，支持 Markdown
• 分享 - 微博、Twitter、Facebook 等社交媒体分享
• 代码块 - 语法高亮、复制按钮、自动折叠
• 图片 - 懒加载、点击放大、相册模式
• 主题切换 - 浅色/暗色主题自动切换

• 多栏目支持 - 运维、前端、编程、黑客、专题等多个栏目
• 标签分类 - 灵活的分类和标签系统
• 草稿管理 - 支持草稿预览
• 文档分析 - 自动统计字数、阅读时长

技术	说明	版本
Hugo	静态网站生成器	v0.150.0+ (Extended)
Go	构建工具开发语言	v1.21+
SCSS	样式预处理器	-
JavaScript	前端交互脚本	ES6+
Algolia	搜索服务	-
Twikoo	评论系统	v1.6.41

hugo-teeker-theme/
├── hugo                          # Hugo 可执行文件 (v0.150.0+extended)
├── Makefile                      # 构建命令集合
├── AGENTS.md                     # 开发规范和指南
├── 总结.md                       # 项目架构总结
│
├── hugo-teek-site/               # Hugo 站点主目录
│   ├── config.toml               # 主配置文件（生产环境）
│   ├── config-dev.toml           # 开发配置文件
│   ├── content/                  # 内容目录
│   │   ├── docs/                 # 文档栏目
│   │   │   ├── 11.运维/
│   │   │   ├── 20.前端/
│   │   │   ├── 30.编程/
│   │   │   ├── 35.黑客/
│   │   │   ├── 40.专题/
│   │   │   └── 50.工具/
│   │   └── posts/                # 博客文章
│   ├── data/                     # 数据文件
│   │   └── docAnalysis.json      # 文档分析数据（自动生成）
│   ├── layouts/                  # 模板文件
│   ├── static/                   # 静态资源
│   ├── archetypes/               # 内容模板
│   └── public/                   # 构建输出（自动生成）
│
├── themes/                       # 主题目录
│   └── hugo-teek/                # Hugo Teek 主题
│       └── assets/               # 主题资源
│           ├── css/              # SCSS 样式文件
│           └── js/               # JavaScript 脚本
│
├── tools/                        # Go 构建工具
│   ├── permalink-gen/            # 永久链接生成器
│   ├── index-generator/          # 索引页生成器
│   ├── doc-analysis/             # 文档分析工具
│   └── docs-manager/             # 文档管理工具
│
├── vitepress-2.0.0-alpha.12/     # VitePress 原版参考（只读）
└── vitepress-theme-teek-1.5.1/   # VitePress Teek 主题参考（只读）

• Hugo Extended v0.150.0 或更高版本
• Go v1.21+ (用于构建工具)
• Git (用于版本管理)

Linux/macOS:

# 使用 Homebrew
brew install hugo

# 或下载二进制文件
wget https://github.com/gohugoio/hugo/releases/download/v0.150.0/hugo_extended_0.150.0_linux-amd64.tar.gz
tar -xzf hugo_extended_0.150.0_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/

验证安装:

hugo version
# 输出应包含 "+extended"

git clone https://github.com/yourusername/hugo-teeker-theme.git
cd hugo-teeker-theme

# 安装 Go 工具依赖
make install-deps

# 方式1: 使用 Makefile（推荐）
make dev

# 方式2: 直接使用 Hugo
./hugo server --source=hugo-teek-site --bind=0.0.0.0 --port=8080 --buildDrafts

# 方式3: 快速预览（跳过预生成）
make quick

访问 http://localhost:8080 查看网站。

# 创建博客文章
./hugo new posts/my-first-post.md --source=hugo-teek-site

# 创建文档页面
./hugo new docs/11.运维/docker-tutorial.md --source=hugo-teek-site

编辑生成的 Markdown 文件，修改 Front Matter 和内容：

---
title: "我的第一篇文章"
date: 2025-10-23T18:00:00+08:00
draft: false
description: "这是一篇示例文章"
categories: ["技术"]
tags: ["Hugo", "博客"]
---

## 你好，世界！

这是我的第一篇博客文章。

保存后，页面会自动刷新显示新文章。

项目提供了一系列便捷的 Make 命令：

# 查看所有可用命令
make help

# 开发模式（生成数据 + 启动服务器）
make dev

# 快速预览（不生成数据）
make quick

# 生成永久链接
make gen-permalink

# 生成索引页
make gen-index

# 生成文档分析数据
make gen-doc-analysis

# 构建生产版本
make build

# 清理构建文件
make clean

项目包含多个 Go 编写的构建工具，用于预处理内容：

自动为文章生成 SEO 友好的永久链接，更新 Front Matter 中的 slug 字段。

make gen-permalink

自动生成分类、标签、归档等索引页面。

make gen-index

统计文档字数、阅读时长等信息，生成 data/docAnalysis.json。

make gen-doc-analysis

内容目录采用"数字前缀 + 名称"的方式组织：

content/docs/
├── 11.运维/          # 运维相关文档
├── 20.前端/          # 前端技术文档
├── 30.编程/          # 编程语言文档
├── 35.黑客/          # 安全技术文档
├── 40.专题/          # 专题系列文档
└── 50.工具/          # 工具使用文档

数字前缀用于控制显示顺序，Hugo 会自动识别并排序。

标准的文章 Front Matter 格式：

---
title: "文章标题"                    # 必填
date: 2025-10-23T18:00:00+08:00    # 必填
draft: false                        # 是否草稿
description: "文章描述"             # SEO 描述
categories: ["分类"]                # 分类（数组）
tags: ["标签1", "标签2"]           # 标签（数组）
slug: "article-slug"                # URL slug（可选，自动生成）
coverImg: "https://..."             # 封面图（可选）
author: "作者名"                    # 作者（可选）
---

主题样式位于 themes/hugo-teek/assets/css/：

themes/hugo-teek/assets/css/
├── main.scss                 # 主样式入口
├── _variables.scss           # 变量定义
├── _base.scss                # 基础样式
├── _layout.scss              # 布局样式
└── components/               # 组件样式
    ├── _header.scss
    ├── _footer.scss
    └── ...

修改变量示例（_variables.scss）：

// 主题颜色
$primary-color: #3498db;
$secondary-color: #2ecc71;
$text-color: #333333;
$bg-color: #ffffff;

// 字体
$font-family: "PingFang SC", "Microsoft YaHei", sans-serif;
$code-font: "Fira Code", "Consolas", monospace;

// 尺寸
$container-width: 1280px;
$sidebar-width: 280px;

模板文件位于 hugo-teek-site/layouts/：

layouts/
├── _default/                 # 默认模板
│   ├── baseof.html           # 基础模板
│   ├── single.html           # 单页模板
│   └── list.html             # 列表模板
├── partials/                 # 部分模板
│   ├── header.html
│   ├── footer.html
│   └── ...
└── shortcodes/               # 短代码
    └── ...

创建自定义 Shortcode 示例：

<!-- layouts/shortcodes/notice.html -->
<div class="notice notice-{{ .Get 0 }}">
  {{ .Inner | markdownify }}
</div>

在文章中使用：

{{</* notice info */>}}
这是一个提示信息！
{{</* /notice */>}}

编辑 hugo-teek-site/hugo.toml：

baseURL = "https://yourdomain.com"
languageCode = "zh-CN"
title = "你的网站标题"
theme = "hugo-teek"

[params]
  description = "网站描述"
  keywords = ["关键词1", "关键词2"]

  # 博主信息
  [params.blogger]
    avatar = "https://your-avatar-url.jpg"
    name = "你的名字"
    slogan = "你的签名"

# 一级菜单
[[menu.main]]
  name = "首页"
  url = "/"
  weight = 1

# 带下拉的菜单
[[menu.main]]
  name = "文档"
  url = "/docs/"
  weight = 2
  identifier = "docs"

  # 子菜单
  [[menu.main]]
    name = "运维"
    url = "/docs/linux/"
    weight = 1
    parent = "docs"

[params.algolia]
  enabled = true
  appId = "YOUR_APP_ID"
  apiKey = "YOUR_SEARCH_API_KEY"
  indexName = "YOUR_INDEX_NAME"

[params.comment]
  enabled = true
  provider = "twikoo"
  envId = "https://your-twikoo-url.com/"
  version = "1.6.41"

[params.analytics]
  # 百度统计
  [params.analytics.baidu]
    id = "YOUR_BAIDU_ID"

  # Google Analytics
  [params.analytics.google]
    id = "G-YOUR_GA_ID"

  # 不蒜子统计
  [params.analytics.busuanzi]
    enabled = true
    url = "https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"

[markup.highlight]
  codeFences = true
  guessSyntax = true
  lineNos = true
  lineNumbersInTable = true
  noClasses = false
  style = "monokai"  # 可选: monokai, github, dracula 等
  tabWidth = 2

# 构建生产版本
make build

# 或直接使用 Hugo
./hugo --source=hugo-teek-site --minify

构建产物位于 hugo-teek-site/public/ 目录。

# 构建
make build

# 上传到服务器
rsync -avz hugo-teek-site/public/ user@server:/var/www/html/

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 开启 Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

创建 .github/workflows/deploy.yml：

name: Deploy Hugo site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.150.0'
          extended: true

      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'

      - name: Build
        run: |
          make install-deps
          make build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./hugo-teek-site/public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

创建 Dockerfile：

FROM hugomods/hugo:exts as builder

WORKDIR /src
COPY . .
RUN make build

FROM nginx:alpine
COPY --from=builder /src/hugo-teek-site/public /usr/share/nginx/html
EXPOSE 80

构建并运行：

docker build -t hugo-teek-blog .
docker run -d -p 80:80 hugo-teek-blog

编辑 hugo-teek-site/data/heroBg.yaml 配置背景图：

list:
  - https://img1.example.com/bg1.jpg
  - https://img2.example.com/bg2.jpg
  - https://img3.example.com/bg3.jpg

配置副标题打字机效果（hugo.toml）：

[params.heroSubtitle]
  typeSpeed = 90        # 打字速度（毫秒/字符）
  deleteSpeed = 45      # 删除速度（毫秒/字符）
  hold = 1800           # 保持时间（毫秒）
  nextDelay = 600       # 下一句延迟（毫秒）
  shuffle = false       # 是否随机顺序

在首页显示分类卡片：

[params.category]
  enabled = true
  limit = 8             # 显示卡片数量
  autoPage = true       # 自动翻页
  pageSpeed = 4000      # 翻页速度（毫秒）

创建 content/about/friend-links.md：

---
title: "友情链接"
layout: "friends"
---

## 我的朋友们

这里是我的友链列表...

在 data/friends.yaml 中配置友链：

friends:
  - name: "示例网站"
    link: "https://example.com"
    avatar: "https://example.com/avatar.jpg"
    description: "这是一个示例网站"

编辑 hugo.toml 添加多语言配置：

[languages]
  [languages.zh-cn]
    languageName = "简体中文"
    weight = 1

  [languages.en]
    languageName = "English"
    weight = 2

    [languages.en.params]
      description = "English Description"

A: 确保使用的是 Hugo Extended 版本：

hugo version
# 输出应包含 "+extended"

A: 检查是否安装了 Hugo Extended 版本，并清理缓存：

make clean
make build

A: 检查图片路径：

• 放在 static/img/ 的图片，使用 /img/xxx.jpg 引用
• 外部图片使用完整 URL

A: 尝试清理缓存并重启服务器：

make clean
make dev

A: 检查以下配置：

1. params.comment.enabled 是否为 true
2. Twikoo envId 是否正确
3. 浏览器控制台是否有错误

A: 检查 Algolia 配置：

1. appId、apiKey、indexName 是否正确
2. 是否已在 Algolia 创建索引并上传数据

A: 重新安装依赖：

make install-deps

A: 更换端口启动：

./hugo server --source=hugo-teek-site --port=8090

遵循 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

类型（type）：

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 重构
• perf: 性能优化
• test: 测试相关
• chore: 构建工具或辅助工具的变动

示例：

feat(nav): 添加导航下拉菜单功能

- 实现多级菜单支持
- 添加菜单图标配置
- 优化移动端菜单体验

Closes #123

• Hugo 模板: 2空格缩进，使用 {{- -}} 去除空白
• SCSS: 2空格缩进，变量统一在 _variables.scss 定义
• JavaScript: 2空格缩进，使用 ES6+ 语法，camelCase 命名
• Go: 遵循 gofmt 格式，使用 go vet 检查

• main: 主分支，稳定版本
• develop: 开发分支
• feature/*: 功能分支
• bugfix/*: 修复分支
• release/*: 发布分支

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'feat: Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

• 遵循代码规范和提交规范
• 包含清晰的描述和截图（UI 变更）
• 测试通过（make build 无错误）
• 更新相关文档

本项目基于 MIT License 开源。

• Hugo - 强大的静态网站生成器
• VitePress Teek - 原始主题设计
• 所有贡献者和使用者

• 博客: https://xxdevops.cn
• Email: your-email@example.com
• Issues: GitHub Issues

• Hugo 官方文档
• Hugo 主题开发指南
• VitePress 官方文档
• 快速开始指南
• 开发规范文档
• 项目架构总结

---

⭐ 如果这个项目对你有帮助，请给个 Star！

Made with ❤️ by 余温Gueen