Hugo Web

Hugo + Stack 简单搭建一个静态博客

从零开始的博客生活

前言

静态博客已成为现代技术博客、个人站点和文档系统的热门选择。

本文基于Hugo

Hugo优势

生产的性能好。Hugo是由 Go 语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。

无论是Hugo还是Hexo，本质上都是将master文件通过预定好的模板渲染html文件

环境准备

  1. 下载golang

  2. 下载node.js

安装golang

安装hugo之前，先安装好golang，推荐安装最新版本。

安装时选择安装目录为 C:\Users\sky\work\soft\golang 或者 D:\sky\work\soft\golang。

修改环境变量，将 GOPATH 的值修改为 C:\Users\sky\work\soft\gopath 或者 D:\sky\work\soft\gopath（默认为 %USERPROFILE%\go）。

安装nodejs/npm

为了使用Google Docsy主题，需要安装nodejs/npm。

在网站下载nodejs

安装时选择安装路径为C:\Users\sky\work\soft\nodejs或者 D:\sky\work\soft\nodejs。

安装Hugo

在Hugo Releases页面下载对应操作系统版本的安装包。Hugo官方下载文档 ,如hugo_extended_0.150.0_windows-amd64.zip.下载下来之后，解压缩，将 hugo.exe 文件复制到目录下。

然后修改环境变量，在 Path 中增加这个路径， 验证安装 $ which hugo 、$ hugo version。

切记由于 hugo和主题之间版本有依赖关系，因此不同主题选择不同版本

打开命令提示符，输入hugo version来验证安装是否成功。

Hugo安装完成后的配置工作

设置别名

为了方便使用，增加 hugo server 命令的 alias 用来本地编辑时的实时预览： vi ~/.zshrc 增加内容：

1
2
3
4
5

# hugo
alias h='hugo -D -F server --disableFastRender --bind "0.0.0.0"'
alias h2='hugo -D -F server --disableFastRender --bind "0.0.0.0" --port 2323'
alias h3='hugo -D -F server --disableFastRender --bind "0.0.0.0" --port 3333'
alias h4='hugo -D -F server --disableFastRender --bind "0.0.0.0" --port 4343'

hugo命令行参数说明：

-D: 等同–buildDrafts，标记为 Draft 的内容也会一起构建，方便在本地编写和预览新的暂时未发布的内容。

-F: 等同–buildFuture，发布时间为"未来"(即时间比当前时间还要晚)内容也会一起构建，方便在本地编写和预览新的暂时未发布的内容。 –disableFastRender：当内容修改时，进行完整的重新构建，避免预览的内容不够新 h2/h3/h4 指定了不同的端口，当需要在本地打开多个时，可以使用固定端口而不是随机端口。

设置代理

npm代理

主要是 npm 命令需要代理才能顺利下载文件，比如:安装 PostCSS 要构建或更新站点的 CSS 资源，您还需要PostCSS创建最终资产。

如果您需要安装它，您必须在您的机器上安装最新版本的NodeJS，以便您可以使用npmNode 包管理器。

默认情况npm下，在您运行的目录下安装工具

1
2
3
4

npm install：
npm install -D autoprefixer
npm install -D postcss-cli
npm install -D --save autoprefixer

如果发生报错，并且查看到如下的错误信息

1
2
3
4
5
6
7
8

path /home/sky/work/code/learning/docsy/>node_modules/hugo-extended
command failed
command sh -c node postinstall.js
✖ Hugo installation failed. :
node:internal/process/promises:391
triggerUncaughtException(err, true />*fromPromise*/);
	^
RequestError: getaddrinfo ENOTFOUND github.com

解决方式：

1
2
3

npm config set registry <https://registry.npmmirror.com>
npm config set proxy <http://192.168.2.1:7890>
npm config set https-proxy <http://192.168.2.1:7890>

如果遇到报错信息：

1
2

Failed to connect to github.com port 443 after 21045 ms
Could not connect to server

注意修改成自己的IP和端口号

1
2

git config --global http.proxy <http://127.0.0.1:7890>
git config --global https.proxy <http://127.0.0.1:7890>

站点骨架

