教程 on 我的博客

快速开始：使用 Template 一键部署博客

Thu, 09 Apr 2026 00:00:00 +0000

欢迎使用 Hugo Theme Stack Starter

这是一个基于 Hugo Theme Stack v4 的开箱即用博客模板，内置美化增强、双语支持和 GitHub Actions 自动部署，无需本地安装任何工具就能快速上手。

方式一：GitHub Template 一键部署（推荐）

这是最简单的方式，全程在浏览器中完成。

第 1 步：使用模板创建你的仓库

打开本项目 GitHub 页面
点击右上角绿色按钮 “Use this template” → “Create a new repository”
填写仓库名称（如 my-blog），选择 Public（GitHub Pages 免费版需要公开仓库）
点击 “Create repository”

第 2 步：开启 GitHub Pages

进入你新建的仓库，点击 Settings → Pages
在 “Source” 下选择 “GitHub Actions”
保存

第 3 步：修改配置

在 GitHub 网页上直接编辑 config/_default/config.toml：

# 改为你的 GitHub Pages 地址
baseurl = "https://你的用户名.github.io/仓库名/"
title   = "我的博客"

第 4 步：推送触发自动部署

任何一次代码提交都会触发 GitHub Actions 自动构建并部署。稍等 1-2 分钟后，访问你的 GitHub Pages 地址即可看到博客！

方式二：本地开发

如果你想在本地预览和编写：

安装 Hugo（扩展版）

# macOS
brew install hugo

# Windows（使用 Scoop）
scoop install hugo-extended

# Linux（apt）
sudo apt install hugo

验证安装（需要 Extended 版本）：

hugo version
# 输出应包含 extended

克隆并运行

git clone https://github.com/你的用户名/my-blog.git
cd my-blog
hugo server

访问 http://localhost:1313 即可预览。

基本配置说明

所有配置文件在 config/_default/ 目录下：

文件	作用
`config.toml`	站点标题、域名、语言
`languages.toml`	多语言设置（中/英）
`params.toml`	主题参数（评论、首页布局等）
`params.zh.toml`	中文专属参数（头像、副标题）
`menu.zh.toml`	中文导航菜单

必须修改的配置

1. 站点标题和域名 (config.toml)：

baseurl = "https://你的域名/"
title   = "我的博客"

2. 你的头像和介绍 (params.zh.toml)：

[sidebar]
    subtitle = "你的个性签名"
    avatar   = "img/avatar.jpg"  # 替换 assets/img/avatar.jpg

3. 运行时间 (params.toml)：

[footer]
    launchDate = "2024-01-01"  # 博客建站日期

目录结构

my-blog/
├── .github/workflows/    # GitHub Actions 自动部署（无需修改）
├── assets/scss/          # 样式定制
│   ├── custom.scss       # 颜色、全局样式
│   └── partials/custom-components/  # 组件样式
├── config/_default/      # 所有配置文件
├── content/
│   └── post/             # 博客文章（在这里写作）
├── layouts/              # 自定义布局和 Shortcodes
└── static/               # 静态资源（图片等）

下一步

📖 主题美化介绍 — 了解本模板做了哪些改动
💬 配置 Waline 评论 — 为博客添加评论功能
✏️ 开始写第一篇博客 — 学习 Markdown 和多语言写作

祝你写作愉快！🎉

主题美化介绍：我做了哪些改动

Fri, 10 Apr 2026 00:00:00 +0000

本模板基于 Hugo Theme Stack v4 开发，在保持原有功能完整性的基础上，进行了一系列视觉和交互上的美化。

所有修改都通过 Hugo 的覆盖机制实现（在 assets/ 和 layouts/ 中创建同名文件），不修改主题源代码，方便随时升级主题版本。

1. 全局配色系统

重新定义了整套颜色变量，采用深蓝 + 暖米白的配色方案：

亮色模式：

背景色：暖米白 #f8f7f2（比纯白更护眼）
主色调：深海蓝 #1B365D
卡片背景：#fdfdfb（微暖的白）

暗色模式：

背景色：#101214（深灰黑）
卡片背景：#1c2128（GitHub 暗色风格）
暗色模式下图片自动降亮，hover 后恢复

修改位置：assets/scss/custom.scss 中的 :root 变量。

2. Mac 风格代码块

原始主题的代码块较为简洁，本模板对其进行了全面美化：

顶部装饰栏

为每个代码块添加了 macOS 风格的三色圆点装饰（红、黄、绿），模拟终端窗口外观。

复制按钮重设计

