本教程将介绍如何使用 Hugo 和 GitHub Pages 搭建一个静态博客。Hugo 是一款功能强大的静态站点生成器，可以帮助您轻松创建美观、响应式的博客页面。GitHub Pages 则是 GitHub 提供的免费托管服务，可用于托管您的 Hugo 博客。本教程将手把手地带你一步步学习如何使用Hugo搭建自己的博客网站,并部署到GitHub Pages上。让我们开始吧!
第一部分：入门与环境搭建
1.环境准备
在开始之前，请确保您的电脑已安装以下软件:
文本编辑器或 IDE： 用于编写 Markdown 内容和 Hugo 配置文件。推荐使用 Visual Studio Code 。
Git： 用于版本控制和部署代码。
2.在mac上安装hugo
安装hugo的时候注意要安装extended版本，不要安装standard版本，否则会有一些模板不兼容。 你可以根据自己的操作系统选择合适的安装方式, 比如在macOS上使用Homebrew安装:
brew install hugo
3.在windows上安装hugo
在windows系统上面使用winget安装hugo
winget install Hugo.Hugo.Extended
在windows子系统上面,和在linux上安装一样，建议使用sanp
sudo snap install hugo
第二部分：创建 Hugo 站点
1.创建 Hugo 新站点
使用 Hugo 创建新站点非常简单，只需在命令行中输入以下命令：
hugo new site my-blog
其中 my-blog 是您的博客名称，可以根据需要修改。
这将创建必要的配置文件和文件夹，并提示您输入一些站点信息，例如站点标题、描述等。
2. 初始化git
进入新创建的站点目录，并运行以下命令进行初始化：
cd my-blog
git init
第三部分：选择和配置主题
1. 浏览和选择主题
Hugo 提供了丰富的主题模板，您可以根据自己的喜好选择合适的主题。
您可以通过以下方式浏览和选择 Hugo 主题：
官方主题仓库：https://themes.gohugo.io/
第三方主题仓库：https://github.com/topics/hugo-theme
2. 下载及应用主题
找到喜欢的主题后，您可以将其下载到本地并应用到您的站点中。如果你选择的主题支持git子模块管理，通过以下方式下载：
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
把地址修改为你选择的主题theme，下载完成后在 hugo.yaml 文件中配置主题名称。
theme = "mytheme"
如果您选择的主题不支持git子模块管理，则需要手动下载，将其解压到 themes/mytheme 目录下，并在 config.toml 文件中添加以下配置：
theme = "mytheme"
第四部分：内容创建与管理
Hugo 使用 Markdown 语言编写内容，这使得内容创作更加简单便捷
1. 理解 Hugo 目录结构
Hugo 站点的目录结构如下：
my-blog/
├── content # 存放所有内容文件
│ ├── _index.md # 博客首页内容
│ ├── posts # 博客文章
│ │ ├── first-post.md
│ │ └── second-post.md
│ └── pages # 博客页面
│ └── about.md # 关于页面
├── data # 存放站点数据
│ ├── authors.yml # 作者信息
│ └── config.toml # 站点配置文件
├── i18n # 国际化语言文件
│ ├── en.toml # 英文语言文件
│ └── zh.toml # 中文语言文件
├── layouts # 存放页面模板
│ ├── _default # 默认模板
│ ├── partials # 模板片段
│ └── index.html # 首页模板
├── assets # 存放编译前的资源文件
│ ├── css # 存放 CSS 源文件
│ ├── js # 存放 JavaScript 源文件
│ └── images # 存放图片源文件
├── resources # 存放生成的资源文件
│ └── _gen # 生成的资源文件
├── static # 存放静态资源（如图片、CSS、JS）
│ ├── css # 存放编译后的 CSS 文件
│ ├── js # 存放编译后的 JavaScript 文件
│ └── images # 存放图片文件
├── public # 生成的网站文件
├── themes # 存放主题文件
│ └── my-theme # 自定义主题文件
│ ├── layouts # 存放页面模板
│ ├── static # 存放主题静态资源
│ └── theme.toml # 主题配置文件
├── archetypes # 内容模板文件
│ ├── default.md # 默认内容模板
│ └── post.md # 博客文章模板
└── hugo_build.lock # Hugo 包管理文件
2. 添加内容
创建新的内容文件，例如一篇博客文章，
hugo new content posts/my-first-post.md
这个命令会在 content/posts 目录下创建一个 Markdown 文件，并使用您喜欢的文本编辑器进行编辑即可。
3. 使用 archetypes
Hugo 提供了 archetypes 功能，可以快速生成内容模板。例如，要生成一篇新的博客文章，您可以使用以下命令：
hugo new content posts/my-first-post.md
这将创建一个名为 my-new-post.md 的 Markdown 文件，并包含了一些archetypes/default.md 基本的文章模板，例如标题、日期等
第五部分：本地预览与配置
1. 博客本地预览
在对内容和主题进行修改后，您可以使用以下命令进行本地预览：
hugo serve
这将在您的浏览器中打开一个本地服务器，您可以访问 http://localhost:1313 来查看您的博客页面。
2. 预览草稿
本地预览默认是不渲染草稿的，如果你需要查看草稿，需要将 draft : true 修改为 draft : false,或者在命令中添加渲染草稿的参数：
hugo serve -D
3. 设置博客配置文件
Hugo 的配置文件 config.toml 用于配置站点信息、主题、菜单等。 除了在config.toml中设置基本信息外,Hugo还提供了许多其他配置选项,你可以根据需要进行定制。比如设置Markdown渲染引擎、启用评论系统、配置SEO优化等。
第六部分：部署到 GitHub Pages
1. 部署准备
在本地预览和调试完成后,是时候将我们的Hugo博客部署到互联网上了。这里我们选择使用GitHub Pages,它是GitHub提供的免费静态网站托管服务。 首先,你需要在GitHub上创建一个新的仓库,仓库名称遵循your-github-username.github.io的格式。这将是你博客的主域名。 在将您的 Hugo 博客部署到 GitHub Pages 之前，请确保您已经：
- 创建了一个 GitHub 账户。
- 创建一个新的 GitHub 仓库。
2. 首次部署
现在,我们可以将Hugo生成的静态网站文件推送到GitHub仓库:
git init
git remote add origin [email protected]:your-github-username/your-github-project-name.git
git add .
git branch -M main
git commit -m "First commit"
git push origin main
3. 修改部署方式为使用action
访问你的 GitHub 仓库。从主菜单中选择 Settings > Pages。将部署方式改为GitHub Actions.
4. 本地创建action文件
在本地添加一个action文件
.github/workflows/hugo.yaml
5. 添加action内容
将下面这些内容，复制到.github/workflows/hugo.yaml 文件中。
# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages
on:
# Runs on pushes targeting the default branch
push:
branches:
- main
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
# Default to bash
defaults:
run:
shell: bash
jobs:
# Build job
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: 0.126.0
steps:
- name: Install 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: Install Dart Sass
run: sudo snap install dart-sass
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: 0
- name: Setup Pages
id: pages
uses: actions/configure-pages@v4
- name: Install Node.js dependencies
run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
- name: Build with Hugo
env:
# For maximum backward compatibility with Hugo modules
HUGO_ENVIRONMENT: production
HUGO_ENV: production
TZ: America/Los_Angeles
run: |
hugo \
--gc \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./public
# Deployment job
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@v4
内容可以到hugo 官网中查询，链接
6. 上传到github仓库
git add .
git commit "Add workflow"
git push origin main
7. 等待action部署完成
登陆github后台，找到项目的action选项，等等build和deploying 完成，状态指示灯变绿就成功了，现在你可以直接使用deploy下面的地址，来对你的博客进行访问了
第七部分：自定义域名与高级设置
1. 自定义域名
您可以使用自定义域名来访问您的 Hugo 博客。具体步骤如下： 购买一个域名。 首先验证你的域名 将您验证过后的域名指向 GitHub Pages 的 IP 地址。 在 GitHub 仓库的“Settings”>“Pages”中配置自定义域名。
结语
恭喜您完成了 Hugo 博客的搭建！通过本教程，您已经掌握了基本的 Hugo 博客搭建和使用知识，您可以开始使用您的 Hugo 博客分享您的想法和创意了。
