Hugo博客搭建简单教程
Tips
一些不懂的命令或者操作可以问AI
推荐Gemini3 ，个人认为比GPT好用
一. 环境配置
搜索hugo官网并依次安装
hugoGit
推荐使用vscode作为编辑器
二.本地初始化
本地新建文件夹Weblog
在文件夹目录下执行
hugo new site my-blog
cd ./my-blog
git init
作用：初始化hugo ， 本地Git仓库
你会得到
archetypes/: 内容模板文件。content/: 博客文章等内容。layouts/: 网站布局和模板。static/: 静态资源，如图片、CSS、JS。themes/: 主题存放目录。hugo.toml: 网站主配置文件。
我们主要修改的是:hugo.toml配置文件
前往hugo官网，选择自己喜欢的主题文件
Hugo Themes
点击Download跳转到对应的Github仓库
执行
git ./themes
git submodule add https://github.com/adityatelange/hugo-PaperMod.git #对应的主题仓库地址
下载对应的主题文件到./themes文件夹下
打开hugo.toml
修改基本配置
baseURL = "localhost:1313" #（重要）（之后换成你的域名/或者远程仓库名）
languageCode = "zh-cn"
title = "博客"
theme = "PaperMod" #你对应的主题的名字(重要)
[menu]
[[menu.main]]
identifier = "about"
name = "关于"
url = "/about/"
weight = 1
[[menu.main]]
identifier = "blog"
name = "博客"
url = "/posts/"
weight = 2
执行
hugo new posts/hello_world.md
在content目录下创建posts目录，并新建一个markdown文件
出现
---
title: "我的第一篇文章"
date: 2022-11-20T09:03:20-08:00
draft: true
---
在此处编辑文章
将draft设置为false （为true时为草稿不显示）
执行
hugo server -D
访问本地localhost:1313出现对应页面
设置.gitignore文件
/public/
/resources/
/.hugo_build.lock
/hugo_stats.json
选择不将冗余文件同步到远程仓库
这里不加public是因为 后续使用Github Actions 方便更新博客
设置Github Action文件
创建在.github\workflows\hugo.yml
name: Deploy Hugo site to Pages
on:
push:
branches: ["main"] # 只有推送到 main 分支时才触发
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive # 如果你的主题是 git submodule 形式，这行很重要
fetch-depth: 0
- name: Setup Hugo
uses: peaceiris/actions-hugo@v3
with:
hugo-version: 'latest'
extended: true # 建议开启，因为很多主题需要 extended 版本
- name: Build
run: hugo --minify
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./public
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
最后将所有修改提交至本地仓库
git add .
git commit -m "Initalize"
三.远程仓库初始化
Github新建一个仓库 ：
用户名.github.io
执行
git remote add origin #你的仓库地址
git branch -M main
git push -u origin main
绑定本地仓库和Github仓库
修改仓库设置
Settings->Pages->Github Actions启用
若有域名
在Custom domain中添加
当然也需要修改域名设置
四.一些修改
修改hugo.toml
baseURL = '...' #你的域名
参考选择的主题的文档修改toml
或者使用AI 的建议
在archetypes下
修改default.md: 更新 每次new 一个新文章的使用的模板
五.更新博客
设置好github action后只需要每次执行
git add .
git commit -m "update"
git push origin main
即可推送至网站
可作为脚本upload.bat
@echo off
echo 开始推送到 GitHub...
git add .
git commit -m "update %date% %time%"
git push origin main
echo 推送完成！
pause
双击或命令行执行.\upload.bat
六.更多内容
Latex
hugo使用katex进行渲染
在layouts文件夹下新建
math.html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" onload="renderMathInElement(document.body);"></script>
<script>
document.addEventListener("DOMContentLoaded", function() {
renderMathInElement(document.body, {
delimiters: [
{left: "$$", right: "$$", display: true},
{left: "$", right: "$", display: false}
]
});
});
</script>
拉取你的主题的single.html到layouts文件夹下的_default文件夹
在其最后一行添加
{{ if .Params.math }}{{ partial "math.html" . }}{{ end }}
每次新建文章时加入参数启用latex渲染
math: true
浏览量统计
可使用不蒜子 、或者其他工具
评论功能
使用Giscus
githubfeature启用discussion- 本地添加
giscus官方url生成对应的js文件 - 在
single.html下修改逻辑
Markdown编辑器
推荐使用Obsidian
七.提醒
- 如果浏览器无法正常渲染，尝试将插件关闭