从不易发现的图标按钮改为悬浮在标题栏右侧的文字按钮
亮色模式：毛玻璃风格（backdrop-filter: blur）
暗色模式：深色半透明背景
点击后按钮文字变为"✓ Copied!"

自动折叠长代码块

超过 600px 高度的代码块会自动折叠，底部显示"展开代码"按钮：

折叠时底部有渐变遮罩
点击展开后，按钮变为"收起代码"
收起时自动滚动回代码块顶部，防止页面位置混乱

滚动条美化

代码块的横向滚动条默认透明，鼠标悬停时才显现，保持界面整洁。

3. 首页双栏网格布局

在 PC 端（宽度 ≥ 1024px），首页文章列表变为 2 列网格展示：

每篇文章以卡片形式呈现，包含封面图、标题、摘要和元信息
卡片 hover 时有轻微上浮动画
文章标题和摘要超出时自动截断（2 行）
移动端自动恢复为单列列表

开启方式：在 params.toml 中设置：

[homepage]
    grid = true

4. 移动端导航重设计

原主题的移动端导航较基础，本模板完全重写了移动端体验：

顶部悬浮导航栏

固定在顶部（sticky），随页面滚动保持可见
左侧：头像 + 站点名称（点击回首页）
右侧：明暗切换、语言切换、搜索、汉堡菜单

汉堡菜单

点击展开侧边菜单，带有淡入动画
菜单展开时顶栏标题淡出，避免遮挡
当前页面菜单项高亮显示
屏幕宽度恢复时自动关闭

搜索框

桌面端侧边栏的搜索框经过重新设计，与卡片样式一致。

5. 博客统计页（Stats）

新增了一个功能丰富的 /stats/ 统计页，包含：

摘要卡片：总文章数、总字数、运行天数（动画数字滚动）
分类分布：带进度条的分类列表，可点击进入分类页
热门标签：标签云展示（前 30 个标签）
写作习惯：按周几和时段分析发布习惯（基于 Git 提交时间）
年度热力图：GitHub 风格的贡献热力图（近一年的发布记录）

配置页面入口：在 content/stats/index.zh.md 中设置 layout: stats。

Footer 新增博客运行时长展示，会计算从建站日期到当前的天数、小时、分钟。

点击可跳转到 Stats 统计页。

配置建站日期：

[footer]
    launchDate = "2024-09-09"

7. 自定义 Shortcodes

时间线（Timeline）

适合展示成长经历、技术栈演进等内容：

{{< timeline >}}
{{< timeline-item date="2024-01" >}}
开始学习 Hugo 建站
{{< /timeline-item >}}
{{< timeline-item date="2024-06" >}}
博客正式上线
{{< /timeline-item >}}
{{< /timeline >}}

标题分割线（Title）

适合日记、健身记录等需要分段标题的内容：

{{< title "晨练记录" "green" >}}

支持颜色：red、orange、yellow、green、teal、blue、indigo、purple、pink、gray

如何自定义颜色

编辑 assets/scss/custom.scss，修改 :root 中的变量：

:root {
    --accent-color: #1B365D;        /* 主色调（按钮、链接等） */
    --body-background: #f8f7f2;     /* 页面背景 */
    --card-background: #fdfdfb;     /* 卡片背景 */
}

保存后 Hugo 会自动重新编译，浏览器实时刷新。

配置 Waline 评论区

Sat, 11 Apr 2026 00:00:00 +0000

Waline 是一款安全、简洁的评论系统，支持 Markdown，免费部署，无需用户注册即可评论。

本模板已内置 Waline 集成，只需部署好服务端并填写一行配置即可启用。

第一步：部署 Waline 服务端

请参考 Waline 官方快速上手文档 完成服务端的部署：

👉 https://waline.js.org/guide/get-started/

官方文档提供了在 Vercel 上的免费一键部署方案，整个过程大约 5 分钟。

部署完成后，你会获得一个 Waline 服务地址，类似：

https://your-waline-project.vercel.app/ （默认 Vercel 域名）
或者你绑定的自定义域名

记录这个地址，下一步会用到。

第二步：在本模板中配置

编辑 config/_default/params.toml，填入你的服务地址：

[comments]
    enabled  = true
    provider = "waline"

[comments.waline]
    serverURL = "https://your-waline-project.vercel.app/"  # ← 填入你的地址
    pageview  = true       # 同时开启文章阅读量统计

    # 可选：自定义表情包（默认微博表情）
    emoji = ["https://unpkg.com/@waline/emojis@1.0.1/weibo"]

    # 评论必填字段
    requiredMeta = ["name"]

    [comments.waline.locale]
        admin = "Admin"    # 管理员标识

