Hugo 博客写作指南（四）：ChangAn 主题特色功能详解

2026-03-04 9 分钟 3956 字
技术教程 Hugo ChangAn 主题 特色功能
Hugo 博客写作指南（四）：ChangAn 主题特色功能详解

Hugo 博客写作指南（四）：ChangAn 主题特色功能详解

本文是 Hugo 博客写作指南系列的第四篇，详细介绍 ChangAn 主题的特色功能和使用技巧。

ChangAn 是一个现代化的 Hugo 博客主题，基于 astro-gyoza 风格设计，具有简洁、可爱、快速的特点。本文将详细介绍主题的各项特色功能。

主题特点概览

核心理念

  • Clean（简洁） - 干净清爽的界面设计
  • Cute（可爱） - 细腻的动画和交互细节
  • Fast（快速） - 优化的性能和加载速度

主要特性

特性说明
🎨 响应式设计完美适配手机、平板、电脑
🌓 深色模式自动/手动切换，保护视力
🔍 全文搜索快速定位文章内容
📱 移动端优化专门的移动端菜单和布局
🎯 代码高亮macOS 风格代码块
📊 目录导航文章目录自动生成
🔗 社交分享支持多个社交平台
⚡ 性能优化快速加载，SEO 友好

1. 响应式设计

ChangAn 主题采用移动优先的设计理念，自动适配各种屏幕尺寸。

断点设置

/* 移动端 */
@media (max-width: 768px) { }

/* 平板端 */
@media (min-width: 769px) and (max-width: 1024px) { }

/* 桌面端 */
@media (min-width: 1025px) { }

响应式特性

导航栏：

  • 桌面端：完整导航菜单 + 主题切换按钮
  • 移动端：汉堡菜单 + 全屏侧边栏

首页布局：

  • 桌面端：左侧边栏 + 主内容区
  • 移动端：单栏布局

文章页面：

  • 桌面端：主内容区 + 右侧目录
  • 移动端：单栏布局，目录隐藏

代码块：

  • 自动横向滚动
  • 移动端优化显示

测试响应式

在浏览器开发者工具中测试：

iPhone 14 Pro: 393 x 852
iPad Pro: 1024 x 1366
Desktop: 1920 x 1080

2. 深色模式

ChangAn 主题支持完整的深色模式，包括自动切换和手动切换。

自动切换

主题会根据系统偏好自动切换：

// 检测系统主题偏好
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

手动切换

桌面端：

  • 位置：导航栏右侧
  • 图标：太阳/月亮切换

移动端：

  • 位置：侧边菜单内
  • 操作：点击切换按钮

深色模式配色

浅色主题：

:root {
  --color-bg: 255 255 253;      /* 背景 */
  --color-text: 55 58 60;       /* 文字 */
  --color-border: 228 228 231;  /* 边框 */
}

深色主题：

[data-theme="dark"] {
  --color-bg: 0 2 18;           /* 背景 */
  --color-text: 255 255 255;    /* 文字 */
  --color-border: 63 63 70;     /* 边框 */
}

深色模式适配

所有组件都经过深色模式优化：

  • ✅ 代码块背景
  • ✅ 图片亮度
  • ✅ 图标颜色
  • ✅ 链接颜色
  • ✅ 表格样式

3. 全文搜索功能

ChangAn 主题内置强大的全文搜索功能。

搜索界面

桌面端：

  • 模态对话框
  • 居中显示
  • 缩放动画

移动端：

  • 侧边栏样式
  • 从右侧滑入
  • 全屏显示

使用方法

  1. 点击导航栏搜索图标
  2. 输入关键词
  3. 实时显示结果
  4. 点击结果跳转

搜索配置

在 hugo.toml 中配置：

[params]
  searchDebounce = 300  # 防抖时间（毫秒）

搜索索引

搜索索引自动生成在 /index.json：

[
  {
    "title": "文章标题",
    "content": "文章内容...",
    "summary": "文章摘要",
    "permalink": "/posts/article/"
  }
]

搜索技巧

  • 🔍 支持中文搜索
  • 🔍 支持英文搜索
  • 🔍 标题优先匹配
  • 🔍 内容全文匹配
  • 🔍 最多显示 10 条结果

4. 移动端菜单

菜单结构

┌─────────────────┐
│   菜单标题      │
├─────────────────┤
│ 🌓 主题切换     │
├─────────────────┤
│ 🏠 首页         │
│ 📁 归档         │
│ #️⃣ 标签         │
│ ❤️ 友链         │
│ 👻 关于         │
└─────────────────┘

动画效果

打开菜单：

  • 面板从左侧滑入
  • 链接逐项淡入
  • 交错动画效果