每个 Hugo 项目都是一个目录，其中的子目录贡献于站点的内容、结构、行为和呈现。

在创建新站点时，Hugo 会生成一个项目骨架。例如，以下命令：
利用hugo new site myblog(此时需要用到hugo.exe,假设存放在bin下),会在bin下生成myblog

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

myblog/
├── archetypes      #新建内容的模板（原型），方便统一管理文章格式，用于新建内容时自动填充默认 Front Matter
│   └── `default.md`
|--assests              #目录包含通常通过资源管道传递的全局资源。包括图片、CSS、Sass、JavaScript 和 TypeScript 等资源。
├── hugo.toml           # 博客站点的配置文件
├── content             # 博客文章所在目录.目录包含组成站点内容的标记文件（通常是 markdown）和页面资源
├── data                #目录包含用于增强内容、配置、本地化和导航的数据文件（JSON、TOML、YAML 或 XML），供模板调用
|----i18n               #目录包含多语言站点的翻译表。
├── layouts             # 自定义网站布局。目录包含将内容、数据和资源转换为完整网站的模板。决定网站的外观和布局。主题通常也会提供一套layouts，当你用自定义（不使用主题）时候可以在此覆盖主题默认模板。（hugo 初始化的layouts并不包含任何主题）
├── static              # 一些静态内容，目录包含在构建站点时将复制到 public 目录的文件，例如 .ico、.txt 和用于验证站点拥有权的文件。在引入 页面包 和 资源管道之前，static 目录也用于存放图片、CSS 和 JavaScript 等资源
└── themes              # 博客主题， 目录包含一个或多个主题，每个主题位于自己的子目录中。包含自己的layouts、static、配置文件等。启用主题后，Hugo首先会从主题中加载布局文件，再加载站点内自定义的覆盖文件
根据需要，可以将站点配置组织到子目录中：
|---config/                    #目录包含站点配置，可能分为多个子目录和文件。对于配置较少或不需要在不同环境中以不同方式运行的项目，项目根目录中的单个 hugo.toml 配置文件就足够了。
|___ _default/     
|_____config.toml #全局配置文件

  • config.toml

    Hugo的全局配置文件，用于定义站点的基本信息、URL、语言、主题、菜单等。也可以使用config.yaml/config.json

  • content/

​ 存放所有博客文章和页面。每个markdown文件的Front matter中定义标题、日期、草稿状态、标签与分类等信息。

​ 示例文件：

title:"我的第一篇文章"
date:2024-03-21
draft:false
tags:["入门"、“Hugo”]
categories:[“技术博客”]
这里是文章内容
  • archetypes/

​ 定义新建内容时所用的模板（原型），方便统一管理文章格式。你可以自定义默认模板以满足特定格式要求

​ 下有模板index.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
title: "{{ replace .Name "-" " " | title }}" # 标题，创建时自动填充
slug: "{{ replace .Name "-" " " | title }}" #URL标识符，如果没有则于title相同
description: # 文章简介
date: {{ .Date }} # 日期，创建时自动填充，格式同 2023-01-15T12:00:00+08:00
image: # 文章的封面，留空就是没有，填文章所在位置的相对地址，通常放在同目录下，
math: # 是否启用 KaTex，填 true 启用
license: # 文章尾部显示的协议，false 为隐藏，其他作为内容，留空就是使用 config.yaml 里默认的
hidden: false # 是否隐藏，一般用不到
comments: true # 因为 bug 所以这个属性只要存在，不管是 true 还是 false 都会导致回复无法显示，需要删掉
draft: true # 是否为草稿，建议改为 false 或者删掉这个属性以防止忘记修改，毕竟我们一般都是写好了才部署到服务器上
---

  • layouts/

    存放网站页面模板文件，决定网站的外观和布局。主题通常也会提供一套layouts，当你需要自定义时可以自此覆盖主题默认模板

  • static/

    内容所有不会经过Hugo处理的静态文件，如图片、CSS文件、JS文件等。生成网站时，这些文件会直接复制到输出目录。

  • themes/

    存放第三方主题，每个主题通常都包含自己的layouts、static、配置文件等。启用主题后，Hugo会先从主题中加载布局文件，再加载站点内自定义的覆盖文件。

  1. 利用Hugo命令构建站点时，Hugo 会创建一个 public 目录，目录包含发布的网站，在运行 hugo 命令时生成。Hugo 根据需要重建此目录及其内容。
  2. 通常还会创建一个 resources 目录：目录包含 Hugo 资源管道的缓存输出，在运行 hugo 或 hugo server 命令时生成。默认情况下，此缓存目录包括 CSS 和图片。Hugo 根据需要重建此目录及其内容。
  3. Hugo 创建了一个联合文件系统，允许将两个或多个目录挂载到同一位置。例如，假设您的主目录包含一个 Hugo 项目的目录，另一个目录包含共享内容。您可以使用挂载（mounts）在构建站点时包含共享内容。
  4. 在站点配置中当两个或多个文件具有相同路径时，优先级顺序遵循挂载的顺序。例如，如果共享内容目录包含 books/book-1.md，则会被忽略，因为项目的 content 目录先被挂载。
  5. 将archetypes/default.md,"+“改成”-","=“改成”+"，因为这个时toml格式的，我们要改成yaml格式

配置主题

  1. 下载主题

​ 以Stack为例，下载发布页面.把解压好的主题放在themes下，并把后面的版本号如3.3.10去掉

​ 或者将存储库克隆到 themes/hugo-theme-stack

​ git clone https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

​ 或者如果您已经在您的网站中使用 Git，则可以通过在 Hugo 网站的根目录中运行以下命令将主题添加为子模块：

​ git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

  1. 把子模块的hugo-theme-stack里的layouts复制出来，复制到myblog下的layouts

  2. 在hugo-theme-stack里examplesite里面的content和hugo.yaml,复制到myblog 下，然后把原来的hugo.toml删掉

    1
2
3
4
5
6
7

    示例
baseurl: https://example.com/ 
languageCode: en-us
theme: hugo-theme-stack#指定主题
title: Example Site
copyright: Example Person
DefaultContentLanguage: zh-cn# 默认语言

  3. 然后在终端执行hugo，进行构建（如果有一些我们没有，删除content下post的内容，只留下chinese-test）

  4. 同一个文件可以通过多个markdown，后缀名不同来实现。默认的index就是默认的名字 zh-cn# 默认语言，默认的主题下的名字。如果。即content/post/chinese-test下的 index-zh-cn.md可以通过index-zh-cn来改变在中文界面显示。index-en会在英文界面下显示。

方法一：通过文件后缀名实现

你想要的效果 做法
只在中文站显示 只创建 index.zh-cn.md
只在英文站显示 只创建 index.en.md
中英文都显示 创建 index.zh-cn.md 和 index.en.md
根据默认语言 只创建 index.md（使用默认语言，在blog/hugo.yaml）

方法二：通过Front Matter指定

1
2

# 在文章前面的Front Matter中强制指定语言
lang: zh-cn  # 这篇文章只在中文本显示

文章开头可以有categories分类和用来打tags标签

注意：如果创建多级文件夹时文章文件名不是 index.md 或者类别、标签文件名不是 _index.md 的话，设置封面图片会出现问题。

如何快速创建一个文章？hugo new potst/test/index.md,就生成了test/index.md,将draft:true改成draft:false（此时是在content/post下）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

title: Chinese Test
description: 这是一个副标题
date: 2020-09-09
slug: test-chinese
image: helena-hertz-wWZzXlDpMog-unsplash.jpg
categories:
    - Test
    - 测试
    - HLE
tags:
    - lf

常用命令

命令 说明
hugo new post/test/index.md 创建新文章。新建文章后，Hugo会在content/post目录下生成一份Markdown文件，并根据archetypes中的模板填充默认Front Matter
hugo server -D 启动本地服务器预览，使用-D参数可包含草稿内容进行预览
hugo 构建站点（生成静态文件到public/目录）
hugo –cleanDestinationDir 清理构建文件并重新生成
hugo –minify 构建并压缩HTML/CSS/JS文件（适合生产部署）
hugo new site [path] 创建一个新站点
hugo server 启动本地服务器预览
hugo config 显示站点配置信息
hugo list drafts 列出所有处于草稿状态的文章