保存后重启 hugo server，文章页面底部会出现评论区。

功能说明

阅读量统计

设置 pageview = true 后，文章头部会自动显示阅读量（需要 Waline 服务端支持）。

评论管理后台

访问 https://your-waline-project.vercel.app/ui/ 进入管理界面，第一个注册的账号自动成为管理员，可以审核、删除评论。

邮件通知

有人回复时可以通过邮件通知博主，需要在 Vercel 环境变量中配置 SMTP 信息，详见官方文档 - 评论通知。

常见问题

评论区不显示？
检查 serverURL 末尾是否有斜杠 /，以及 Vercel 服务是否正常运行（直接访问 serverURL 应该能看到 Waline 欢迎页）。

Cookie 提示遮住评论区？
如果开启了 Cookie 同意功能，用户需先接受「功能性 Cookie」后评论区才会显示。可以在 params.toml 中关闭 Cookie 提示，或引导用户接受。

开始写博客：Markdown 入门与多语言写作

Sun, 12 Apr 2026 00:00:00 +0000

创建第一篇文章

方式一：使用命令创建（推荐）

# 创建中文文章
hugo new content post/my-first-post/index.zh.md

# 同时创建对应的英文版
hugo new content post/my-first-post/index.en.md

Hugo 会根据 archetypes/default.md 模板自动填充初始内容。

方式二：手动创建

在 content/post/ 下新建一个文件夹，然后在其中创建 index.zh.md：

content/
└── post/
    └── my-first-post/       ← 文章目录（名称即 URL）
        ├── index.zh.md      ← 中文正文
        ├── index.en.md      ← 英文正文（可选）
        └── cover.jpg        ← 封面图（可选）

Front Matter 说明

每篇文章顶部的 --- 之间的部分叫 Front Matter，用于定义文章元数据：

---
title: "文章标题"
description: "文章摘要，显示在列表页和 SEO 描述中"
date: 2026-04-12          # 发布日期
lastmod: 2026-04-23       # 最后修改日期（可选）
draft: false              # true = 草稿，不会发布
categories:
    - Technology          # 分类（建议只选一个）
tags:
    - Hugo                # 标签（可多个）
    - Markdown
image: cover.jpg          # 封面图（相对于文章目录）
---

提示：date 决定文章在列表中的排序顺序，未来日期的文章在本地预览时需要 hugo server -F 才能显示。

Markdown 基本语法

标题

## 二级标题
### 三级标题
#### 四级标题

文章正文中不使用一级标题（# H1），因为文章的 title 字段已经是 H1。

文字样式

**粗体**          加粗
*斜体*            斜体
~~删除线~~        删除线
`行内代码`        代码

效果：粗体、斜体、~~删除线~~、行内代码

链接和图片

