一直想着建个自己的网站,顺便折腾点主题。前几天突发奇想注册了这个域名。顺手也把网站搭起来。调研了现在静态博客的情况,之前印象中的流行框架 HEXO 已然被 Hugo 盖住了风头。学习了下 Hugo,够简单,功能也够丰富。虽然网上 Hugo 搭建指南一大把,但我还是记录一下自己的使用过程,也作为第一篇正式博文。
你可以在这篇博客中了解到:
- Hugo 搭建静态博客方法
- 利用 github pages 托管网页
- 利用 github action 自动发布网页
- 一些建站过程中的 tips
安装Hugo
Hugo的官网是https://gohugo.io/,另外有个中文文档网站https://gohugo.org/也可以参考。
官方推荐了很多安装方式,但我觉得直接下载二进制文件最为方便(升级需要手动),Hugo有标准版、扩展版两个版本,扩展版支持对 WebP 图像进行编码和使用嵌入式 LibSass 转译器将 Sass 转译到 CSS,官方也推荐使用扩展版。
下载后,放到对应路径,添加到 PATH 环境变量,更方便使用。安装完后,使用以下命令进行验证:
hugo version
使用Hugo
生成站点
即在指定路径下生成名为 sitename 的文件夹
hugo new site /path/to/sitename
站点目录结构:
▸ archetypes/
▸ content/
▸ layouts/
▸ static/
config.toml
创建文章
在content文件夹下新建posts
文件夹并新建xx.md
文档
hugo new posts/xx.md
默认生成的 xx.md 内容和解释如下:
title: "xx" # 网站显示的文章名字,可以与文件名不同
date: 2021-08-19T15:04:55+08:00
draft: true # 是否为草稿
# 下面两个默认没有,需要自己加
categories: ["互联网"] # 文章分类
tags: ["Hugo", "Github Pages", "Github Actions", "CI/CD"] # 文章标签
一般情况下,我们都要新建这些文件构建网站的骨架:
- about.md
- archives.md
- search.md
- category.md
我一般会用文件夹组织 content 内的博文,比如我在posts
下新建年份目录(2023/)进行归类,便于查找管理
使用主题
可以去这里下载相关主题,并解压到theme
目录下。我个人比较喜欢 PaperMod 主题,然后参考Cassius’s Blog进行了魔改。除了下载也可以 git clone,或者 git submodule 便于更新主题。
使用主题需要在hugo.toml
中添加theme: PaperMod
才能启用
运行Hugo
在你的站点根目录执行 Hugo
命令进行调试:
hugo server -D --theme=PaperMod
-D 是显示草稿文章,–theme 是自行指定主题。然后打开 localhost:1313 就能欣赏自己的网站了。
如果没问题,可以执行发布命令,发布正式网站内容到public
目录:
hugo
hugo.yml 展示
hugo.yml
做了很多配置,我的如下:
baseURL: "http://tubaozi.top/"
title: 今是昨非 | 技术.生活.阅读.思考
paginate: 10
theme: PaperMod
languageCode: zh
defaultContentLanguage: zh
enableInlineShortcodes: true
enableRobotsTXT: true
buildDrafts: false
buildFuture: true
buildExpired: false
enableEmoji: true
googleAnalytics: G-MZJS5SGFET
minify:
disableXML: true
minifyOutput: true
menu:
main:
- name: 🔎 搜索
url: search/
weight: 9
- name: ⏱️ 时间轴
url: archives
weight: 10
- name: ⛩️ 分类
url: categories/
weight: 20
- name: 🧩 标签
url: tags/
weight: 30
- name: 🙋🏻♂️ 关于
url: about
weight: 50
outputs:
home:
- HTML
- RSS
- JSON
params:
env: production # to enable google analytics, opengraph, twitter-cards and schema.
description: "个人博客"
author: Beeta
# author: ["Me", "You"] # multiple authors
# images: /favicon.ico
defaultTheme: auto
disableThemeToggle: false
# ShowShareButtons: true
# ShowReadingTime: true
# disableSpecial1stPost: true
displayFullLangName: true
ShowPostNavLinks: true
ShowBreadCrumbs: false
ShowCodeCopyButtons: true
ShowToc: true
# home-info mode
homeInfoParams:
Title: "悟已往之不谏,知来者之可追"
Content: >
- ✨ 欢迎来到我的个人博客
- 🤔 我在这里分享技术、读书、生活还有思考。
socialIcons:
- name: Github
url: "https://github.com/Beeta"
- name: RSS
url: "index.xml"
- name: email
url: "mailto:zrc199021@163.com"
label: # 左上角图标
text: "今是昨非"
icon: "img/足迹.png"
iconHeight: 35
markup:
goldmark:
renderer:
unsafe: true
配置github actions
一般情况下,直接把public
目录内容提交到你的xx.github.io
仓库就能访问了。但这样做需要每次都提交一堆内容,比较繁琐。我们可以用 github actions 实现提交自己的 md 文档后自动执行发布的功能。
原理:发布博文到仓库 -> 触发 actions 执行hugo
命令并复制public
下内容到指定仓库。
有的人将博文和发布内容放到两个仓库,我则是发到了统一仓库的两个分支上:master 分支存md 文件,gh-pages 分支放发布后的内容。
github actions 配置如下:
点击 github 仓库页面Actions
进行操作
最终会在仓库下生成.github/workflows
目录内部有自己指定的配置文件,如github-pages.yaml
。其中secrets.G_T
是自己申请的(settings->Actions secrets and variables->Actions创建名为secrets.G_T的秘钥)
github-pages.yaml
内容如下
name: GitHub Pages
on:
push:
branches:
- master # Set a branch to deploy
pull_request:
jobs:
deploy:
runs-on: ubuntu-20.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
with:
submodules: true # Fetch Hugo themes (true OR recursive)
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.112.1'
extended: true
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
if: ${{ github.ref == 'refs/heads/master' }}
with:
github_token: ${{ secrets.G_T }}
publish_dir: ./public
tips
hugo.toml
是最近版本新改的,之前是config.yml
,两者都行,甚至hugo.yml
也行。我比较习惯yaml语法,所以用最后这个每次发布都会重刷 public 里的所有文件,所以一些需要保留的文件需要放到static目录下
- 可以在static下放 favicon.ico 文件,再网页标题栏显示图标
- github页面展示需要的 CNAME文件也放在这
博客图片也可以放到 static 下,但是我个人习惯 md 文件和图片在同目录下。所以我的方式是每个博文一个文件夹,下面新建
index.md
作为博文主体。文件夹最好是英文,这样 url 编码好看些。生成的文章内部头部配置信息包括一些文章名称,时间之类的信息,可以事先在目录 archetypes/default.md 下使用模板,这样在用命令 hugo new 生成文章后会自动加上模板里的配置
我的博客代码托管在:https://github.com/Beeta/beeta.github.io
参考
下面的博客给了我很大帮助: