这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

安装

介绍Hugo的安装，使用，配置和优化

1 - linux安装Hugo

Hugo在linux操作系统下的安装

准备工作

安装golang

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

安装nodejs/npm

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

在以下网站下载nodejs的安装包：

https://nodejs.org/en/download/package-manager

# installs nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# download and install Node.js (you may need to restart the terminal)
nvm install 22

# verifies the right Node.js version is in the environment
node -v # should print `v22.11.0`

# verifies the right npm version is in the environment
npm -v # should print `10.9.0`

安装Hugo

在Hugo Releases页面下载对应操作系统版本的安装包。

注意：由于Google Docsy主题的需求，需要 extended 版本的hugo 以支持 SCSS.

由于 hugo和主题之间版本有依赖关系，因此我们暂时固定使用 v0.121.1 版本。

找到linux的安装包，对于 ubuntu 可以直接用 deb 文件：

  • hugo_extended_0.121.1_linux-amd64.deb
wget https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_extended_0.121.1_linux-amd64.deb

deb文件直接安装即可。

sudo dpkg -i hugo_extended_0.121.1_linux-amd64.deb

2 - windows安装Hugo

Hugo在 windows 操作系统下的安装

准备工作

安装golang

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

https://go.dev/dl/

下载 windows 安装文件，如 go1.23.3.windows-amd64.msi。

安装时选择安装目录为 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的安装包：

https://nodejs.org/en/download/package-manager

选择 prebuild installer，下载到 node-v22.11.0-x64.msi。

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

安装Hugo

在Hugo Releases页面下载对应操作系统版本的安装包。

注意：由于Google Docsy主题的需求，需要 extended 版本的hugo 以支持 SCSS:

由于 hugo和主题之间版本有依赖关系，因此我们暂时固定使用 v0.121.1 版本。

https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_extended_0.121.1_windows-amd64.zip

下载下来之后，解压缩，将 hugo.exe 文件复制到目录 C:\Users\sky\work\soft\hugo 或者 D:\sky\work\soft\hugo 下。

然后修改环境变量，在 Path 中增加一项，路径为 C:\Users\sky\work\soft\hugo 或者 D:\sky\work\soft\hugo 。

验证安装：

$ which hugo
/c/Users/sky/work/soft/hugo/hugo

$ hugo version
hugo v0.121.1-00b46fed8e47f7bb0a85d7cfc2d9f1356379b740+extended windows/amd64 BuildDate=2023-12-08T08:47:45Z VendorInfo=gohugoio

3 - macOS安装Hugo

Hugo在macOS操作系统下的安装

准备工作

安装golang

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

安装nodejs/npm

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

在以下网站下载nodejs的安装包：

https://nodejs.org/en/download/package-manager

TODO

安装Hugo

在Hugo Releases页面下载对应操作系统版本的安装包。

注意：由于Google Docsy主题的需求，需要 extended 版本的hugo 以支持 SCSS:

备注: mac 下安装最简单的方式是用brew命令，但不合适用来安装extended版本，所以还是需要下载之后手工安装

下载下列文件：

wget https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_extended_0.121.1_darwin-universal.tar.gz

解压后，将 hugo 可执行文件放在path路径下即可：

cd hugo_extended_0.121.1_darwin-universal
sudo cp hugo /usr/local/bin/hugo

4 - 安装后配置Hugo

Hugo安装完成后的配置工作

设置别名

为了方便使用，增加 hugo server 命令的 alias 用来本地编辑时的实时预览：

vi ~/.zshrc

增加内容：

# 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 命令需要代理才能顺利下载文件，比如：

npm install -D --save autoprefixer

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

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

这说明是网络出了问题，导致无法访问 github.com ，需要设置网络代码：

npm config set proxy http://192.168.2.1:7890
npm config set https-proxy http://192.168.2.1:7890

参考：

通用代理

如果之前配置有通用代理命令 proxyon，则执行 proxyon 开启各种代理即可：

# proxy
alias proxyon='export all_proxy=socks5://192.168.2.1:7891;export http_proxy=http://192.168.2.1:7890;export https_proxy=http://192.168.2.1:7890;export no_proxy=127.0.0.1,localhost,local,.local,.lan,192.168.0.0/16,10.0.0.0/16'
alias proxyoff='unset all_proxy http_proxy https_proxy no_proxy'

或者临时性的在当前终端中执行：

export all_proxy=socks5://192.168.2.1:7891

5 - 快速开始

详细介绍通过Hugo快速开始启动一个现有的项目

通常我在安装完成 hugo 之后，第一时间使用的是我的学习笔记。因此，以 hugo 学习笔记为例。

具体参考：

本地快速搭建学习笔记

6 - 开启HTTPS

如何为Hugo增加HTTPS支持

参考文章：

由于我用的博客服务器是ubuntu 16.04，因此部分命令稍有不同。

生成证书

先安装工具：

sudo apt-get install letsencrypt

生成证书：

sudo letsencrypt certonly --webroot -w /var/www/skyao -d skyao.io

配置nginx

