Hugo + Gitlab 建站流程

一、Hugo 安装和使用

1. 安装hugo（基于ubuntu）

$ sudo apt-get install hugo  

查看版本：

$ hugo version

注意： 各Linux维护的hugo版本极低，功能不全，不建议直接安装。
建议从官网 github.com/gohugoio/hugo/releases 下载，手动安装。

2. 新建网站（new site）

$ cd /home/uussrr  
$ hugo new site zzzblog  
$ cd zzzblog  

3. 下载主题（theme）

官方主题库：themes.gohugo.io/
注意兼容性： hugo版本要满足选定主题的最低要求。

$ cd zzzblog  
$ git init
$ git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

注意： 要使用 git submodule 。

4. 网站设置（Site Configuration）

编辑 config.toml 文件。

• 设置主题

theme = "ananke" 

注意：可以把theme目录中的样本config文件和相关内容文件均拷贝出来，直接用。

• 设置更新修改时间

[frontmatter]
  lastmod = [':git', 'lastmod', ':fileModTime', ':default']
    # 依次按照Git提交时间、文章里面的 lastmod 字段、文件的修改时间作为更新时间
enableGitInfo = true

5. 文件夹结构解释

• archetypes ：hugo new时基于archetypes，可自行预设。
• assets ：存储Hugo Pipes用到的所有文件。不是默认创建。文件用到.Permalink或者.RelPermalink的才publish到public文件夹。
• config ：设置文件夹。不是默认创建。
• content ：content文件夹中的子文件夹结构代表着网站的sections。Hugo用sections分配默认的content types。
• data ：内容的configuration files和data templates that pull from dynamic content。
• layouts ：.html的模板文件，用于生成静态文件
• static ：images, CSS, JavaScript等。
  注意： 图片放在static中的images文件夹中。引用时用 /images/aa.jpg。

6. 写东西

$ hugo new posts/my-first-post.md

7. 修改front matter

---
slug: " "
title: " "
date: "2099-12-31T23:59:59"
lastmod: "2099-12-31T23:59:59"
description: "  "
tags: [aaa, bbb, ccc, ddd]
featured_image: "/images/pic.jpg"
categories: " "
comment: true
draft: false
---

• slug：用来生成链接url，如果不设，使用title生成链接。
• date：日期的位数一定要严格。例如：“2022-01-01”正确，“2022-1-1”错误。
• draft：true（true，不处理，不发布）
• publishdate ：date value （如果是未来的，不处发）
• expirydate：date value （如果过期了，不处发）

8. 启动服务器

$ hugo server -D

-D 代表draft也显示
（LiveReload机制使得内容修改后自动即时更新）

9. 浏览器 http://localhost:1313/

10. 修改ccs文件，调节主题样式。

具体参照主题的文档
可以开着server修改，会实时显示更新。

11. 生成静态网页（static pages）

注意： 托管在gitlab不需要这步，因为在服务器端自动生成）

$ hugo -D

-D 代表draft也处理
默认存入 ./public/ (指定存入目标：使用参数-d或者修改config.toml文件中的publishdir)。
原来存在的文件，不动，尤其有过期的内容时注意。所以建议先清空./public/，再 $ hugo。

二、GitLab 托管

（一）新建项目

gitlab后台：新建项目new project/repository，Blank project，项目名称设置为username.gitlab.io（username为个人GitLab账户名）； Visibility Level选项选为私有；不选Initialize repository with a README。建立后，将Page对所有人可见。
注意：

• 项目名用"projectname"，该项目page做为项目的page，今后用 “https://username.gitlab.io/projectname“访问。
• 项目名用"username.gitlab.io”，该项目page做为用户的page，今后用 “https://username.gitlab.io“访问。

（二）SSH key

1. 本地计算机查看：

$ cd ~/.ssh
$ ls -al

是否有 id_rsa.pub 或者 id_dsa.pub 存在。

2. 本地生成：

$ ssh-keygen -t rsa -C "xxxxx@gmail.com"

3. 本地获得公钥：

打开 id_rsa.pub 文件，并且复制全部内容。

4. gitlab添加公钥:

gitlab后台：点击头像–设置，点击SSH密钥；将public key粘贴到相应位置并命名密钥，保存密钥。

三、新建网站的设置

（一） 添加Pipeline文件

1. 下载 https://gitlab.com/pages/hugo/-/blob/master/.gitlab-ci.yml
   文件内容一般无需修改；可以修改锁定hugo版本。