关闭菜单：

  • 面板滑回左侧
  • 遮罩层淡出

使用方式

  1. 点击左上角汉堡菜单图标
  2. 菜单从左侧滑出
  3. 点击菜单项跳转
  4. 点击遮罩层或关闭按钮关闭

5. 代码块增强

ChangAn 主题的代码块经过精心设计和优化。

macOS 风格装饰

┌─────────────────────────┐
│ ● ● ●    Python    [复制]│
├─────────────────────────┤
│ 代码内容...             │
│                         │
└─────────────────────────┘

装饰元素：

  • 🔴🟡🟢 三个圆形按钮（macOS 风格）
  • 🏷️ 语言标签
  • 📋 复制按钮

代码高亮

支持多种高亮主题，包括 Dracula、Monokai、Nord、Tokyo Night 等 36 种 Chroma 主题。

基础配置：

[markup.highlight]
  style = 'dracula'  # 可选：dracula, monokai, nord, tokyonight 等

推荐主题：

  • 🥇 Dracula - 现代、高对比度，深色模式首选
  • 🥈 Tokyo Night - 时尚、紫色调，日系风格
  • 🥉 Monokai - 经典、鲜艳，Sublime Text 默认
  • 🏅 Nord - 冷色调、专业，北极冰川配色
  • 🏅 Gruvbox - 复古、暖色，舒适温馨

💡 提示：想了解所有可用主题的详细对比和配置方法？请阅读： Hugo 博客写作指南（六）：Chroma 代码高亮主题完整指南

复制功能

悬停显示：

  • 鼠标悬停时显示复制按钮
  • 语言标签隐藏

点击复制：

  • 点击复制按钮
  • 按钮文字变为"已复制"
  • 2 秒后恢复

深色模式适配

/* 深色模式代码块背景 */
[data-theme="dark"] .code-block {
  background-color: rgb(30, 30, 30) !important;
}

使用示例

```python
def hello_world():
    """Hello World 示例"""
    print("Hello, World!")
    
if __name__ == "__main__":
    hello_world()
```

6. 目录导航（TOC）

自动生成

主题会自动从文章标题生成目录。

配置：

[markup.tableOfContents]
  startLevel = 2  # 从 H2 开始
  endLevel = 4    # 到 H4 结束
  ordered = false # 无序列表

目录样式

桌面端：

  • 位置：文章右侧
  • 样式：粘性定位
  • 高亮：当前阅读章节

移动端：

  • 自动隐藏
  • 节省空间

滚动监听

目录会自动高亮当前阅读的章节：

// 监听滚动位置
window.addEventListener('scroll', () => {
  // 更新目录激活状态
});

使用技巧

文章结构建议：

# 文章标题（H1 - 自动生成）

## 第一章（H2 - 目录项）

### 1.1 小节（H3 - 目录项）

#### 1.1.1 细节（H4 - 目录项）

##### 不要使用 H5（不会出现在目录中）

7. 社交分享

社交平台支持

ChangAn 主题支持多个社交平台：

平台图标配置
QQicon-qqparams.socials
微信icon-wechatparams.socials
微博icon-weiboparams.socials
GitHubicon-githubparams.socials
邮箱icon-mailparams.socials
知乎icon-zhihuparams.socials
B 站icon-bilibiliparams.socials
豆瓣icon-doubanparams.socials

配置方式

在 hugo.toml 中配置：

[[params.socials]]
  name = 'Github'
  icon = 'icon-github'
  url = 'https://github.com/yourname'

显示位置

  • 首页横幅区域
  • 关于页面
  • 移动端菜单

样式特点

  • 圆形按钮
  • 悬停效果
  • 颜色变化
  • 图标动画

8. 首页布局

首页横幅（Banner）

桌面端布局：

┌─────────────────────────────────┐
│                                 │
│    [头像]    博客标题            │
│              简介文字            │
│              [社交图标]          │
│                                 │
│         一言文字                 │
│                                 │
│           ↓ (滚动提示)          │
└─────────────────────────────────┘

特点：

  • 全屏高度（100vh）
  • 响应式布局
  • 渐变背景
  • 动画效果

首页文章列表

布局：

┌─────────────────────────────────┐
│ 侧边栏     │  文章列表          │
│ - 分类     │  - 文章 1          │
│ - 标签     │  - 文章 2          │
│            │  - 文章 3          │
└─────────────────────────────────┘

文章卡片信息：

  • 标题
  • 摘要
  • 封面图（如果有）
  • 发布日期
  • 分类/标签
  • 阅读时间
  • 阅读更多按钮

分类和标签

侧边栏分类：

  • 网格布局
  • 悬停效果
  • 计数显示

标签云：

  • 标签大小一致
  • 悬停效果
  • 标签计数

