Hugo on 一条狗的传说

Hugo｜从零开始Hugo建站 5

Wed, 16 Sep 2026 00:00:00 +0000

📝 写在前面

本篇是第五部分，主要学习如何创建第一篇博客文章，掌握 Markdown 基本语法，以及如何使用hugo主题中的特殊用例。

第一节：markdown基础语法

Markdown 基本语法 | Markdown 教程

第二节：markdown进阶语法

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

Markdown 语法指南

第三节：Markdown 带提示的引用（Callout）语法实现指南

💡 提示

本文介绍 GitHub 风格 Callout（提示框）语法，以及 Hugo Stack 主题中的使用方法。

1.什么是 Callout

你看到的"带提示的引用"是通过 > [!类型] 的 Callout（提示框）语法实现的。

这是 GitHub 风格的 Callout 语法，Hugo Stack 主题对它做了原生支持。写法是在普通引用块（>）的第一行，紧跟一个方括号加感叹号加类型名的标记。

2.基础语法

> [!NOTE]
> 突出显示用户在快速浏览时也应注意的信息。

> [!TIP]
> 可选信息，帮助用户更顺利地完成任务。

> [!IMPORTANT]
> 用户成功所必需的关键信息。

> [!WARNING]
> 由于潜在风险而需要用户立即关注的关键内容。

> [!CAUTION]
> 某个操作可能带来的负面后果。

3.五种内置类型

标记	显示效果	图标
`[!NOTE]`	备注	📝
`[!TIP]`	提示	💡
`[!IMPORTANT]`	重要	📌
`[!WARNING]`	警告	⚠️
`[!CAUTION]`	注意	🚨

标记本身不区分大小写（[!note] 也可以），标题文字和图标、配色是由主题在渲染时自动套用的，不需要自己写。

4.自定义标题

如果不想用默认标题，在方括号标记后面直接加空格再写标题文本即可，也就是页面上演示的最后一种用法：

> [!NOTE] 自定义标题
> 如果你想使用自定义标题，可以在方括号后面添加标题文本，如上所示。

5.内容部分照常写 Markdown

Callout 正文里可以继续用普通 Markdown 语法——加粗、行内代码、链接、列表等都没问题，只需保证每行都以 > 开头（或至少第一行带标记）。

例如：