常用参数

  • -D ,–buildDrafts:包括草稿文章
  • -F，–buildFuture:包括未来发布的文章
  • -E，–buildExpired：包括已过期的文章
  • –minify:生成时压缩输出文件
  • –gc:构建时运行垃圾回收

在content/page里修改左侧的内容

404 Page Not Found

注意，一旦网站可以建立，那么除非你做一个新的文件，否则就一直404

  1. hugo server –theme=your_theme_name(echo “theme = ‘ananke’” » hugo.toml)，这个相当于向hugo.toml添加theme
  2. 删去 hugo.toml,保留config.toml

推荐：在 config.toml 中写 theme = "your_theme_name"

临时：命令行 hugo server --theme=your_theme_name

如果需要更多,如配置favicon，评论区，参考建站技术 | 使用 Hugo + Stack 简单搭建一个博客

Github推送自动化

在使用 GitHub Pages 构建并托管博客时，我们面临一个常见问题：如何在保持源码安全的同时，将构建好

的 public 文件用于页面展示。直接丢上去的往往是public文件。为了解决这一问题，我们可以通过创建两个 GitHub 仓库来实现不同用途的分离和自动化管理。

  1. 源码仓库（source_blog）
    • 用于存储博客相关的源码， 包括markdown文件、配置信息等未构建的内容
    • 设置为Private仓库
  2. 展示仓库（blog_show)
    • 用于存储构建后的文件（如public文件夹），供Github Pages或其他托管服务使用
    • 设为Public仓库，确保可以正常访问页面

自动化流程

利用Github Actions或脚本实现如下自动化：

  1. 在源码仓库更新时触发构建操作，生成博客所需的静态文件。将生成的文件自动推送到展示仓库，无需手动干预。

  2. Settings->Developer Settings->Personal access tokens -> Tokens(classic),勾选repo和workflow，过期时间选择永远不过期。generate token，然后复制生成的token。

  3. 点开source_blog,Security-Secrets and variables-Actions-Repository secrets-New repository secret,填写2中生成的token。

  4. 修改自动化代码(deploy.yml)，将修改分支改成master。将.github_hugo移到blog下，并且去掉_hugo,作为部署文件

  5. git init 创建.git 文件

  6. EXTERNAL_REPOSITORY:xx/blog_show，展示的博客

​ blow_show里所展示的就是public里面的内容

  1. blow_show>Settings>Pages>Build and delployment，改成 master 和root

你可以在根目录创建一个批处理脚本，用来快速启动本地服务器并使用 chrome 打开网页。

1
2
3
4
5
6

本地运行.bat
@echo off
echo [本地运行]
start chrome http://localhost:1313/ #默认开放1313端口
hugo server
pause

使用Netlify

Add new project → import an existing project→选择blog_show

Typora +PicGo 图床配置

下载PicGo

创建一个新的仓库如blog_picture 设置为公开博客图片

再次重复操作,生成一个blog_show,然后在PicGo里填写对应Token.

这样子就可以通过PicGo上传了。

但是我不想每次都得要先通过PicGo上传至Github，然后将链接如（https://raw.githubusercontent.com/S1-19027/blog_picture/master/image-20250925115857370.png）再复制到Markdown里的链接语法。

我希望截图后就可以直接上传至github

在Typora中：

  1. 指定一下图形设置的上传服务设定

  2. 插入图片时选择上传图片。

阿里云图床,开通OSS教程：参考文献1、参考文献2

注：阿里云的99元/年云服务器似乎不太行，还是老实买点2核4Gib的70元/月

华为云相比较太贵了，更多的我也懒得去找了。

使用云服务器

利用Nginx即可

附录

参考文献

  1. hexo与hugo博客搭建与github自动化推送和服务器推送
  2. Stack官方文档
  3. 建站技术 | 使用 Hugo + Stack 简单搭建一个博客
  4. Hugo Stack开启多语言模式

版权信息

本文原载于blog.chenalna.site，遵循 CC BY-NC-SA 4.0 协议，复制请保留原文出处。

Hugo
Licensed under CC BY-NC-SA 4.0
© 2020 - 2025 chenalna
使用 Hugo 构建
主题 Stack 由 Jimmy 设计