9. 文章页面

文章头部

┌─────────────────────────────────┐
│           文章标题              │
│                                 │
│  📅 日期  |  👤 作者  |  ⏱️ 阅读时间│
│                                 │
│  [分类] [标签 1] [标签 2]       │
└─────────────────────────────────┘

文章内容

样式特点：

  • 合适的行高（1.8）
  • 舒适的字间距
  • 优化的代码块
  • 美观的表格
  • 响应式图片

文章版权信息

┌─────────────────────────────────┐
│ 版权声明                        │
│                                 │
│ 作者：长安                      │
│ 链接：/posts/article/          │
│ 许可：CC BY-NC-SA 4.0          │
└─────────────────────────────────┘

文章导航

上一篇/下一篇：

┌──────────────┐ ┌──────────────┐
│ ← 上一篇     │ │     下一篇 → │
│ 文章标题     │ │ 文章标题     │
└──────────────┘ └──────────────┘

10. 归档页面

时间线样式

2026
├─ 03-04  文章标题 1
├─ 03-03  文章标题 2
└─ 03-01  文章标题 3

2025
├─ 12-31  文章标题 4
└─ 12-25  文章标题 5

特点

  • 时间线设计
  • 年份分组
  • 悬停效果
  • 圆点标记

11. 友链页面

卡片布局

┌─────────────┐ ┌─────────────┐
│ [头像] 名称  │ │ [头像] 名称  │
│ 描述文字    │ │ 描述文字    │
└─────────────┘ └─────────────┘
┌─────────────┐ ┌─────────────┐
│ [头像] 名称  │ │ [头像] 名称  │
│ 描述文字    │ │ 描述文字    │
└─────────────┘ └─────────────┘

添加友链

创建 content/links.md：

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

- name: 朋友博客
  link: https://friend.com
  avatar: /images/friend-avatar.webp
  descr: 朋友的描述

12. 性能优化

图片优化

推荐格式：

  • WebP（首选）
  • PNG（透明背景）
  • JPG（照片）

优化建议：

  • 压缩图片
  • 使用适当尺寸
  • 懒加载

CSS 优化

  • 压缩 CSS
  • 移除未使用样式
  • 关键 CSS 内联

JavaScript 优化

  • 延迟加载
  • 压缩代码
  • 事件委托

构建优化

# 使用优化参数构建
hugo --gc --minify

参数说明：

  • --gc：垃圾回收，移除未使用资源
  • --minify：压缩 HTML、CSS、JS

13. SEO 优化

Meta 标签

自动生成完整的 meta 标签：

<meta name="description" content="文章描述">
<meta name="author" content="作者名">
<meta name="keywords" content="关键词">

Open Graph

支持社交媒体分享：

<meta property="og:title" content="文章标题">
<meta property="og:description" content="文章描述">
<meta property="og:image" content="封面图">

结构化数据

自动生成 JSON-LD 结构化数据。

站点地图

自动生成 sitemap.xml。

14. 自定义技巧

自定义颜色

在 CSS 中覆盖变量：

:root {
  --color-accent: 249 85 85;  /* 强调色 */
}

自定义字体

html {
  font-family: "自定义字体", sans-serif;
}

添加自定义样式

创建 assets/css/custom.css：

/* 自定义样式 */
.my-custom-class {
  color: red;
}

自定义页脚

在 hugo.toml 中配置：

[params]
  since = '2026'
  author = '你的名字'

15. 常见问题

Q1: 如何修改主题颜色？

A: 在 CSS 文件中覆盖 CSS 变量。

Q2: 如何添加新的社交链接？

A: 在 hugo.toml 中添加 [[params.socials]] 配置。

Q3: 如何禁用深色模式？

A: 需要修改主题代码，移除主题切换按钮。

Q4: 搜索功能不工作？

A: 检查是否配置了 home = ['HTML', 'RSS', 'JSON']。

Q5: 代码块没有高亮？

A: 检查 hugo.toml 中的 markup.highlight 配置。

小结

ChangAn 主题提供了丰富的功能：

  • ✅ 响应式设计，适配所有设备
  • ✅ 深色模式，保护视力
  • ✅ 全文搜索，快速定位
  • ✅ 代码块增强，美观实用
  • ✅ 目录导航，便于阅读
  • ✅ 社交分享，连接世界
  • ✅ 性能优化，快速加载
  • ✅ SEO 友好，易于索引

希望这些功能能让你的博客更加出色！

上一篇： Hugo 博客写作指南（三）：Markdown 基础用法详解

系列文章：

相关资源：

版权声明

本文作者：长安

本文链接：https://changan.icecome.com/posts/hugo-writing-guide-04-theme-features/