在/etc/nginx/sites-available下增加一个skyao.io.https站点文件，内容如下：

server {
    listen 443 ssl;
    server_name skyao.io www.skyao.io;

    root /var/www/skyao;
    index index.html;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/skyao.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/skyao.io/privkey.pem;
}

然后将http请求都自动转为https，修改原来的skyao.io配置文件：

server {
    listen 80;
    server_name skyao.io www.skyao.io;
    rewrite ^(.*)$  https://$host$1 permanent;
}

重启nginx：

sudo service nginx restart

设置自动更新证书

由于Let’s Encrypt证书的有效期为90天，所有我们需要定期更新以避免证书过期，通常Let’s Encrypt会发邮件提醒的。

更新操作如下：

# 更新证书
sudo letsencrypt renew
# 重新启动nginx
sudo systemctl restart nginx

7 - 搜索引擎优化（待更新）

为了让Hugo网站更好的被搜索引擎收录，需要进行搜索引擎优化

站点内容优化

修改配置

修改 hugo/config/_default 目录下的 params.toml 文件：

description = "敖小剑的个人技术博客网站，主要关注服务网格,serverless,kubernetes,微服务等云原生技术。"

修改模板

0.54 版本下基本做的很好了，不再修改。

添加页面信息

首先确保每个页面一定都要设置有 title，description，最好还有 keywords：

title: 前言
keywords:
- hugo
- 学习笔记
- hugo学习笔记
description : "介绍Hugo学习笔记的基本资料和访问方式。"

google搜索优化

提交给Google网站站长

打开 Google网站站长，点击 “SEARCH CONSOLE ” 进入，然后添加资源，如https://skyao.io/learning-hugo/。会要求下载一个html文件如google571325××××.html做验证，将这个文件保存到hugo站点根目录下的static子目录，更新站点内容让google search console可以访问到进行验证即可。

进入资源页面，点"索引"下的"站点地图"，在"添加新的站点地图"处输入当前hugo站点的sitemap，这个文件hugo会默认生成，就在根路径下，如https://skyao.io/learning-hugo/sitemap.xml。

百度搜索优化

打开 百度搜索资源平台 ，点击 链接提交，然后点"添加站点"。同样可以用文件验证的方式来进行网站验证。

进入"数据引入"下的"链接提交"，再点 “自动提交” 下的 “sitemap”，在这里可以提交hugo网站的sitemap文件。注意百度不容许以子目录的方式提交子站点，和google不一样，我们的学习笔记 https://skyao.io/learning-hugo/ 就不能直接提交了，只能在提交sitemap文件时，提交多个sitemap文件。这样也能勉强让百度收录。

Bing搜索优化

在 Bing Webmaster Tools 处用登录，然后选择导入站点。Bing webmaster tools支持直接从 google 导入数据，很方便。

操作界面和google很类似。

参考资料

有参考以下资料，特此鸣谢：

8 - 增加更多语言的语法高亮

默认支持的编程语言有限，可以在需要时增加语言的支持，使之也可以做到语法高亮

默认支持的语言列表

hugo 采用 Prism 进行编程语言的语法高亮，由于编程语言数量太多，通常也不需要支持所有的语言（会导致js和css文件过大），因此默认只支持以下语言：

  • markup
  • css
  • clike
  • javascript
  • bash
  • c
  • csharp
  • cpp
  • go
  • java
  • markdown
  • python
  • scss
  • sql
  • toml
  • yaml

其他语言是无法支持的，比如默认 rust 语言就不被支持。如果需要增加对rust语言的支持，可以进行定制。

定制新的语言支持列表

步骤如下：

  1. 打开任意页面，查看源代码，找到 <script src='/js/prism.js'></script> 这段，通常在页面最下方

  2. 打开这个 js 文件，比如 http://localhost:1313/js/prism.js ，可以看到最前面有这么一排注释：

    /* PrismJS 1.25.0
https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+markdown+python+rust+scss+sql+toml+yaml&plugins=toolbar+copy-to-clipboard */

    这里有版本和支持语言列表。

  3. 打开上面的 URL 地址，在该页面增加需要支持的语言，如:

    • HTTP
    • Lua
    • Makefile
    • Rust
    • .properties
    • Protocol Buffers
    • WebAssembly

    也可以添加插件

    • Line Highlight
    • Line Numbers
    • Highlight Keywords

  4. 点击页面下方的“download js”和“download css”，下载 prism.js 文件和 prism.css 文件

    此时 js 文件前面的内容变为：

    /* PrismJS 1.25.0
https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+lua+makefile+markdown+properties+protobuf+python+rust+scss+sql+toml+wasm+yaml&plugins=line-highlight+line-numbers+highlight-keywords+toolbar+copy-to-clipboard */

  5. 将上述文件分别复制到hugo项目根目录下，路径为： static/css/prism.css 和 static/js/prism.js ，这会覆盖默认的文件。

其他：高亮的参数设置

可以高亮某些行，现实代码行数等。

https://gohugo.io/content-management/syntax-highlighting/