2. 存入网站文件夹根目录$ cd zzzblog，命名为.gitlab-ci.yml，注意以.点开头。
3. 修改config.toml文件：

baseurl = "https://uesrname.gitlab.io"

注意：如果项目的形式：

baseurl = "https://username.gitlab.io/projectname"

还需添加 relativeURLs = true 和 canonifyURLs = true 。

（二）本地git设置

$ git config --global user.name "xxxxx yyyyy"
$ git config --global user.email "xxxxx@gmail.com"

（三）git上传

$ cd zzzblog
$ pwd    # 检查当前位于网站文件夹的跟目录。

$ git init
$ git remote add origin git@gitlab.com:username/username.gitlab.io.git
$ echo "/public" >> .gitignore

上传：

$ git add .
$ git commit -m "commit"
$ git push -u origin master

（四）技巧（可选）：文章放在外部分文件夹

假设文章均保存在 /home/uussrr/posts 文件夹中管理；图片也保存在外部文件夹。

1. 新建 bind.sh 并附执行权：

#!/bin/bash
if [ "$(ls ./content/posts/)" = "" ]
then
    /bin/mount --bind /mnt/d/DAV/blog_nen_ink/posts ./content/posts
    if [ "$(ls ./static/images/)" = "" ]
    then
        /bin/mount --bind /mnt/d/DAV/blog_nen_ink/images ./static/images
        echo "bind OK"
    else
        /bin/umount ./content/posts
        echo "images existed. CHECK!"
    fi
else
    echo "posts existed. CHECK!"
fi

2. 新建 unbind.sh 并附执行权：

#!/bin/bash
/bin/umount ./content/posts
/bin/umount ./static/images

3. git忽略此两个脚本：

$ echo "/bind.sh" >> .gitignore
$ echo "/unbind.sh" >> .gitignore

4. 每次更新文章，上传：

$ cd zzzblog
$ sudo ./bind.sh
$ git add .
$ git commit -m "commit"
$ git push
$ sudo ./unbind.sh

四、浏览访问

gitlab后台：左侧菜单CI/CD->pipeline查看脚本执行情况，当脚本的Stages状态变为test:passed && deploy: passed成功，即可访问 https://uesrname.gitlab.io 。

五、绑定个人域名

1. gitlab后台：左侧面板settings->pages->new domain，填加个人域名。
2. Verification
   （域名管理后台：根据域名供应商的documentation设置！以下以namecheap.com为例）

gitlab后台：点击retry vertification，成功后显示vertified。

3. SSL证书：gitlab后台点选“Automatic certificate management using Let’s Encrypt”，即可由gitlab管理并自动更新let’sEncrypt申请的证书。

4. 域名管理后台：域名解析，添加个人域名指向https://uesrname.gitlab.io的主机记录。
   一般添加两条主机记录，分别是前缀www和前缀@，记录类型选择CNAME，记录值填写默认域名：uesrname.gitlab.io

5. 修改config.toml文件中的baseurl地址为https://yourdomain，重新提交。

六、添加Blog文章

当要在博客上写新文章时，用$ hugo new新建文章，使用markdown编辑器(如typora)编辑文章，完成后将源码push到Gitlab仓库中即可，Gitlab服务器会根据.gitlab-ci.yml文件重新生成博客的静态网页，然后自动发布到Gitlab pages博客站点上。
可以在gitlab后台点击CD/CI configuration让Gitlab服务器自动检测.gitlab-ci.yml文件，若文件正确则自动运行和发布；也可以在Gitlab左侧菜单CI/CD->Schedules中添加new schedule，这样Gitlab服务器会定时重新运行.gitlab-ci.yml文件来重新发布博客。

1. 在 content/posts 文件夹中新建md文件。
2. md文件的开头以 archetypes/default.md 为模板。

七、Google服务

（一）在Google声明域名

在 search.google.com 通过域名DNS方式，声明对域名的所有权：

1. 记录 “google-site-verification”
2. 域名后台（以namecheap.com为例）：

注意：如果已有同类型的记录，会造成冲突无法完成认证，先删除。

3. 认证通过后，改回原来。

（二）网页上添加Google Search Box

1. 在 Google Custom Search Engine 注册。
   注意：加两项，“yourdomain"和"yourdomain/*”
2. 记录 “Search engine ID”
3. 修改config.toml文件，将"Search engine ID"添加到相应位置。

最后修改于 2024-02-24