Hugo使用指南

Hugo 是一个用 Go 语言编写的快速、现代的静态网站生成器。它以其极快的构建速度和易用性而闻名。以下是 Hugo 的基本使用流程和核心概念：

核心步骤
#

安装 Hugo
创建一个新站点
添加主题
添加内容
本地预览
构建静态网站
部署

1. 安装 Hugo
#

官方网站下载: 前往 https://gohugo.io/installation/ 下载适合你操作系统 (Windows, macOS, Linux) 的二进制文件。
包管理器:
- macOS (Homebrew): brew install hugo
- Linux (Snap): sudo snap install hugo
- Windows (Chocolatey): choco install hugo
安装完成后，在终端/命令提示符中运行 hugo version 验证是否安装成功。

2. 创建一个新站点
#

在终端中，导航到你想要存放网站项目的目录，然后运行：

hugo new site my-awesome-site

这会在当前目录下创建一个名为 my-awesome-site 的新文件夹，其中包含 Hugo 的基本目录结构：

my-awesome-site/
├── archetypes/       # 新内容的默认模板
├── assets/           # 需要 Hugo Pipes 处理的文件 (CSS, JS 等)
├── config.toml       # 主配置文件 (也可以是 config.yaml/config.json)
├── content/          # **核心目录：存放所有网站内容 (Markdown 文件)**
├── data/             # 网站使用的数据文件 (YAML, TOML, JSON)
├── layouts/          # **核心目录：HTML 模板 (覆盖主题模板或自定义)**
├── public/           # **Hugo 构建生成的静态 HTML 文件 (最终部署的内容)**
├── resources/        # Hugo Pipes 生成的缓存文件
├── static/           # **存放静态文件 (图片, CSS, JS, PDF 等)，直接复制到 public/**
└── themes/           # **存放网站主题**

3. 添加主题
#

Hugo 依赖主题来定义网站的外观和布局。主题通常放在 themes/ 目录下。