[链接文字](https://example.com)
[内部链接](/post/hello-world/)

![图片描述](image.jpg)          # 相对路径（同目录下）
![图片描述](/img/photo.jpg)     # 绝对路径（static 目录下）

列表

- 无序列表项
- 第二项
  - 嵌套项

1. 有序列表
2. 第二项
3. 第三项

代码块

```python
def hello():
    print("Hello, World!")
```

支持语言高亮：python、go、javascript、bash、toml、yaml、markdown 等。

引用块

> 这是一段引用内容
> 可以多行

效果：

这是一段引用内容

表格

| 列1   | 列2   | 列3   |
|-------|-------|-------|
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |

分割线

---

多语言写作

本模板默认开启中英双语支持。

文件命名规则

文件名	对应语言
`index.zh.md`	中文
`index.en.md`	英文

两个文件放在同一目录下，Hugo 会自动关联为同一篇文章的不同语言版本。

只写中文版

如果你不想写英文版，只创建 index.zh.md 即可。

添加英文版

在同一目录下创建 index.en.md
翻译文章内容（Front Matter 的 title、description 也要翻译）
图片等资源两个语言版本共享，无需复制

示例：

index.zh.md：

---
title: "我的第一篇文章"
description: "这是我的第一篇博客文章"
date: 2026-04-12
---
内容...

index.en.md：

---
title: "My First Post"
description: "This is my first blog post"
date: 2026-04-12
---
Content...

插入图片

使用文章目录下的图片（推荐）

将图片放在文章目录下，然后用相对路径引用：

content/post/my-post/
├── index.zh.md
├── cover.jpg       ← 封面图
└── screenshot.png  ← 文章内图片

在 Markdown 中：

![截图说明](screenshot.png)

封面图在 Front Matter 中指定：

image: cover.jpg

使用 static 目录下的图片

将图片放在 static/img/ 下，用绝对路径引用：

![图片](img/photo.jpg)

使用本模板的 Shortcodes

标题分割线

适合日记类文章的段落分隔：

{{< title "早晨跑步" "green" >}}

今天跑了 5 公里，状态不错。

{{< title "下午阅读" "blue" >}}

读了两章《深度工作》。

时间线

适合展示经历、成长轨迹：

{{< timeline >}}
{{< timeline-item date="2024-01" >}}
开始学习编程
{{< /timeline-item >}}
{{< timeline-item date="2024-06" >}}
完成第一个项目
{{< /timeline-item >}}
{{< /timeline >}}

写作建议

文章目录名即是 URL，建议用英文小写加连字符，如 my-first-post
封面图建议尺寸 1200×630px，这也是社交分享时的最佳尺寸
description 不超过 160 个字符，对 SEO 友好
本地预览时使用 hugo server -D 可以看到草稿文章

祝写作顺畅！✍️

Shortcodes 使用指南

Tue, 14 Apr 2026 00:00:00 +0000

Hugo Shortcodes 是在 Markdown 中嵌入特殊组件的方式。本文展示所有自定义 Shortcode 的实际渲染效果。

标题分割线 (title)

适合日记、健身记录、学习笔记等需要分段小标题的内容。

用法：

{{< title "标题文字" "颜色" >}}

实际效果——不同颜色展示：

绿色标题

这是绿色分割线下的内容，适合运动、健康类记录。

蓝色标题

这是蓝色分割线下的内容，适合技术、学习类记录。

橙色标题

这是橙色分割线下的内容，适合创意、设计类记录。

紫色标题

这是紫色分割线下的内容，适合日记、随笔类记录。

自定义颜色 #E91E63

也可以直接使用十六进制颜色值。

时间线 (timeline)

适合展示个人经历、项目里程碑、技术成长轨迹等。

用法：

{{< timeline >}}
{{< timeline-item date="2024-01" >}}
内容...
{{< /timeline-item >}}
{{< /timeline >}}

实际效果：

2024-01

开始学习 Hugo，了解静态博客的优势与生态。
2024-06

博客正式上线，发布第一篇技术文章，收获了第一批读者。
2025-01

引入 Waline 评论系统，与读者建立互动，评论区逐渐活跃。
2025-09

对博客主题进行美化改造，添加 Mac 风格代码块、Stats 统计页等功能。

时间线内容支持完整 Markdown，如粗体、行内代码、链接等。

代码块功能（主题增强）

代码块本身不是 Shortcode，但本模板对其进行了增强：

复制按钮

每个代码块右上角都有复制按钮（在代码块的 macOS 顶栏内）：

// 点击右上角的复制按钮试试
function greet(name) {
    return `Hello, ${name}!`;
}
console.log(greet("Hugo"));

自动折叠长代码

超过 600px 高度的代码块会自动折叠，底部出现「展开代码」按钮。这是一段用于测试折叠功能的长代码：

# 这段代码足够长，会触发自动折叠
import os
import sys
import json
import time
import datetime

class BlogStats:
    def __init__(self, posts_dir: str):
        self.posts_dir = posts_dir
        self.posts = []
        self.total_words = 0
        self.categories = {}
        self.tags = {}

    def scan_posts(self):
        """扫描所有文章目录"""
        for root, dirs, files in os.walk(self.posts_dir):
            for file in files:
                if file.endswith('.md'):
                    filepath = os.path.join(root, file)
                    self.parse_post(filepath)

    def parse_post(self, filepath: str):
        """解析单篇文章的 front matter"""
        with open(filepath, 'r', encoding='utf-8') as f:
            content = f.read()

        # 提取 front matter
        if content.startswith('---'):
            end = content.find('---', 3)
            if end > 0:
                front_matter = content[3:end].strip()
                body = content[end+3:].strip()
                self.total_words += len(body.split())
                self.parse_front_matter(front_matter)

    def parse_front_matter(self, front_matter: str):
        """解析 YAML front matter"""
        for line in front_matter.split('\n'):
            if line.startswith('categories:'):
                pass  # 简化处理
            elif line.startswith('tags:'):
                pass  # 简化处理
            elif line.startswith('    - '):
                tag = line.strip().lstrip('- ')
                self.tags[tag] = self.tags.get(tag, 0) + 1

    def get_report(self) -> dict:
        """生成统计报告"""
        return {
            'total_posts': len(self.posts),
            'total_words': self.total_words,
            'categories': sorted(
                self.categories.items(),
                key=lambda x: x[1],
                reverse=True
            ),
            'tags': sorted(
                self.tags.items(),
                key=lambda x: x[1],
                reverse=True
            )[:20],
        }

if __name__ == '__main__':
    stats = BlogStats('./content/post')
    stats.scan_posts()
    report = stats.get_report()
    print(json.dumps(report, ensure_ascii=False, indent=2))

如何创建自己的 Shortcode

在 layouts/shortcodes/ 下新建 HTML 文件即可。例如创建 badge.html：

<!-- layouts/shortcodes/badge.html -->
<span style="
  display: inline-block;
  padding: 2px 10px;
  border-radius: 4px;
  font-size: 12px;
  font-weight: 600;
  background: {{ .Get 1 | default `var(--accent-color)` }};
  color: {{ .Get 2 | default `#fff` }};
">{{ .Get 0 }}</span>

使用：{{< badge "New" "#059669" >}}

样式自定义指南

Mon, 13 Apr 2026 00:00:00 +0000

本模板的样式系统基于 SCSS，所有自定义样式都在 assets/scss/ 目录下，不需要修改主题源文件。

修改主题色

打开 assets/scss/custom.scss，修改 :root 中的 CSS 变量：

:root {
    /* 亮色模式 */
    --accent-color: #1B365D;           /* 主色调：按钮、链接、高亮 */
    --accent-color-darker: #202A44;    /* 主色调深色版：hover 状态 */
    --accent-color-text: #FFF;         /* 主色调上的文字颜色 */
    --body-background: #f8f7f2;        /* 页面背景 */
    --card-background: #fdfdfb;        /* 卡片背景 */
    --body-text-color: #2D3748;        /* 正文文字颜色 */

    &[data-scheme="dark"] {
        /* 暗色模式覆盖 */
        --body-background: #101214;
        --card-background: #1c2128;
        /* ... */
    }
}

保存后 Hugo 自动重新编译，浏览器立即刷新。

常用配色方案参考

紫色系：

--accent-color: #7C3AED;
--accent-color-darker: #6D28D9;

绿色系：

--accent-color: #059669;
--accent-color-darker: #047857;

橙色系：

--accent-color: #EA580C;
--accent-color-darker: #C2410C;

修改代码块样式

代码块相关样式在 assets/scss/partials/custom-components/_code.scss。

关闭 Mac 风格顶栏

如果不喜欢 macOS 三色圆点，注释掉以下代码：

/* 注释掉这个 before 伪元素即可关闭顶栏 */
/*
.article-content .highlight:before {
    ...
}
*/

修改折叠阈值

在 _code.scss 和 layouts/_partials/footer/custom.html 中，将 600 改为你想要的像素值：

/* _code.scss */
&.collapsed {
    max-height: 400px;  /* 改为你想要的高度 */
}

/* custom.html 中的 JS */
const MAX_HEIGHT = 400;  /* 与 CSS 保持一致 */

添加自定义字体

在 assets/scss/custom.scss 中添加 Google Fonts 并设置字体：

/* 引入字体 */
@import url('https://fonts.googleapis.com/css2?family=Noto+Serif+SC:wght@400;700&display=swap');

/* 应用到正文 */
body {
    font-family: 'Noto Serif SC', serif;
}

/* 应用到文章内容 */
.article-content {
    font-family: 'Noto Serif SC', serif;
    line-height: 1.9;
}

注意：国内访问 Google Fonts 可能较慢，可以考虑使用 jsDelivr 加速或自托管字体。

组件样式文件说明

文件	作用
`custom.scss`	全局变量、TOC 滚动条
`_code.scss`	代码块全部样式
`_footer.scss`	Footer 运行时长按钮
`_homepage-grid.scss`	首页双栏网格
`_mobile-menu.scss`	移动端顶部导航栏
`_timeline.scss`	时间线 Shortcode 样式
`_title.scss`	标题分割线 Shortcode 样式

每个文件职责单一，可以独立修改，不互相影响。

关闭首页网格布局

如果偏好传统的单列列表，编辑 params.toml：

[homepage]
    grid = false

覆盖主题布局

如果需要修改主题的其他布局文件，在 layouts/ 目录下创建同名文件即可覆盖：

例如，要修改文章页布局，在 hugo-theme-stack-v4/layouts/single.html 中查看原文件，然后复制到 layouts/single.html 并修改。

Hugo 的覆盖机制会优先使用项目根目录下的同名文件，主题文件作为后备。