> [!TIP] 小技巧
> 支持 **加粗**、`行内代码`、[链接](https://example.com) 等：
> - 列表项一
> - 列表项二

6.兼容性说明

需要注意的是，这并非 Markdown 核心规范的一部分，而是各家平台的扩展语法：

GitHub：原生支持上面这套 [!NOTE] 写法；
Hugo 的 Stack 主题：兼容该语法；
其他渲染器：某些静态博客主题或编辑器里可能不识别，会退化成普通引用块显示。

7.效果预览

📝 备注

突出显示用户在快速浏览时也应注意的信息。

💡 提示

可选信息，帮助用户更顺利地完成任务。

📌 重要

用户成功所必需的关键信息。

⚠️ 警告

由于潜在风险而需要用户立即关注的关键内容。

🚨 注意

某个操作可能带来的负面后果。

Hugo｜从零开始Hugo建站 4

Tue, 15 Sep 2026 00:00:00 +0000

📝 写在前面

本篇是第四部分，主要讲搭建hugo个人博客的评论区。

下一篇会讲如何创建第一篇博客文章，掌握 Markdown 基本语法，以及如何使用hugo主题中的特殊用例。

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

第一步：部署 Waline 服务端

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

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

Hugo｜从零开始Hugo建站 3

Tue, 02 Mar 2021 00:00:00 +0000

📝 写在前面

本篇是第三部分，主要讲 Hugo 的完整配置以及如何使用 GitHub Action 实现自动推送。

下一篇会讲如何搭建hugo个人博客的评论区

Hugo 站点文件配置

Hugo 站点文件夹内容

Hugo Stack 主题配置

Hugo Stack 主题快速上手

我使用的主题是基于 Stack 改版的模板，由 liu-houliang/hugo-stack-starter 调整而来，文末会附上链接。

基础配置

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

config/_default/
├── config.toml # 站点标题、域名 ← 必须修改
├── languages.toml # 多语言设置
├── params.toml # 主题参数（评论、首页布局）
├── params.zh.toml # 中文专属参数（头像、副标题）← 建议修改
├── params.en.toml # 英文专属参数
├── menu.zh.toml # 中文导航菜单
└── menu.en.toml # 英文导航菜单

在 GitHub Pages 上托管

将 Hugo 站点部署为 GitHub Pages 项目（或个人/组织站点），并通过 GitHub Actions 实现自动化构建与部署。

每次手动构建再推送很繁琐，可以利用 GitHub Actions 实现：推送代码 → 自动构建部署。

Hugo 官方 GitHub Actions 模板

在 Hugo 项目根目录创建 .github/workflows/hugo.yaml，使用官方推荐的 GitHub Pages Actions 方式，推送到 main 分支即可自动构建并部署。以下是完整的配置流程和可直接使用的 workflow 文件。

一、准备工作

确保 Hugo 项目已推送到 GitHub 仓库（注意：不要把 public/ 目录提交进仓库，Hugo 构建时会自动生成，建议在 .gitignore 中添加 public/ 和 resources/）。
修改 hugo.toml 中的 baseURL：
- 用户主页站点（仓库名为 用户名.github.io）：baseURL = "https://<用户名>.github.io/"
- 普通项目站点：baseURL = "https://<用户名>.github.io/<仓库名>/"
如果主题以 Git Submodule 方式引入，确认 Submodule 已正确提交（git submodule add <主题地址> themes/<主题名>）。

二、创建 Workflow 文件

在项目根目录创建 .github/workflows/hugo.yaml，以下是 Hugo 官方文档提供的模板：

# 用于构建和部署Hugo网站到GitHub Pages的示例工作流程
name: 发布Hugo网站到Pages

on:
 # 在目标为默认分支的推送上运行
 push:
 branches:
 - main

 # 允许手动从Actions标签运行此工作流程
 workflow_dispatch:

# 设置GITHUB_TOKEN的权限，以允许部署到GitHub Pages
permissions:
 contents: read
 pages: write
 id-token: write

# 仅允许一个并发部署，跳过在进行中的运行与最新排队的运行之间排队的运行。
# 但不取消进行中的运行，以确保这些生产部署能够完成。
concurrency:
 group: "pages"
 cancel-in-progress: false

# 默认使用bash
defaults:
 run:
 shell: bash

jobs:
 # 构建作业
 build:
 runs-on: ubuntu-latest
 env:
 HUGO_VERSION: 0.120.2
 steps:
 - name: 安装Hugo CLI
 run: |
 wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
 && sudo dpkg -i ${{ runner.temp }}/hugo.deb 
 - name: 安装Dart Sass
 run: sudo snap install dart-sass
 - name: 检出
 uses: actions/checkout@v4
 with:
 submodules: recursive
 fetch-depth: 0
 - name: 设置Pages
 id: pages
 uses: actions/configure-pages@v3
 - name: 安装Node.js依赖
 run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
 - name: 使用Hugo构建
 env:
 HUGO_ENVIRONMENT: production
 HUGO_ENV: production
 run: |
 hugo \
 --gc \
 --minify \
 --baseURL "${{ steps.pages.outputs.base_url }}/" 
 - name: 上传构建产物
 uses: actions/upload-pages-artifact@v2
 with:
 path: ./public

 # 部署作业
 deploy:
 environment:
 name: github-pages
 url: ${{ steps.deployment.outputs.page_url }}
 runs-on: ubuntu-latest
 needs: build
 steps:
 - name: 部署到GitHub Pages
 id: deployment
 uses: actions/deploy-pages@v2

几个关键点说明

submodules: recursive + fetch-depth: 0：拉取主题子模块和完整 Git 历史（确保 .GitInfo、.Lastmod 正常工作）。
HUGO_ENVIRONMENT: production：让主题的 GA 统计等生产环境配置生效。
--baseURL "${{ steps.pages.outputs.base_url }}/"：自动获取 Pages 地址，无需手动写死 baseURL。
HUGO_VERSION：建议改为本地 hugo version 输出的版本号，避免本地与 CI 构建结果不一致。

参考资料

liu-houliang 的 hugo-stack-starter在线预览 (Live Demo)

Hugo｜从零开始Hugo建站 2

Mon, 01 Mar 2021 00:00:00 +0000

📝 写在前面

本篇是第二部分，主要讲如何用 Hugo ，从 0 到 1 完成一个静态博客：通过简单配置自定义博客界面，并把站点免费部署到 GitHub Pages。

下一篇会讲 Hugo 的完整配置以及如何使用 GitHub Action 实现自动推送。

环境准备

安装 Git

前往 Git 官网下载安装：git-scm.com
全部默认选项安装即可

安装 Hugo（Extended 版本）

前往 Hugo GitHub Releases 页面：Hugo Releases
选择 extended 版本（带 extended 字样），Stack 主题需要 extended 版本的 SCSS 编译支持

不管在哪种系统中安装 Hugo，最后都可以使用以下命令查看是否安装成功：

>>> hugo version
Hugo Static Site Generator v0.68.3-157669A0 linux/amd64 BuildDate: 2020-03-24T12:05:34Z

本文编写时使用的操作系统Ubuntu 版本为wsl版24.04，Hugo 版本为 v0.165.0，Stack 主题版本为 v4。

创建 Hugo 站点

1. 初始化项目

使用 Hugo 创建博客项目：

# 创建新站点
hugo new site myblog # 博客项目的名字为 myblog

# 进入站点目录
cd myblog

生成的目录结构：

myblog/
├── archetypes/ # 文章模板
├── assets/ # 静态资源（图片、CSS、JS）
├── content/ # 博客内容（文章）
├── data/ # 数据文件
├── i18n/ # 多语言
├── layouts/ # 布局模板
├── public/ # 构建输出（hugo 命令生成）
├── static/ # 静态文件（直接复制到 public）
├── themes/ # 主题
└── hugo.toml # 站点配置

2. 安装主题

cd themes
git clone git@github.com:CaiJimmy/hugo-theme-stack.git

注意：hugo-theme-stack 对 Hugo 版本有要求，请确保版本兼容。

安装完成后，主题目录结构如下：

myblog/themes/
└── hugo-theme-stack-4.0.x/ # 带版本号的文件夹

3. 配置主题（关键步骤）

⚠️ 版本差异：这一步最容易出错。新版 Stack（v4.x）和旧版（v3.x）的文件结构完全不同：

对比项	旧版 Stack（v3.x）	新版 Stack（v4.x）
样例目录名	`exampleSite/`	`demo/`
配置文件	单个 `hugo.yaml`	多个 `.toml` 文件在 `config/_default/`
主题引用	`theme: hugo-theme-stack`	`[[module.imports]]`（Hugo Modules 方式）

新版（v4.x）操作步骤

Step 1：复制配置文件

将主题目录下的 config/_default/ 文件夹复制到博客根目录（myblog），其中包含 6 个配置文件：

文件	作用
`hugo.toml`	基础配置（baseURL、title、分页、永久链接等）
`languages.toml`	多语言配置
`markup.toml`	Markdown 渲染配置（代码高亮、目录等）
`menu.toml`	菜单配置（导航栏、社交链接）
`params.toml`	主题参数（侧边栏、评论、widgets 等）
`related.toml`	相关内容推荐配置

同时，将主题目录下的 demo/ 文件夹中的内容复制到博客根目录（myblog）。

Step 2：修改主题引用方式

打开 config/_default/hugo.toml，找到以下内容：

[[module.imports]]
 path = "github.com/CaiJimmy/hugo-theme-stack/v3"

将其替换为传统引用方式（无需 Go 环境和 Hugo Modules，更简单）：

theme = "hugo-theme-stack-4.0.2"

修改后，删除博客根目录下的原 hugo.toml 文件（避免配置冲突）。

旧版（v3.x）操作步骤可参考文末的资料链接。本篇内容编写时参考了相关资料，由于本博客之前由 v3 版本搭建，此次改为 v4 也花费了不少功夫。

4.启动 Hugo 博客服务

使用以下命令启动本地服务：

>>> hugo server
 | EN 
-------------------+-----
 Pages | 29 
 Paginator pages | 0 
 Non-page files | 0 
 Static files | 1 
 Processed images | 0 
 Aliases | 12 
 Sitemaps | 1 
 Cleaned | 0 

Built in 60 ms
Watching for changes in /home/wp/t/myblog/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /home/wp/t/myblog/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

5. 推送本地博客到远端（GitHub Pages）

将生成的 public/ 目录作为独立仓库推送到 GitHub：

cd public
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/你的用户名/你的仓库名.git
git push -u origin main

后续可通过 GitHub Action 实现推送博客源文件后自动构建并部署，将在下一篇中介绍。

附：常用 Linux 命令

# 查看 Hugo 安装路径
which hugo

# 查看当前目录路径
pwd

# 查看命令历史
history

wsl GUI GNOME

资料参考

Hugo + Stack + GitHub Pages 博客搭建指南

Hugo｜从零开始Hugo建站 1

Sun, 28 Feb 2021 00:00:00 +0000

📝 写在前面

从一开始看到各路技术大牛的个人博客，开始萌发起了建站的想法。我不擅长写技术性博客文章（~~本文怕不是我第一篇也是最后一篇技术博客~~），只是粗略记录一下我建站的过程。如果你在对hugo博客建立的任何地方有问题，希望这篇可以帮助到你👌。

这个系列记录我从零搭建 Hugo 静态博客的过程。本篇是第一部分，主要讲建站前的准备工作：Git 的安装、本地基本操作、本地与远程仓库的连接，以及一些进阶技巧。如果你已经熟悉 Git，可以直接跳到下一篇。

下一篇会讲如何用 Hugo ，从 0 到 1 完成一个静态博客：通过简单配置自定义博客界面，并把站点免费部署到 GitHub Pages。

一、Git 入门：本地环境配置

镜像加速（推荐，最省事）如果你git下载慢，不想折腾代理，直接在原地址前加一个代理前缀即可

git config --global url."https://gh-proxy.com/https://github.com/".insteadOf "https://github.com/"

1. 安装与检查

git --version # 查看版本号
git --help # 查看帮助文档

2. 配置用户信息

git config --list # 查看所有配置
git config --list --show-origin # 查看所有配置及其所在文件

接着配置用户名和邮箱：

git config --global user.name "yourname" # 全局配置用户名
git config --global user.email "youremail@example.com" # 全局配置邮箱

也可以单独查看用户配置：

git config user.name # 查看用户名
git config user.email # 查看邮箱

3. 常用基础命令

以下是最基本的 Git 操作，全部在本地完成，不涉及远程仓库：

命令	作用
`git status`	查看仓库状态
`git init`	创建空仓库或重新初始化已有仓库
`git add`	把文件添加到暂存区
`git commit`	提交改动到仓库
`git log`	打印提交日志
`git branch`	查看、添加、删除分支
`git checkout`	切换分支、标签
`git merge`	合并分支
`git tag`	新建、查看标签

二、连接本地与远程仓库

1. 配置 SSH 密钥

mkdir .ssh # 创建 .ssh 目录（如已存在可跳过）
ssh-keygen -t rsa -C "youremail@example.com" # 生成 SSH 密钥

生成后，把公钥添加到 GitHub 的 Settings 中。

常见报错：fatal: Could not read from remote repository.

解决步骤

一般是 SSH 配置有问题，可按以下步骤排查：

重新生成密钥：ssh-keygen -t rsa -C "youremail@example.com"

将密钥添加到 ssh-agent：ssh-add ~/.ssh/id_rsa

将公钥添加到你的 GitHub 账户

用 ssh -T git@github.com 验证是否成功

2. 克隆远程仓库

git clone https://github.com/project/repo.git

3. 推送与拉取

git push：把本地代码推送到远程仓库
git pull：把远程仓库的最新代码拉到本地合并

git push origin main # 把本地代码推送到远程 main 分支
git pull origin main # 把远程最新代码更新到本地
#这一变化始于2020年10月，GitHub为了推动更具包容性的术语，将新仓库的默认分支名称从传统的 master 更改为 main‌

本地推送远程库

cd public
git init 
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/你的名字/你的仓库名.git
git push -u origin main

fatal:remote origin already exiests.

处理方法：git remote rm origin

三、Git 进阶技巧

1. 设置别名

用 alias 给常用命令起别名，可以简化输入。基本语法：

git config --global alias.别名 git命令

例如给 commit 和 status 起别名：

git config --global alias.ci commit # 用 ci 代替 commit
git config --global alias.st status # 用 st 代替 status

别名可以根据个人习惯自由设定。设置后，可以在 .gitconfig 文件里看到对应的 alias 配置；不需要时删掉即可。

2. 查看改动

git diff

3. 版本回滚

先用 git log 查看版本号（commit 后面那一长串就是版本号）：

git reset --hard 版本号 # 回退并丢弃当前工作区的修改
git reset --soft 版本号 # 回退但保留当前工作区的修改，可重新提交

四、GitHub 实用插件与工具

Octotree：目录树
Sourcegraph：在线代码查看器
GITzip

图床方案：使用 GitHub + PicGo 搭建图床。