查找主题:
- 官方主题库: https://themes.gohugo.io/
- GitHub 搜索 hugo-theme
添加主题 (推荐使用 Git Submodule):
1. 进入你的站点根目录 (cd my-awesome-site)。
2. 找到你喜欢的主题的 Git 仓库地址 (例如 https://github.com/user/theme-name.git)。
3. 运行命令将其添加为子模块：
```
git init # 如果还没初始化 git 仓库
git submodule add https://github.com/user/theme-name.git themes/theme-name
```
配置主题: 打开主配置文件 config.toml (或 config.yaml/config.json)，添加主题配置：
```
theme = "theme-name"
```
- 根据主题文档，可能还需要配置其他选项（如菜单、参数等）。

4. 添加内容 (核心)
#

所有内容都放在 content/ 目录下，以 Markdown (.md) 文件形式组织。
创建新页面/文章:
- 手动创建： 直接在 content/ 或其子目录下创建 .md 文件 (例如 content/posts/my-first-post.md)。
- 使用 hugo new 命令 (推荐)：
```
hugo new posts/my-first-post.md
```
  这会根据 archetypes/default.md 模板在 content/posts/ 下创建文件，并包含预填充的 Front Matter。
理解 Front Matter: 每个内容文件顶部需要有一段用 +++ (TOML) 或 --- (YAML) 包裹的元数据区域，称为 Front Matter。它定义了页面的标题、日期、分类、标签、模板、草稿状态等。例如 (TOML)：
```
+++
title = "我的第一篇博文"
date = 2023-10-27T15:30:00+08:00
draft = true # 标记为草稿，构建时默认不发布
categories = ["技术", "Hugo"]
tags = ["入门", "静态网站"]
author = "你的名字"
+++
```
- draft: true 的文章在运行 hugo server -D 时会显示，但 hugo (正式构建) 时默认不会生成。
编写内容: 在 Front Matter 下方，使用标准的 Markdown 语法编写你的内容。Hugo 支持所有基本 Markdown 语法以及一些扩展（如代码高亮、短代码）。

5. 本地预览 (开发阶段必备)
#

在站点根目录下运行：

hugo server -D

-D: 包含标记为 draft: true 的草稿文章。
-F: 包含标记为 publishDate 在未来的文章。
默认情况下，Hugo 会启动一个本地开发服务器，通常监听在 http://localhost:1313。
实时重载: 这是 Hugo 的一大亮点！保存对内容文件 (content/)、配置文件 (config.toml)、模板文件 (layouts/) 或静态文件 (static/) 的更改后，浏览器会自动刷新，几乎无需手动刷新即可看到最新效果。

6. 构建静态网站 (准备部署)
#

当你对网站满意并准备好发布时，运行：

hugo

这会将你的整个网站（不包括草稿和未来的文章）编译成静态 HTML、CSS、JS 等文件，并输出到 public/ 目录。
public/ 目录里的内容就是最终可以部署到任何 Web 服务器（如 Nginx, Apache）或托管服务（如 GitHub Pages, Netlify, Vercel, Cloudflare Pages）上的文件。
构建选项:
- -D / --buildDrafts: 包含草稿。
- -F / --buildFuture: 包含未来的文章。
- --minify: 最小化输出文件 (HTML, CSS, JS)。
- --cleanDestinationDir: 在生成新文件前清除 public/ 目录（删除旧文件）。

7. 部署
#

将 public/ 目录里的所有内容上传到你的 Web 服务器或托管服务即可。

常用托管方式:
- GitHub Pages:
  1. 在 GitHub 上创建一个仓库 (例如 username.github.io)。
  2. 将 public/ 目录的内容推送到该仓库的 main 或 gh-pages 分支 (具体看 GitHub Pages 设置)。
- Netlify / Vercel / Cloudflare Pages:
  1. 将你的 整个 Hugo 项目根目录 (包含 config.toml, content/, themes/ 等，不包括 public/) 推送到 GitHub/GitLab/Bitbucket。
  2. 在这些平台上创建一个新站点，连接到你的代码仓库。
  3. 设置构建命令为 hugo (或 hugo --minify)，发布目录为 public。
  4. 每次向仓库推送代码，平台会自动触发构建和部署。非常方便！

关键目录和文件总结
#

config.toml / config.yaml / config.json: 主配置文件，设置站点全局参数、主题配置等。
content/: 核心内容目录，所有 Markdown 文件存放于此，组织方式决定 URL 结构。
layouts/: 模板目录，存放 .html 模板文件 (覆盖主题模板或创建自定义模板)。
static/: 静态文件目录，存放图片、CSS、JS、PDF 等，直接复制到最终 public/。
themes/: 主题目录，存放下载的主题。
public/: 输出目录，运行 hugo 后生成，包含最终可部署的静态网站文件。
archetypes/: 内容模板，hugo new 命令会基于此创建新内容文件。

常用命令总结
#

hugo new site [name]: 创建新站点
hugo new [path/to/content.md]: 创建新内容文件
hugo server / hugo server -D: 启动本地开发服务器 (不含/含草稿)
hugo: 构建网站到 public/ 目录 (不含草稿和未来文章)
hugo -D: 构建网站并包含草稿
hugo --minify: 构建并最小化输出文件
hugo version: 显示 Hugo 版本

学习更多
#

官方文档: https://gohugo.io/documentation/ - 最全面、最权威的资源。
官方论坛: https://discourse.gohugo.io/ - 提问和查找答案的好地方。
主题文档: 仔细阅读你所选主题的文档，了解其特定配置和功能。

主题推荐
#

参考博客
#

上面推荐的文章你是否喜欢呢，如果有什么好的推荐或者想要了解最新的工具，欢迎在评论区留言和大家一起交流！喜欢记得关注公众号【可持续学园】，我们下期再见！ 👇

核心步骤 #

1. 安装 Hugo #

2. 创建一个新站点 #

3. 添加主题 #

4. 添加内容 (核心) #

5. 本地预览 (开发阶段必备) #

6. 构建静态网站 (准备部署) #

7. 部署 #

关键目录和文件总结 #

常用命令总结 #

学习更多 #

主题推荐 #

参考博客 #

相关文章