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

Learning Hugo

Hugo学习笔记

1: 介绍

1.1: Hugo介绍
1.2: 为什么选择Hugo
1.3: 资料收集

2: 安装

2.1: 安装Hugo
2.2: 快速开始
2.3: 开启HTTPS
2.4: 搜索引擎优化（待更新）
2.5: 增加更多语言的语法高亮

3: 主题

3.1: Hugo主题介绍
3.2: 推荐列表
3.3: academic主题

3.3.1: 更新到2021年最新版本
3.3.2: 重来备忘录
3.3.3: [归档]2019年修改记录

3.4: docsy主题

3.4.1: 搭建站点
3.4.2: 本地化加速
3.4.3: 启用Ugly URL
3.4.4: 启用CSE搜索
3.4.5: Google Analytics
3.4.6: 百度统计
3.4.7: 迁移站点
3.4.8: 更新到最新版本
3.4.9: 重来备忘录

3.5: material-docs主题

1 - 介绍

Hugo的介绍，选择Hugo的理由，以及Hugo的资料收集

1.1 - Hugo介绍

Hugo是什么？Hugo可以用来做什么？

静态网站生成器，专注内容，快速创作。

Hugo是什么？

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

Hugo以速度快著称，号称是世界上最快的网站生成框架。

The world’s fastest framework for building websites

Hugo可以用来做什么？

1.2 - 为什么选择Hugo

为什么我选择了Hugo，而放弃了gitbook/hexo？

非常重要的额外理由：找到了两个很喜欢的主题 academic 和 docsy，分别用于技术博客网站和学习笔记

Hugo的特点

Hugo以速度快著称，号称是世界上最快的网站生成框架。

The world’s fastest framework for building websites

来自1Password的评价

这里有一段来自1Password的对hugo的评价，很有代表性。

内容翻译自 https://gohugo.io/showcase/1password-support/

在1Password，我们过去每个月都会经历一个不同的文档平台：博客引擎，电子书，维基，用Ruby和JavaScript编写的网站生成器。每个方式都有自己的不足。然后我们找到了hugo。我们做了最后一次切换，我们很高兴我们做到了。

并非所有静态站点生成器都是相同的

找到一个能让您的客户，作者，设计师和DevOps团队满意的工具并非易事，但我们通过Hugo进行了管理：

Hugo是静态的。我们是一家安全公司，所以我们坚持静态网站并尽可能地使用它们。我们觉得客户在HTML文件上比在需要强化的复杂服务器上更安全。
Hugo是基于Go的。在1Password我们喜欢Go编程语言，我们很高兴得知Hugo使用了我们的设计师和前端开发人员已经掌握的相同的Go模板语法。
Hugo很快。我们以前的静态站点生成器花费将近一分钟来编译我们的（那时还小得多）站点。开发人员可能已经习惯了这一点，但对于希望看到工作实时预览的作家来说，这并不合适。Hugo在几毫秒内完成了同样的工作，到现在，转瞬之间就可以编译五种语言编写的400多个页面。
Hugo很灵活。感谢Hugo的内容和布局系统，我们能够保留现有的文件和文件夹结构，并在几天内移植整个生产站点。然后我们可以创建以前不可能的新内容类型，比如这些时髦的陈列柜。
Hugo非常适合作家。我们的文档团队已经对Markdown和Git感到满意，并且可以开始为Hugo创建内容而无需停顿。一旦我们添加了短代码，我们的作者就可以通过少量的新语法来使用类似平台盒(platform boxes)的功能来装饰文章。
Hugo有一个惊人的开发者社区。Hugo更新频繁，充满了功能和修复。在我们开发网站的多语言版本时，我们提交了所需功能的PR，并通过@bep和其他人的流程得到了帮助。
Hugo易于部署。 Hugo拥有适量的配置选项，可以适应我们的构建系统而不会太复杂。

我的个人感受

个人技术博客网站的变迁

我的个人技术博客网站，十几年来经历过很多变更，从csdn，blogjava，javaeye，hexo+github page，gitbook一路走来，在2018年2月，开始转换到hugo，迄今整三年。

这些年博客的历程，有兴趣了解的同学可以看看我在2018年改用hugo时写的文章：十年一觉扬州梦，赢得青楼薄幸名

目前的博客网站使用了自行修改订制之后的 academic 主题，非常满意，点击这里可以看到实际效果。

学习笔记

而现在这份Hugo学习笔记则采用的是定制版本的 Google Docsy 主题，后续会将目前大大小小的四五十份学习笔记逐步迁移到 Hugo+Docsy 上来。

对于hugo，个人非常喜爱，上面1Password列出的几点都感同身受。仅从个人感受上说，我觉得hugo优势主要体现在以下方面：

静态文件生成：生成纯静态文件，可以任意找地方托管，无任何特殊依赖。免费的github pages，廉价的虚拟主机，廉价的VPS，都可以轻松完成网站托管。
markdown编写：这是至关重要的一点，在习惯了markdown高效而专注的写作体验之后，markdown的支持成为硬性要求。
使用方便：无论是偏公共性质的技术博客，还是偏私人性质的学习笔记，从内容创作或者学习心得记录的角度，都是“内容为王”！因此，一个样式简单大方的网站，在一次性的安装调试完成之后，后续就应该可以轻松快捷的进行内容创作。
速度！：仅以上述三点而言，hexo和gitbook都表现的很好，两者的功能和主题都非常的丰富。但是，hugo在渲染速度上明显高出太多，尤其是对比gitbook，几乎有几十上百倍的性能差距。当站点内容比较多，比如积攒了几年的博客，或者大量细节展开的学习笔记，gitbook的渲染速度就开始从秒级到十几秒再到分钟级，而变得越来越不可接受。Hugo的速度，是我最终放弃hexo和gitbook的最关键的原因。
Go语言：这是讨人喜欢的一点，当然这会因人而异，nodejs的同学可能更愿意用gitbook。仅从个人感受上说，我对基于go的hugo好感更多。
喜欢的主题：对于hexo、gitbook、hugo，都拥有数以千计的各式主题。而要在众多主题中找到自己的心头好，有时需要一点运气。我自我感觉比较幸运的是：我找到了两个很喜欢的主题，academic 和 docsy，分别用于我的技术博客网站和学习笔记。特点是简单大气，简洁大方，不花俏，不土气，精致而内敛。有特别喜欢的主题，是一个关键的决策依据。

1.3 - 资料收集

收集Hugo的各种资料

官方资料

社区资料

Hugo中文网站：貌似有段时间没有更新了？

学习资料

Hogo handbook: 宋净超(Jimmy Song)同学整理的hugo使用资料
Hugo❤️ China User Group: 宋净超(Jimmy Song)同学组织，有个微信群可以申请加入

2 - 安装

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

2.1 - 安装Hugo

Hugo在多个操作系统下的安装

准备工作

安装golang

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

安装nodejs/npm

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

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

https://nodejs.org/en/download/

Linux下安装nodejs

wget https://nodejs.org/dist/v18.12.0/node-v18.12.0-linux-x64.tar.xz
tar xvf node-v18.12.0-linux-x64.tar.xz
sudo mv node-v18.12.0-linux-x64 /usr/share/nodejs

打开 ~/.zshrc, 添加下来内容,将 /usr/share/nodejs/bin 加入PATH 路径:

export PATH=/usr/share/nodejs/bin:$PATH

完成之后执行version命令检验是否安装成功：

source ~/.zshrc
npm --version

注意这里一定要将 /usr/share/nodejs/bin 加入到 PATH，不然后面安装其他内容后使用时会报错找不到命令，因为通常新安装的命令都会放在 /usr/share/nodejs/bin

安装Hugo

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

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

Linux安装

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

hugo_extended_0.105.0_linux-amd64.deb

deb文件直接安装即可。

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

Mac安装

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

hugo_extended_0.80.0_macOS-64bit.tar.gz

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

cd hugo_extended_0.80.0_macOS-64bit
sudo cp hugo /usr/local/bin/hugo
# 如果想多个hugo版本共存，可以将hugo二进制文件改名
sudo cp hugo /usr/local/bin/hugo2

Windows安装

TODO：暂未尝试，待更新。

安装后设置

验证安装：

$ hugo version
hugo v0.105.0-0e3b42b4a9bdeb4d866210819fc6ddcf51582ffa+extended linux/amd64 BuildDate=2022-10-28T12:29:05Z VendorInfo=gohugoio

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

vi ~/.zshrc
# hugo
alias h='hugo -D -F server --disableFastRender --bind "0.0.0.0"'

hugo命令行参数说明：

-D: 等同--buildDrafts，标记为 Draft 的内容也会一起构建，方便在本地编写和预览新的暂时未发布的内容。
-F: 等同--buildFuture，发布时间为"未来"(即时间比当前时间还要晚)内容也会一起构建，方便在本地编写和预览新的暂时未发布的内容。
--disableFastRender：当内容修改时，进行完整的重新构建，避免预览的内容不够新

安装SCSS

SCSS的安装参考 docsy 的文档：

https://www.docsy.dev/docs/getting-started/#install-postcss

首先需要安装 nodejs，这样才能使用 npm 命令，然后在hugo项目下执行：

% npm install -D --save autoprefixer

+ autoprefixer@9.8.6
added 115 packages from 112 contributors and audited 115 packages in 12.974s

% npm install -D --save postcss-cli

+ postcss-cli@7.1.2
added 1 package from 1 contributor, removed 1 package, updated 18 packages and audited 115 packages in 39.211s

自动发布

以下是jenkins自动生成并发布到nginx的简单脚本：

sh update_academic.sh

# clean 
cd /var/www/skyao/
# 删除所有文件和文件夹，但排除以"learning-"前缀开头的
rm -rf `ls | grep -v "learning-"`
cd /var/lib/jenkins/workspace/skyao.io/

# 需要明确指定baseUrl
hugo --baseUrl="https://skyao.io/" -d "/var/www/skyao/"

2.2 - 快速开始

详细介绍通过Hugo快速开始搭建一个新的站点

新建站点

hugo new site /path/tp/your/site

提示如下：

$ hugo new site learning-cilium
Congratulations! Your new Hugo site is created in /home/sky/work/code/learning/learning-cilium.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/, or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

下载模板

选择喜欢的模板，一般下载方式如下：

cd learning-cilium
git clone git@github.com:digitalcraftsman/hugo-material-docs.git themes/hugo-material-docs

为了快速开始使用，一般模板都会提供一个exampleSite，通常将该目录下的内容都复制到站点跟目录下：

cp -av themes/hugo-material-docs/exampleSite/* .

运行

直接执行server命令就可以启动：

hugo server

通过浏览器访问 http://localhost:1313/ 就可以看内容，由于上面我们采用的是直接复制exampleSite的内容，所以一般此时看到的就是这个模板的example内容。

之后再进行具体的网站设定，模板修改，添加内容等。

提交到github

echo "# learning-cilium" >> README.md
git init
git add -A
git commit -m "first commit"
git remote add origin git@github.com:skyao/learning-cilium.git
git push -u origin master

2.3 - 开启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

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

为了让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很类似。

参考资料

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

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

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

默认支持的语言列表

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

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

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

定制新的语言支持列表

步骤如下：

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

打开这个 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 */

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

打开上面的 URL 地址，在该页面增加需要支持的语言，如:
- HTTP
- Lua
- Makefile
- Rust
- .properties
- Protocol Buffers
- WebAssembly
也可以添加插件
- Line Highlight
- Line Numbers
- Highlight Keywords

点击页面下方的“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 */

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

其他：高亮的参数设置

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

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

3 - 主题

介绍hugo的主题，个人推荐列表，及重度使用的academic和docsy主题

3.1 - Hugo主题介绍

介绍hugo的主题

Hugo有非常丰富的主题。

后面会列出一些个人觉得不错的Hugo主题，然后重点推荐两个我自己在重度用的主题：

academic 主题：用于我的个人博客网站
Docsy 主题：用于我的学习笔记

3.2 - 推荐列表

推荐一些个人觉得不错的Hugo主题

在这里列出一些个人觉得不错的Hugo主题，一方面推荐给有兴趣的同学，另一方面也给自己留个备份。

文档类

官网的分类列表：

https://themes.gohugo.io/tags/documentation/

以下主题觉得还不错的：

Docsy

超级完善的一个文档类主题， google出品，特别适合做开源项目，强烈推荐。

https://github.com/google/docsy

观察了两年，一直在开发维护，最近选择docsy替代了Material Docs。
DocuAPI

类slate风格，带code example列，特别适合API文档和配置文档。

https://themes.gohugo.io/docuapi/

看demo效果相当的不错！！
~Material Docs~

非常漂亮的文档主题，但可惜原作者放弃维护，已经无法在hugo新版本中使用。

https://themes.gohugo.io/material-docs/

不得意，已放弃，改用 docsy
learn

类似gitbook。

https://themes.gohugo.io/hugo-theme-learn/
Kube

带blog/faq，适合用于小型项目。

https://themes.gohugo.io/kube/

3.3 - academic主题

介绍hugo的docsy主题，使用方式和订制化

academic特别适合搭建内容相对比较丰富的网站

主题介绍

academic是一个特别适合搭建内容相对比较丰富的网站的主题，如果我们hugo网站的内容不仅仅是博客，还有其他好几种样式的内容，那么academic会是一个很不错的选择。此外，academic主题简洁大方，也适合作为一个稍有规模的正式网站。

官网介绍：https://academic-demo.netlify.app/
我用academic主题搭建的个人技术博客网站: https://skyao.io

3.3.1 - 更新到2021年最新版本

更新到2021年最新版本，详细介绍hugo的academic主题的使用方式和订制化

2021年版本，从最新的 academic 主题开始更新个人博客网站。

准备工作

准备自己的模版仓库

fork https://github.com/wowchemy/starter-hugo-academic 仓库到自己的 github 账号，不要用官方的 generated，那样会生成一个全新的仓库，以后就不好从上流更新内容了。
clone 到本地
在本地从 master 分支处 checkout 一个 skyao. io 分支，以后所有的改动都在这个分支上进行

准备网站仓库

复制 starter-hugo-academic 仓库下的 exampleSite 目录为新的文件夹 newsite，作为新站点的基础代码
进入 newsite 目录，运行 hugo server ，即可启动 hugo ，看到网站

在这个目录下进行内容修改，等网站基本成型之后，在和原来的 skyao.io 网站内容融合，尽量保留原有仓库的历史提交记录。

配置网站

修改 languages.yaml

将默认语言修改为中文，暂时不需要支持多语言。

# Default language
#en:
  #languageCode: en-us

zh:
  languageCode: zh-Hans
  title: 敖小剑的博客

修改config.yaml

将默认语言修改为中文:

############################
## LANGUAGE
############################

defaultContentLanguage: zh
hasCJKLanguage: true
defaultContentLanguageInSubdir: false

其他修改：

title: 敖小剑的博客 # Website name
baseurl: 'https://skyao.io/' # Website URL

# 分页数量从10修改为20
paginate: 20

修改 menus.yaml

这是默认的内容：

main:
  - name: Demo
    url: '#about'
    weight: 10
  - name: Posts
    url: '#posts'
    weight: 20
  - name: Projects
    url: '#projects'
    weight: 30
  - name: Talks
    url: '#talks'
    weight: 40
  - name: Publications
    url: '#featured'
    weight: 50
  - name: Courses
    url: courses/
    weight: 60
  - name: Contact
    url: '#contact'
    weight: 70

修改为：

main:
  - name: 首页
    url: '#about'
    weight: 10
  - name: 演讲分享
    url: '#talks'
    weight: 20
  - name: 出版作品
    url: '#featured'
    weight: 30
  - name: 技术博客
    url: '#posts'
    weight: 40
  - name: 开源项目
    url: '#projects'
    weight: 50
  - name: 学习笔记
    url: learning/
    weight: 60
  - name: Courses
    url: courses/
    weight: 60
  - name: 和我联系
    url: '#contact'
    weight: 70

修改params.yaml

Contact 信息修改如下：

# Appearance
# 保持和原来的主题一致
theme: 1950s

# Contact (edit or remove options as required)

email: aoxiaojian@hotmail.com
address:
  street: 天河区
  city: 广州市
  region: 广东省
  postcode: '510600'
  country: 中国
  country_code: CN
contact_links:
  - icon: twitter
    icon_pack: fab
    name: DM Me
    link: 'https://twitter.com/SkyAoXiaojian'

删除部分不需要的文件

Netlify.toml
static/media/* 和 static/uploads/*

首页修改

去掉不需要的内容

删除 accomplishments.md
删除 experience.md
删除 hero.md
删除 demo.md
删除 hero-academic.png
删除 gallery.md
删除 privacy.md
删除 terms.md

关闭：

demo.md

作者信息修改

修改 content/author/admin 目录下的 _index.md 文件，这些内容会直接显示在首页开头部分。

替换 avatar.jpg 文件为自己的头像。

about.md

title: 简介

其他信息在作者信息里面。

其他信息修改

主题修改

fork 主题仓库

fork github.com/wowchemy/wowchemy-hugo-modules 仓库，clone 到本地。

后续需要有些需要是需要修改主题文件才能实现的。

在 Hugo 项目下，修改 go.mod 文件：

其原始内容是:

require (
	github.com/wowchemy/wowchemy-hugo-modules/v5 v5.3.0
)

为了让这个依赖指向我们fork的仓库，需要增加 replace：

require (
	github.com/wowchemy/wowchemy-hugo-modules/v5 v5.3.0
)

replace github.com/wowchemy/wowchemy-hugo-modules/v5 => /Users/sky/work/code/skyao/hugo-academic
replace github.com/wowchemy/wowchemy-hugo-modules/wowchemy/v5  => /Users/sky/work/code/skyao/hugo-academic/wowchemy

执行命令 hugo mod get -u 更新 hugo 依赖的 module，之后就可以修改 fork 的主题文件仓库，然后在 hugo 项目这边运行 hugo server 就可以生效了。

参考 Use Hugo Modules | Hugo (gohugo.io)

layout文件修改

wowchemy/layouts/partials/site_footer.html，修改footer，删除原来的内容，简单点。

<!--
   <p class="powered-by">
     {{ $is_sponsor := site.Params.i_am_a_sponsor | default false }}
     {{ $hide_published_with_footer := site.Params.power_ups.hide_published_with | default true }}
@@ -49,4 +50,7 @@
       {{ $i18n_published_with | markdownify | emojify }}
     {{ end }}
   </p>
-->

<p class="powered-by">© 2021 skyao.io All Rights Reserved</p>

修改 wowchemy/layouts/partials/book_layout.html ，去掉最后修改时间的显示，页面简洁一些：

        <div class="body-footer">
          <!--
          <p>{{ i18n "last_updated" }} {{ $.Lastmod.Format site.Params.date_format }}</p>
          -->

主题模板调整

列表页面的图片显示

academic 主题，在 post、publication、talk 等几个列表显示图片时，会按照 808*455 的长宽进行处理，而我之前设置的图片都是长条形，因此显示效果和之前版本差别好大，不够美观，因此考虑修改模板，将图片预处理的长宽比修改为 808*210 （等比1920x500计算而来）。

修改 wowchemy/layouts/partials/li_card.html

  {{ $image := .Fill (printf "808x455 %s" $anchor) }}
  
  {{ $image := .Fill (printf "808x210 %s" $anchor) }}

在新版本中，如果需要显示图片，只需要将图片命名为 featured.jpg 或者 featured.png ，放在 md 文件同目录即可。不需要再在 md文件中设置 header image了。比较方便。

横幅图片的显示

academic 主题，在 post、publication、talk 等几个 single 页面显示 featured 图片时，是放在主题内容中的，宽度很有限。远没有将图片拉宽到占据整个页面宽度那样的视觉效果好。因此考虑修改过来。

从源代码中看到，图片可以设置多种摆放的方式，其中默认 1 是和主体内容等宽。如果设置为3 ，则就可以实现占据整个页面宽度。

因此可以在每个需要改动的页面设置:

image:
  placement: 3

方便起见，可以在 _index.md 文件设置：

cascade:
- type: "publication"
- image:
    placement: 3

修改 wowchemy/layouts/partials/page_header.html ，将这一段的位置往下挪，让图片显示在最前面，这样图片宽度占据全屏宽度，就直接和导航条无缝连接了。

<div class="article-container pt-3">
  <h1>{{ $title }}</h1>

  {{ with $page.Params.subtitle }}
  <p class="page-subtitle">{{ . | markdownify | emojify }}</p>
  {{end}}

  {{ partial "page_metadata" (dict "page" $page "is_list" 0 "share" true) }}
  {{ partial "page_links_div.html" $page }}
</div>

图片的样式默认设置了 “mt-4 mb-4”，导致图片的上下都会留空白，这样顶部就不能和导航条融为一体了，因此删除 mt-4 ，顶部不留空白：

<div class="article-header {{$image_container}} featured-image-wrapper mb-4" style="max-width: {{$image.Width}}px; max-height: {{$image.Height}}px;">
  <div style="position: relative">
    <img src="{{ $image.RelPermalink }}" alt="{{ with $.Params.image.alt_text }}{{.}}{{ end }}" class="featured-image">
    {{ with $.Params.image.caption }}<span class="article-header-caption">{{ . | markdownify | emojify }}</span>{{ end }}
  </div>
</div>

不显示作者名

个人网站，所有的作者都是自己，没有必要到处显示了，不显示作者信息让页面保持简洁。

修改 wowchemy/layouts/partials/page_metadata.html ，注释掉下面这段内容：

  <!--
  {{/* If `authors` is set and is not empty. */}}
  {{ if $page.Params.authors }}
  {{ $authorLen := len $page.Params.authors }}
  {{ if gt $authorLen 0 }}
  <div>
    {{ partial "page_metadata_authors" $page }}
  </div>
  {{ end }}
  {{ end }}
  -->

统一显示阅读时长

默认只在 post 类型的页面上显示阅读时长，publication等是不显示的，感觉还是都显示比较好。

修改 wowchemy/layouts/partials/page_metadata.html ，将下面这段内容中的 post 判断删除：

{{ if and (eq $page.Type "post") (not (or (eq site.Params.reading_time false) (eq $page.Params.reading_time false))) }}
<span class="middot-divider"></span>
<span class="article-reading-time">
  {{ $page.ReadingTime }} {{ i18n "minute_read" }}
</span>
{{ end }}

修改为：

 
{{ if not (or (eq site.Params.reading_time false) (eq $page.Params.reading_time false)) }}
  <span class="middot-divider"></span>
  <span class="article-reading-time">
    {{ $page.ReadingTime }} {{ i18n "minute_read" }}
  </span>
  {{ end }}

如果不想显示阅读时长，可以在单独的页面上进行控制。

外观定制

更改网站图标，将图标 png 文件放在 assets/media/ 目录下：

参考：https://wowchemy.com/docs/getting-started/customization/#website-icon

本地化加速

类似在 docsy 中的做法。

3.3.2 - 重来备忘录

每次重新安装系统之后都不得不从头来一次，为了方便，记录一下全过程以备参考:

常规流程

mkdir -p ~/work/code/skyao

# hugo-academic.git
cd ~/work/code/skyao
git clone git@github.com:skyao/hugo-academic.git
cd hugo-academic
git checkout skyao.io

# skyao.io.git
cd ~/work/code/skyao
git clone git@github.com:skyao/skyao.io.git
cd skyao.io

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

# run hugo server
h

备注：偶尔遇到git clone skyao.io 仓库时有文件意外损坏，导致build失败的情况，删除目录重新clone即可。

m1上遇到的问题

遇到问题：

$ h              
WARN 2022/03/06 20:55:22 Module "github.com/wowchemy/wowchemy-hugo-modules/wowchemy/v5" is not compatible with this Hugo version; run "hugo mod graph" for more information.
Error: from config: failed to resolve output format "WebAppManifest" from site config

参考资料：

解决方法，修改 config/_default/config.yaml 中的 outputs 内容为：

outputs:
  # 默认内容为：
  #home: [HTML, RSS, JSON, WebAppManifest, headers, redirects]
  # 去掉 WebAppManifest
  home: [HTML, RSS, JSON, headers, redirects]
  section: [HTML, RSS]

然后执行:

hugo mod clean
hugo mod get -u ./...
hugo mod tidy

执行再执行 h 就可以成功了，和上面帖子中将 WebAppManifest 加回去还可以用不同，我如果把 WebAppManifest 加进去，只会继续抱同样的错。暂时先去掉 WebAppManifest吧。

备注：这个错误只在 m1 的 macbook 上遇到，intel macos 和 linux 下没这个问题。

3.3.3 - [归档]2019年修改记录

详细介绍hugo的academic主题，使用方式和订制化

以下内容是2019年更新的，后续因为版本变动太大，已经没有参考价值，放在这里归档。

主题介绍

官网介绍：https://themes.gohugo.io/academic/
我用academic主题搭建的个人技术博客网站: https://skyao.io

准备工作

git仓库准备

以建立skyao.io这个网站为例，fork github项目：

https://github.com/gcushen/hugo-academic: 修改仓库名为hugo-academic，这是自行订制的主题仓库，加cn后缀名以示区别。
https://github.com/sourcethemes/academic-kickstart: 修改仓库名为skyao.io，这是存放站点内容的仓库，为了方便起见，从官方的kickstart仓库开始改起，也方便未来保持更新。

备注：实际证明，academic的版本变化非常大，fork出来之后，再修改，到升级版本时到处是冲突，极易出错，很难正确处理。最后还是不得不从头来过：取到最新版本，然后手工将原有的改动重新再做一遍。

kickstart 项目就没有必要再fork了，hugo-academic 还是需要 fork 的。

本地仓库准备

clone下来 kickstart 的仓库到本地：

# 本地准备好academic主题仓库
git clone https://github.com/skyao/hugo-academic.git
# 直接获取kickstart的内容作为建站的基础
git clone https://github.com/sourcethemes/academic-kickstart.git skyao.io
cd skyao.io/
rm -rf .git .gitmodules
rm -r themes/academic/

修改.gitignore文件内容如下：

.*
!.gitignore
public/
themes/

修改update_academic.sh文件内容如下：

#!/bin/bash

if [ ! -d "themes" ];then
  echo "No themes directory, create it"
  mkdir themes
fi

if [ -d "themes/academic" ];then
  echo 'Find directoy "themes/academic", update by "git pull"'
  cd themes/academic
  git pull
  cd ../../
else
  echo 'Directoy "themes/academic" not found, do "ln -s"'
  cd themes
  ln -s ../../hugo-academic academic
  cd ../
fi

执行命令 sh update_academic.sh 获取 academic 主题文件(实际是一个ln过程)。此时themes/academic是我们订制的主题内容，此时两个git仓库都可以分别提交内容，而且实时生效，非常方便本地修改。

创建网站

使用 exampleSite 初始化

删除｀skyao.io｀目录下的config.toml文件和content/static目录，然后从｀themes/academic/exampleSite｀下的这三个文件和目录复制到｀skyao.io｀目录下。执行hugo server命令，就可以通过浏览器访问 http://localhost:1313/ 看到示例站点。

我们从这个基础开始进行修改和订制。

修改配置

注意新版本的hugo将原来的单个config.toml配置文件拆分为多个配置文件，这些配置文件在 config/_default 目录下。

修改config.toml文件

title = "敖小剑的博客"
copyright = "skyao.io &copy; 2019"
googleAnalytics = "17048c9d4209e5d08a9ae5b0b4160808"

# 修改默认语言，需要对应的在languages.toml添加中文
defaultContentLanguage = "zh"
hasCJKLanguage = true

paginate = 20

修改languages.toml

先只替换默认语言为中文，暂时不启用多语言版本。

# 注释掉en
#[en]
#  languageCode = "en-us"

# 添加中文
[zh]
  languageCode = "zh-Hans"

如果要调整页面上的字眼，需要修改主题文件中的 i18n 文件，如themes/academic/i18n/zh.yaml。

如果要修改 publication_types 的显示，需要参考 themes/academic/layouts/partials 下 pub_types.html 的内容，在 themes/academic/i18n/zh.yaml 文件中加入对应的内容：

- id: pub_uncat
  translation: 未分组
- id: pub_conf
  translation: 会议记录
- id: pub_journal
  translation: 期刊文章
- id: pub_manuscript
  translation: 手稿
- id: pub_report
  translation: 技术报告
- id: pub_book
  translation: 书籍
- id: pub_book_section
  translation: 书籍摘抄

修改params.toml

color_theme = "1950s"

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

# 这个还不知道该如何设置
sharing_image = ""

twitter = "SkyAoXiaojian"

date_format = "2006-01-02"
time_format = "15:04"

email = "aoxiaojian@hotmail.com"
phone = ""
address = "广州市天河区广电平云广场B塔15楼"
office_hours = ""

contact_links = [
  {icon = "twitter", icon_pack = "fab", name = "DM Me", link = "https://twitter.com/SkyAoXiaojian"},
  # {icon = "skype", icon_pack = "fab", name = "Skype Me", link = "skype:echo123?call"},
  # {icon = "keybase", icon_pack = "fab", name = "Chat on Keybase", link = "https://keybase.io/"},
  # {icon = "comments", icon_pack = "fas", name = "Discuss on Forum", link = "https://discourse.gohugo.io"},
  # {icon = "telegram", icon_pack = "fab", name = "Telegram Me", link = "https://telegram.me/@Telegram"},
  ]
  
  reading_time = false
  comment_count = false
  
  [publications]
  date_format = "2006-01-02"

修改menus.toml

[[main]]
  name = "首页"
  url = "#about"
  weight = 1

[[main]]
  name = "演讲分享"
  url = "/talk/"
  weight = 2

[[main]]
  name = "出版作品"
  url = "/publication/"
  weight = 3

[[main]]
  name = "技术博客"
  url = "/post/"
  weight = 4

[[main]]
  name = "开源项目"
  url = "#projects"
  weight = 5

[[main]]
  name = "学习笔记"
  url = "/learning/"
  weight = 6

[[main]]
  name = "内容标签"
  url = "#tags"
  weight = 7

[[main]]
  name = "和我联系"
  url = "#contact"
  weight = 8

订制首页

需要修改的文件在 content/home 目录下。

关闭部分不需要的内容（设置active = false）：

accomplishments.md
experience.md
skills.md
teaching.md

about.md

title = "简介"

然后修改 author/admin 下的文件，如替换头像，修改_index.md:

name = "敖小剑"
role = "中年码农"
organizations = [ { name = "Dreamfly.io", url = "https://dreamfly.io" } ]
bio = "我目前研究的方向主要在微服务/Microservice、服务网格/Servicemesh、无服务器架构/Serverless等和云原生/Cloud Native相关的领域，欢迎交流和指导"
email = "aoxiaojian@hotmail.com"
interests = [
    "微服务/Micro Service",
    "服务网格/Service Mesh",
    "无服务器架构/Serverless",
    "云原生/Cloud Native",
    "敏捷/DevOps"
]

[[education.courses]] # 删除

## 图标的代码需要在 https://fontawesome.com 网站上查找
[[social]]
  icon = "envelope"
  icon_pack = "fas"
  link = "mailto:aoxiaojian@hotmail.com"  # For a direct email link, use "mailto:test@example.org".

[[social]]
  icon = "twitter"
  icon_pack = "fab"
  link = "https://twitter.com/SkyAoXiaojian"

[[social]]
  icon = "github"
  icon_pack = "fab"
  link = "https://github.com/skyao"

[[social]]
  icon = "git"
  icon_pack = "fab"
  link = "//legacy.gitbook.com/@skyao"

[[social]]
  icon = "weibo"
  icon_pack = "fab"
  link = "//weibo.com/aoxiaojian"

[[social]]
  icon = "youtube"
  icon_pack = "fab"
  link = "//www.youtube.com/channel/UCKeIYzzIeOtVR1iSfAdRBqQ"
  
  
增加个人简介

hero.md

暂时禁用，后面再来设置

title = "SOFAMesh"
overlay_img = "projects/sofamesh-wide.jpg" # 记得把图片放到static/img/下

# 其他内容酌情修改

hero_carousel.md 是另一个版本的hero，横屏，可以多个话题滑动，效果更好的感觉。后面再整理。

posts.md

title = "技术博客"
count = 10

view = 2

修改 content/posts/_index.md 文件：

title = "技术博客"
view = 3

publications.md

title = "出版作品"
count = 5
weight = 30

view = 3
exclude_featured = true

修改 content/publications/_index.md 文件：

title = "出版作品"
view = 3

publications_featured.md

title = "特别推荐"

tags.md

title = "内容标签"

projects.md

title = "开源项目"

contact.md

title = "和我联系"

talks.md

title = "演讲分享"
count = 5
weight = 20

修改talks_selected.md:

title = "下一站"
subtitle = "近期活动，欢迎关注"

修改post

修改 content/posts/_index.md

title = "技术博客"

# 在页面 http://localhost:1313/post/ 显示一张图片
[header]
image = ""
caption = ""

修改project

project没有要修改的内容。

修改publications

修改 content/publication/_index.md

title = "最近发表"
[header]
image = ""
caption = ""

增加 learning

新版本提供了 content/tutorials 的实例，不过没有挂在首页，不容易发现。

官方说明是适合用于：

项目或者软件文档
在线课程
教程

我这次用它来记录我的学习笔记，因为数量繁多不好整理，一直都没有放在个人网站上。

具体修改内容如下：

重命名 content/tutorials 为 content/learning，通过 http://localhost:1313/learning/ 可以访问

由于目录被改名，所以左边的菜单报错，修改修改example.md中

[menu.learning]	# 将menu.tutorial修改为menu.learning
  parent = "Example Topic"
  weight = 1

修改_index.md:

[menu.learning] # 将menu.tutorial修改为menu.learning
  name = "Overview"
  weight = 1

菜单恢复正常

在顶部的导航条中增加链接

修改config.toml，增加菜单：

[[menu.main]]
  name = "学习笔记"
  url = "/learning/"
  weight = 5

修改themes/academic/layouts/partials/docs_layout.html，注释掉一下内容：
```

```
不直接显示最后修改时间在页面上，这样界面清爽一些。

slides功能

在content/slides下发现一个 example-slides.md 文件，用浏览器打开下面的地址：

http://localhost:1313/slides/example-slides/

发现原来是一个用markdown书写slides的功能，很有意思，稍后研究。

图标和其他文件设置

复制 icon.png / icon-192.png 到 static/img 目录下。

复制 baidu_verify_××××.html 和 google××××.html 到 static 目录下。

优化

关闭google地图

首页的google地图现实，太影响页面打开速度。最后选择关闭。修改config.toml:

  map = 0 # 最后还是决定关闭地图现实，太影响页面打开速度

去掉github项目的star显示

在hero页面上，默认设置会去取github项目的star数量，同样非常的拖累整体速度。还是去掉吧，修改文件content/home，删除以下内容：

  <a id="academic-release" href="https://github.com/alipay/sofa-mesh/releases" data-repo="alipay/sofa-mesh">
  Latest release <!-- V -->
  </a>
<div class="mt-3">
  Star
</div>
<script async defer src="/local/buttons.github.io/buttons.js"></script>

改google analytics为百度统计

修改 academic/layouts/partials/header.html，将下面原来用于google analytics的内容：

  {{ if not .Site.IsServer }}
  {{ if .Site.GoogleAnalytics }}
    <script>
      window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
      ga('create', '{{ .Site.GoogleAnalytics }}', 'auto');
      {{ if .Site.Params.privacy_pack }}ga('set', 'anonymizeIp', true);{{ end }}
      ga('require', 'eventTracker');
      ga('require', 'outboundLinkTracker');
      ga('require', 'urlChangeTracker');
      ga('send', 'pageview');
    </script>
    <script async src="//www.google-analytics.com/analytics.js"></script>
    {{ if ($scr.Get "use_cdn") }}
    {{ printf "<script async src=\"%s\" integrity=\"%s\" crossorigin=\"anonymous\"></script>" (printf $js.autotrack.url $js.autotrack.version) $js.autotrack.sri | safeHTML }}
    {{ end }}
  {{ end }}
  {{ end }}

修改为百度统计的内容：

  {{ if not .Site.IsServer }}
  {{ if .Site.GoogleAnalytics }}
	<script>
	var _hmt = _hmt || [];
	(function() {
	  var hm = document.createElement("script");
	  hm.src = "https://hm.baidu.com/hm.js?{{ .Site.GoogleAnalytics }}";
	  var s = document.getElementsByTagName("script")[0];
	  s.parentNode.insertBefore(hm, s);
	})();
	</script>
  {{ end }}
  {{ end }}

本地文件加速

使用中，发现网页装载速度不是很好，而且有时无法访问。检查后发现问题出现在页面上的一些静态文件下载上，使用的路径居然是https://cdnjs.cloudflare.com/××。

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha512-6MXa8B6uaO18Hid6blRMetEIoPqHf7Ux1tnyIQdpt9qI5OACx7C+O3IVTr98vwGnlcg0LOLa02i9Y1HpVhlfiw==" crossorigin="anonymous">

cloudflare网站是在国外，访问速度慢，而且非常不稳定：经常被墙。导致页面加载的速度慢，有时还会出现无法打开页面的问题（被墙）。解决的方式就是将这些文件放在网站本地，从而避开这个问题。

具体做法：

修改 themes/academic/data/assets.toml，将类似https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js 的地址修改为 /local/cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js
修改 fonts.googleapis.com/css.css 文件，用 /local/fonts 替换 https://fonts ，将原来访问https://fonts.gstatic.com的地址指到本地。
修改 themes/academic/ 下的文件，将类似 //cdnjs.cloudflare.com 的地址替换为 /local/cdnjs.cloudflare.com
- layouts/partials/header.html
- layouts/partials/footer.html
- layouts/partials/cookie_consent.html
- layouts/slides/baseof.html
然后将上述这些地址所指向的文件存放在static/img/local目录下，最大的工作量在这里。

最终的目标是实现下面第一个地址修改为第二个地址。

https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js
https://127.0.0.1:1313/local/cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js

小技巧：

用chrome浏览器的开发工具，看network，就知道有哪些文件是走remote访问了
find -type f -exec grep -H "//cdn" {} \; 这样的命令可以方便的查找存在问题的文件

主题模板调整

0.54 版本的 academic 主题，在 post、publication、talk 等几个列表显示时，都不再提供图片显示，效果和之前版本差别好大，因此考虑修改模板。

academic/layouts/partials/widgets

talk

修改 themes/academic/layouts/partials/talk_li_card.html 文件。

下面的内容，只显示日期，不显示具体时间。然后显示publication信息

  <div class="talk-metadata" itemprop="startDate">
    {{ $date := .Params.time_start | default .Date }}
    {{ (time $date).Format $.Site.Params.date_format }} @ {{ .Params.publication }}
  </div>

原有的这段内容删除，非常难看：

{{ (time $date).Format $.Site.Params.date_format }}
    {{ if not .Params.all_day }}
      {{ (time $date).Format ($.Site.Params.time_format | default "3:04 PM") }}
      {{ with .Params.time_end }}
        &mdash; {{ (time .).Format ($.Site.Params.time_format | default "3:04 PM") }}
      {{ end }}
    {{ end }}

删除一下内容，新版本的 featured image 的显示丑的没法忍：

  {{ $resource := (.Resources.ByType "image").GetMatch "*featured*" }}
  {{ $anchor := .Params.image.focal_point | default "Smart" }}
  {{ with $resource }}
  {{ $image := .Fill (printf "918x517 q90 %s" $anchor) }}
  <div>
    <a href="{{ $.RelPermalink }}">
      <img src="{{ $image.RelPermalink }}" class="article-banner" itemprop="image" alt="">
    </a>
  </div>
  {{end}}

将旧版本的横幅图片显示搬回来，在上面位置加入如下内容：

  {{ if .Params.image_preview }}
    {{ .Scratch.Set "image" .Params.image_preview }}
  {{ else if .Params.header.image }}
    {{ .Scratch.Set "image" .Params.header.image }}
  {{ end }}
  {{ if .Scratch.Get "image" }}
  <div>
    <a href="{{ .RelPermalink }}">
      {{ $img_src := urls.Parse (.Scratch.Get "image") }}
      {{ if $img_src.Scheme }}
        <img src="{{ .Scratch.Get "image" }}" class="article-banner" itemprop="image">
      {{ else }}
        <img src="{{ "/img/" | relURL }}{{ .Scratch.Get "image" }}" class="article-banner" itemprop="image">
      {{ end }}
    </a>
  </div>
  {{ end }}

publication

修改 themes/academic/layouts/partials/publication_li_card.html 文件。

同样去掉featured images的代码，也同样将原来的横幅图片显示搬回来。

然后作者信息在最上面，有些不好看，将这行移动到下面一点的位置：

{{ partial "page_metadata" (dict "content" $ "is_list" 1) }}

post

修改 themes/academic/layouts/partials/post_li_card.html 文件。

同样去掉featured images的代码，也同样将原来的横幅图片显示搬回来。

project

暂时还不清楚如何设置，后面再弄。

leanging

学习笔记中，0.54 版本不再显示 header images了，改回来。

需要修改 themes/academic/layouts/partials/doc_layout.html 文件，加入

{{ partial "header_image.html" . }} 这一行代码：

      <article class="article" itemscope itemtype="http://schema.org/Article">

        {{ partial "header_image.html" . }}

        <div class="docs-article-container">

然后将老版本的 header_image.html 文件复制到 themes/academic/layouts/partials/ 目录下。

3.4 - docsy主题

介绍hugo的docsy主题，使用方式和订制化

docsy主题非常适合用于开源项目，支持文档和博客。我主要用它来做学习笔记，替代年旧失修的meterial-docs主题。

主题介绍

docsy 主题官网：

https://github.com/google/docsy

这个主题非常适合用于开源项目，支持文档和博客。

我主要用它来做学习笔记，自行修改和定制。

3.4.1 - 搭建站点

搭建基于docsy主题的站点

git submodule方式在项目比较多时不方便，改用软链接

安装hugo的extended版本

docsy主题和普通的hugo主题不同，需要使用到hugo的 extended 版本。具体安装方式请见前面的章节：

安装

准备example文件

将 docsy 主题文件的示例项目clone到本地：

git clone git@github.com:google/docsy-example.git

进入docsy目录下拉取 docsy 依赖的 submodule ：

cd docsy
git submodule update --init --recursive

子模组 'themes/docsy'（https://github.com/google/docsy）已对路径 'themes/docsy' 注册
正克隆到 '/Users/sky/work/code/learning2/docsy-example2/themes/docsy'...
Connection to github.com port 22 [tcp/ssh] succeeded!

子模组路径 'themes/docsy'：检出 '976ee59c947a153a5c4fe9adc620b32684505d73'
子模组 'assets/vendor/Font-Awesome'（https://github.com/FortAwesome/Font-Awesome.git）已对路径 'themes/docsy/assets/vendor/Font-Awesome' 注册
子模组 'assets/vendor/bootstrap'（https://github.com/twbs/bootstrap.git）已对路径 'themes/docsy/assets/vendor/bootstrap' 注册
正克隆到 '/Users/sky/work/code/learning2/docsy-example2/themes/docsy/assets/vendor/Font-Awesome'...
Connection to github.com port 22 [tcp/ssh] succeeded!

正克隆到 '/Users/sky/work/code/learning2/docsy-example2/themes/docsy/assets/vendor/bootstrap'...
Connection to github.com port 22 [tcp/ssh] succeeded!
子模组路径 'themes/docsy/assets/vendor/Font-Awesome'：检出 '951a0d011f8c832991750c16136f8e260efa60b5'
子模组路径 'themes/docsy/assets/vendor/bootstrap'：检出 'a716fb03f965dc0846df479e14388b1b4b93d7ce'

然后安装SCSS：

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

最后执行：

hugo server

用浏览器打开 http://localhost:1313/ 就可以看到效果了。

特别：软链接主题文件

我用 docsy 来作为学习笔记的主题，由于学习笔记有几十份之多（虽然很多笔记只有一点点内容），如果每个笔记都用 git submodule 机制，clone和更新的维护量太大。

因此我才用了为 docsy 主题文件创建软链接的方式，放弃 git submodule 机制，具体做法是：

将 docsy 主题文件clone到本地的 docsy 仓库：
```
git clone git@github.com:google/docsy.git
```

进入docsy目录下拉取 docsy 依赖的 submodule ：

cd docsy
git submodule update --init --recursive

注意如果不拉取 submodule，在运行时会因为缺少文件而报错，如：

Start building sites … 
Built in 62 ms
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): SCSS processing failed: file "stdin", line 6, col 1: File to import not found or unreadable: ../vendor/bootstrap/scss/bootstrap.

删除 docsy-example 仓库下原有的 theme 目录和 .gitmodule 文件
```
rm -rf themes
rm .gitmodule
```
在 docsy-example 仓库下创建到 docsy 仓库的软链接
```
mkdir themes
cd themes
ln -s ../../docsy .
```

这样就可以让几十份学习笔记同时依赖一份 docsy 模版文件，当 docsy模版文件内容发生变化时，所有的学习笔记都可以借助于软链接而同时得到更新。

重来备忘录

每次重新安装系统之后都不得不从头来一次，为了方便，记录一下全过程以备参考：

# 准备目录
mkdir -p ~/work/code/learning
cd ~/work/code/learning

# docsy.git
git clone git@github.com:skyao/docsy.git
cd docsy
git submodule update --init --recursive
npm install -D --save autoprefixer
npm install -D --save postcss-cli
cd ..


# build script
git clone git@github.com:skyao/docsy-example.git
cp -r docsy-example docsy-example-build
cd docsy
git checkout learning-202108
cd ..

cd docsy-example-build
git checkout build
cp clone.sh init.sh server.sh addremote.sh ../
cd ..

sh clone.sh hugo
sh server.sh hugo

3.4.2 - 本地化加速

将docsy主题的静态文件本地化来加速装载速度避免被墙

在国内网络环境的实际情况下，静态文件的装载速度非常慢，有些甚至被墙，导致页面访问困难，此时需要做本地化

静态文件本地化的背景

在docsy模版中，大量使用 css/js 等静态文件，这些文件很多是直接使用url链接访问的，比如：

https://cdn.jsdelivr.net/gh/rastikerdar/vazir-font@v27.0.1/dist/font-face.css
https://cse.google.com/cse.js
https://code.jquery.com/jquery-3.5.1.min.js
https://unpkg.com/lunr@2.3.8/lunr.min.js
https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js
https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js
https://cdn.jsdelivr.net/npm/mermaid@8.8.1/dist/mermaid.min.js

在国内网络环境的实际情况下，这些文件下载的速度非常慢，有些甚至被墙，导致我们网站页面在不科学上网的情况下速度很慢，甚至打不开。

解决的方法就是将这些静态文件"本地化":

将静态文件下载下来作为网站内容的一部分发布
修改文件地址指向本地文件

具体做法如下：

步骤一：找出网络访问的文件

打开浏览器的开发工具，如chrome的"开发者工具"，然后访问使用docsy的页面。

在network下可以看到访问的文件列表：

步骤二：下载到docsy static目录下

将这些文件下来下来，存放到 docsy 模版项目根目录下的 static/local 目录下，以文件 https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js 为例：

mkdir local
cd local
wget -x https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js

wget -x 会在local目录下建立和url中路径一模一样的多层目录，上面的命令执行完成之后，文件就被下载并保存为docsy/static/local/stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js。

将发现的网络文件安装上面的方式逐个下载并保存到 static/local 目录下。

步骤三：修改文件路径指向本地化文件

需要找出来是哪些文件中存在这样的网络路径，可以在根目录下执行查找命令来看到底是哪个文件引用了网络地址文件 https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js：

cd docsy/layout
find . -type f -exec grep -Hn 'bootstrap.min.js' {} \;

./partials/scripts.html:3:<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>

然后我们打开这个文件，将路径https:// 修改为 /local/ 就可以了。这样 bootstrap.min.js 文件最终的网络访问地址会是 https:/localhost:1313/local/stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js。

修改的文件比较多，有兴趣同样操作的同学可以参考我的这次修改记录：

https://github.com/skyao/docsy/commit/70f0f413b0da4545eb3ae9f1d63d52edaae9ba78

备注： Google CSE 相关的文件不能本地化，否则会在使用时报错 Unauthorized access to internal API。上面的文件列表后来和cse相关的改动都回滚了。

优化总结

静态文件经过本地化优化之后，网站访问速度会有质的提升。

比较头疼的是，每次升级主题版本，都会有大量的静态文件变化，通常是更新版本，因此不得不将上面的优化工作再执行一次。

特别补充：以子目录发布

上述优化完成后，一般情况都没有问题，但是有一种情况，即当前项目并不是作为站点的根目录发布，而是放在某个站点的子目录下时，就会出现问题。

典型如我用 docsy 做学习笔记，几十份学习笔记不可能每个都开一个网站，即使是用子域名也难于维护。因此我用了最简单的方式：每个学习笔记单独存放在一个独立的子目录下。

此时在nginx下发布时需要指定 baseUrl，比如 /var/www/skyao/ 目录下存放的是我的技术博客的内容，访问地址是 https://skyao.io，那么现在这份hugo学习笔记的发布的地址就是 /var/www/skyao/learning-hugo ，而访问地址则是 https://skyao.io/learning-hugo/。下面是构建脚本示意：

rm -rf public
hugo --baseUrl="https://skyao.io/learning-hugo/"

rm -rf /var/www/skyao/learning-hugo
cp -r public /var/www/skyao/learning-hugo

这种以子目录形式发布内容，在实践中会遇到问题，关键在于： “/” 这个根目录绝对路径的使用。在 baseUrl="https://skyao.io/learning-hugo" ，/目录会表示为 https://skyao.io/，而不是 https://skyao.io/learning-hugo ，导致很多路径失效。

通过chrome的开发者工具，查看网络访问时就能看到，本来以 / 开头预期访问地址是 https://skyao.io/learning-hugo/local/***的文件，因为地址被理解为 https://skyao.io/local/*** 而报错404。

解决的方式之一是修改 config.toml 文件，加入以下配置:

# 之前已经配置了 uglyurls = true
uglyurls = true 
# 现在要加入的新配置
relativeURLs = true

hugo官网对 relativeURLs参数的解释是：启用后可使所有使用相对路径的URL修改为相对于内容根（content root）。请注意，这不会影响使用绝对路径的URL。

但这个方式并不完美：在某些环节会出现其他的问题，比如我遇到的这个问题： https://github.com/google/docsy/issues/422 。

也有其他方案，比如设置 canonifyurls = true，但也同样会触发类似的问题：https://github.com/google/docsy/issues/350 。

折腾了一圈，发现没有完美的办法。而且，还有一个地方是绝对无解的：有些url是写死在 js 文件或者css文件中，我修改为 /local 之后是不可能被hugo管理并修改到的。

因此，最后考虑还是通过暴力手段解决问题：直接将docsy中本地化用到的所有文件（保存在 docsy/static/local下）都复制一份扔到网站根目录下，这样类似 https://skyao.io/local/*** 地址就都能解析了。为了持久化，最终的方式是把这些文件提交到了另外一个项目(https://skyao.io 网站)的 static/local 下。

做法有些取巧，但能解决问题就好。

3.4.3 - 启用Ugly URL

启用hugo的ugly URL

Pretty URL 造成了图片路径的困扰：本地实时编辑的路径和在浏览器中正确访问的路径无法同时满足。

背景

https://gohugo.io/content-management/urls/#ugly-urls

Pretty URL

Hugo的默认行为是用 “pretty” URL来呈现内容。 Pretty URL不需要任何非标准的服务器端配置就可以工作。

下面演示一下这个概念：

content/posts/_index.md
=> example.com/posts/index.html
content/posts/post-1.md
=> example.com/posts/post-1/

Ugly URL

如果想拥有通常所说的 “Ugly URL” (例如example.com/urls.html)，请在网站的 config.toml或config.yaml中分别设置 uglyurls = true 或 uglyurls: true。也可以在运行hugo或hugo服务器时，将 HUGO_UGLYURLS 环境变量设置为 true。

.
└── content
    └── about
    |   └── _index.md  // <- https://example.com/about/
    ├── posts
    |   ├── firstpost.md   // <- https://example.com/posts/firstpost/
    |   ├── happy
    |   |   └── ness.md  // <- https://example.com/posts/happy/ness/
    |   └── secondpost.md  // <- https://example.com/posts/secondpost/
    └── quote
        ├── first.md       // <- https://example.com/quote/first/
        └── second.md      // <- https://example.com/quote/second/

开启 uglyurls 之后的路径变成这样：

.
└── content
    └── about
    |   └── _index.md  // <- https://example.com/about.html
    ├── posts
    |   ├── firstpost.md   // <- https://example.com/posts/firstpost.html
    |   ├── happy
    |   |   └── ness.md    // <- https://example.com/posts/happy/ness.html
    |   └── secondpost.md  // <- https://example.com/posts/secondpost.html
    └── quote
        ├── first.md       // <- https://example.com/quote/first.html
        └── second.md      // <- https://example.com/quote/second.html

Pretty URL的影响

Hugo默认采用 pretty URL，url的确漂亮了，但是带来一个很严重的问题，这个问题的来源是编辑内容时最常用的一个需求：

如果我们在页面中要插入一张图片，地址该怎么写？

比如我们在某个 docs 目录下，有 a.md , b.md 两个文件和一个 images 目录，images目录下有一个图片文件 123.jpg。如果我们要在 a.md 的内容中插入这个 123.jpg 图片，那么最常见的方式是:

文本内容1

![](images/123.jpg)

文本内容2

在本地用markdown编辑软件输入内容时，上面的写法可以直接在软件中看到插入的图片。但是在使用 hugo 渲染之后，用浏览器打开 a.md 的地址:

如果是默认的Pretty URL：则地址为 https://localhost:1313/docs/a/，此时插入图片的地址按照相对地址 images/123.jpg 进行计算，结果是 https://localhost:1313/docs/a/images/123.jpg
如果开启的Ugly URL：则地址为 https://localhost:1313/docs/a.html，此时插入图片的地址按照相对地址 images/123.jpg 进行计算，结果是 https://localhost:1313/docs/images/123.jpg

在浏览器中的访问结果就是 Pretty URL 下图片无法显示（404错误），Ugly URL下则地址正确可以正常显示图片。

原因在于 Pretty URL 下 a.md 文件映射的访问地址变成了 https://localhost:1313/docs/a/这样一个文件夹，而不是 a.html 这样一个文件，导致相对路径计算之后和实际本地文件存储的路径不一致。

要修复这个问题，只要简单的修改图片的相对路径，增加 ../ :

文本内容1

![](../images/123.jpg)

文本内容2

这样可以正确的到图片的路径，图片可以正常显示。

但是，在markdown编辑软件中进行本地编辑时，由于这个路径和本地文件和图片的相对路径不符，会造成在编辑器中无法正常显示。

总之，虽然 Pretty URL 下URL的确是 Pretty 了，但是却造成了图片路径的困扰：本地实时编辑的路径和在浏览器中正确访问的路径无法同时满足。

启用Ugly URL

在没有找到其他可行方法之前（希望有吧），暂时采用启用 Ugly URL 的方式来回避这个问题。

修改 config.toml 文件，加入

uglyurls = true

考虑到所有的笔记都应该保持一致，因此我直接修改了 docsy-example 中 config.toml 文件。

备注：如果有朋友知道更好的解决方式，请不吝赐教。

不完美的Ugly URL

启用 Ugly URL之后，普通文件如 docs/a.md / docs/b.md 都采用 docs/a.html / docs/b.html 这样的文件名和路径，但是对于 docs/_index.md ，hugo 有些奇怪的并没有如我预期的转为 docs/ index.html，而是转为 docs.html。这是一个非常的令人费解的行为，同样造成了在 docs/_index.md 文件中图片路径和本地实际路径会不一致的问题。

https://github.com/gohugoio/hugo/issues/4428

3.4.4 - 启用CSE搜索

使用google CSE来搜索站内内容

创建cse搜索

登录cse网站

https://cse.google.com/cse/all

可以看到当前已经添加的搜索引擎
添加一个搜索引擎

注意在"外观" -> “布局” 中设置 “由google托管”，然后"搜索结果会现在以下位置"中选择"当前窗口"

获取 搜索引擎 ID 之后，修改 config.toml :

gcs_engine_id = "8f763efbce07435e9"
#gcs_engine_id = "011737558837375720776:fsdu1nryfng"

在页面上尝试搜索

待解决的问题

uglyurls设置为true之后，搜索不可用，页面报错404，原因是uglyurls设置为true之后，提交的页面地址应该是 /search.html/ 而不应该是 /search/。已经提交issue：

search 404 after set uglyurls = true

3.4.5 - Google Analytics

启用Google Analytics来跟踪网站访问情况

创建Google Analytics账号

https://analytics.google.com/

创建账号和媒体，拿到 Analytics ID ，如 G-4BVWTNS4MB

设置Google Analytics支持

Docsy 内建对 Google Analytics 的支持。设置方式参考官方文档：

https://www.docsy.dev/docs/adding-content/feedback/

修改 config.toml 文件：

 [services.googleAnalytics]
 id = "G-4BVWTNS4MB"

构建时的特殊设置

Ensure that your site is built with HUGO_ENV="production", as Docsy only adds Analytics tracking to production-ready sites.

确保网站构建时带有HUGO_ENV="production"，因为Docsy只在生产就绪的网站上添加分析跟踪。

需要在构建时为hugo增加环境变量：

$ env HUGO_ENV="production" hugo

3.4.6 - 百度统计

启用百度统计来跟踪网站访问情况

没有找到 docsy 主题支持百度统计的方式，只好暴力添加。

修改 docsy 主题中的 layouts/partials/footer.html 文件，在 <footer> 标签中强制加入一下内容：

<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?17048c9d4209e5d08a9ae5b0b4160808";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

不是一个好办法，但好歹能工作。

3.4.7 - 迁移站点

迁移现有的学习笔记到docsy主题

为了日后能方便而干净的merge docsy主题的内容，做了很多工作

背景

对 google 的 docsy 主题比较满意，尤其是看维护和更新的频率，应该未来起码两三年内不会出现如 material-docs 主题那样停止更新的惨剧。因此考虑长期使用这个主题并希望能及时更新。

为了实现这个目标，最理想的状态就是能通过 git merge 的方式方便的将最新的 docsy 主题的改动（包括我自己做的修改和调整）直接更新到数以几十记的学习笔记中。

实践中发现，这对 docsy / docsy-example 和学习笔记的仓库都有要求

准备 docsy 仓库

从 https://github.com/google/docsy 仓库 fork 一个自己的 docsy

https://github.com/skyao/docsy

然后添加远程仓库，merge最新的master内容：

git remote add upstream git://github.com/google/docsy.git
git fetch --all
git merge upstream/master
git push

准备 docsy-example 仓库

通过准备 docsy-example 仓库的fork，由于需要对原仓库内容进行定制修改（默认中文并固定为只有中文，删除和学习笔记无关的内容，修改页面描述，本地化等各种定制），因此在master分支之外拉出来一个 learning 分支，专门用来存放用于学习笔记的模板。

实践中发现，如果直接把 docsy-example fork仓库的 learning 分支 merge 到学习笔记的仓库中（需要加 --allow-unrelated-histories 参数强行merge），会导致学习笔记仓库下出现众多 docsy-example 仓库的提交记录，包括 contributor 列表，非常的混乱。

为了解决这个问题，使用暴力方案：

创建一个空白分支，命名 learning-clean
将 learning 分支下的内容复制到 learning-clean 分支并提交
以后如果 learning 分支有内容更新（包括官方改动和自己的改动），手工更新到 learning-clean 分支
学习笔记从 learning-clean 分支上merge

这个方案的好处是学习笔记的仓库可以保持干净，缺点就是需要手工维护 learning-clean 分支的更新，好在一般更新频率很低。

迁移学习笔记仓库

对学习笔记的仓库也有要求，主要是为了能够轻易的从 docsy-example 仓库的 learning-clean 分支上merge内容。

由于原有学习笔记已有git提交的历史记录，因此从 learning-clean 分支上merge内容必须用 --allow-unrelated-histories 参数强行merge。考虑到学习笔记的提交历史记录不重要，因此我还是继续使用暴力方案：

在学习笔记下创建新的空白分支
merge learning-clean 分支作为code base
复制学习比较的内容提交

这样之后就可以轻松的从 learning-clean 分支上以merge的形式更新内容了。由于学习笔记的内容基本都在content/目录下，重叠内容不多，不容易冲突。

具体步骤如下。

创建新的空白分支

git checkout --orphan docsy
git rm -rf .
ls -la
rm -rf *
ls -la
# 如果还有其他内容再 rm -rf 删除

这样就得到一个什么内容都没有的空白的分支。

添加docsy-example远程仓库

git remote add docsy git://github.com/skyao/docsy-example.git
git fetch --all

merge learning-clean分支

git merge docsy/learning-clean

此时目录下就有从 docsy-example 仓库 learning-clean 分支上的干干净净的内容。

注意 merge 之前切记不要在空白分支上有任何的提交（commit），否则会报错:

git merge upstream/learning-clean
fatal: 拒绝合并无关的历史

虽然也可以加 --allow-unrelated-histories 参数强行merge，但终究不美。

复制原笔记内容并提交

从之前备份的仓库中将学习笔记的内容复制过来，本地验证无误之后提交。

git push --set-upstream origin docsy

调整分支名称

在github的仓库下的 “settings” 页面的 “branches” 中，将默认 branch 从 master 修改为 docsy。

（否则不容许删除默认分支）

然后删除 master 分支，再将 docsy 分支重命名为 master 。之后本地仓库删除后重新 clone 一份新的。

至此，学习笔记的仓库提交记录就非常的干净，而且日后很容易一个简单的merge命令就更新了。代价就是牺牲了git的历史提交记录，但我不介意这些历史记录，更需要能方便的更新和保持仓库整洁。

创建新的学习笔记

新增学习笔记时，记得在仓库创建之后，不要在master分支上有任何内容（不要在创建时选择加入README文件），在做任何提交之前先从 docsy-example 仓库的 learning-clean 分支上 merge 内容，之后再提交学习笔记本身的内容。

总结

上述操作完成后，各个仓库都干干净净的，挺满意。

3.4.8 - 更新到最新版本

更新到 docsy 最新版本

由于改动太大，每次升级docsy版本时都很难自动merge，基本都要重做一次

建立更新需要的git分支

升级 Docsy 最新版本到 master分支

docsy仓库需要 fork，master branch保持和上游master branch的代码一致，master分支上不做任何改动：

升级最新版本时，通过 git remote 机制从上流拉取最新的代码到这个仓库的master分支

创建 learning-xxxx 分支

通过下列命令在 docsy 仓库中为每次更新建立单独的 learning 分支，以月份为后缀：

git checkout -b learning-202108

运行 docsy-example

进入 docsy 仓库拉取 docsy 依赖的 submodule ：

cd docsy
# git checkout leanring-202108
git submodule update --init --recursive

删除 docsy-example 仓库下原有的 theme 目录和 .gitmodule 文件

cd docsy-example
# git checkout leanring-202108
rm -rf themes
rm .gitmodule

在 docsy-example 仓库下创建到 docsy 仓库的软链接
```
mkdir themes
cd themes
ln -s ../../docsy .
```
此时运行 hugo 命令就可以构建完全是最新内容的 docsy-example 网站，后面将在这个基础上进行定制化。
在 docsy-example 仓库下提交上面修改的代码

git add -A
git commit -m "remove gitsubmodule of themes; add soft link to docsy"

更新 docsy

文件本地化

cd docsy/static
mkdir local
cd local

wget -x https://code.jquery.com/jquery-3.5.1.min.js
wget -x https://cdn.jsdelivr.net/npm/popper.js@1.16.1/dist/umd/popper.min.js
wget -x https://cdn.jsdelivr.net/npm/bootstrap@4.6.0/dist/js/bootstrap.min.js
wget -x https://cdn.jsdelivr.net/gh/rastikerdar/vazir-font@v27.0.1/dist/font-face.css
wget -x https://fonts.gstatic.com/s/opensans/v23/mem5YaGs126MiZpBA-UN_r8OUuhpKKSTjw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v23/mem8YaGs126MiZpBA-UFVZ0bf8pkAg.woff2

wget -x https://fonts.gstatic.com/s/opensans/v23/mem5YaGs126MiZpBA-UN7rgOUuhpKKSTjw.woff2
wget -x http://localhost:1313/webfonts/fa-solid-900.woff2



wget -x https://cdn.jsdelivr.net/npm/mermaid@8.9.2/dist/mermaid.min.js
wget -x https://cdn.jsdelivr.net/npm/katex@0.13.2/dist/katex.min.css
wget -x https://cdn.jsdelivr.net/npm/katex@0.13.2/dist/katex.min.js
wget -x https://cdn.jsdelivr.net/npm/katex@0.13.2/dist/contrib/mhchem.min.js

wget -x https://cdn.jsdelivr.net/npm/katex@0.13.2/dist/contrib/auto-render.min.js
wget -x https://cdn.jsdelivr.net/gh/rastikerdar/vazir-font@v27.0.1/dist/font-face.css

css文件的优化

先不优化，先搞定中文页面，再看是否需要优化，有些内容可能和多语言有关系。

css文件比较麻烦，主要是这些css文件不是以静态文件的方式发布，而是服务器端下发，如果简单改会出现css不对应的问题。之前遇到的代码高亮无法显示就是这个造成的。

find . -type f -exec grep -Hn "css?family=" {} \;                             
./assets/scss/_variables.scss:67:$web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap";
./assets/vendor/bootstrap/site/content/docs/4.6/examples/blog/index.html:5:  - "https://fonts.googleapis.com/css?family=Playfair+Display:700,900"

这两个参数是写死的，理论上可以强行静态化，就是涉及到的文件数量非常多。

body:lang(he) {
    @import url('https://fonts.googleapis.com/css2?family=Rubik:wght@300;400;500;600;700&display=swap');
    font-family: 'Rubik', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}

body:lang(ar) {
    @import url('https://fonts.googleapis.com/css2?family=Tajawal:wght@300;400;500;700&display=swap');
    font-family: 'Tajawal', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}

暂时先不懂，以后再看是否有必要。

更新相关的仓库

之后使用 docsy 的 learning-xxx 分支即可，docsy-example 仓库检查了一下，基本没有实质性的内容改动，可以忽略不计。

由于我使用的是 soft link，所以其他笔记自动就更新到了最新的 learning-xxx 分支的 docsy 主题。

3.4.9 - 重来备忘录

每次重新安装系统之后都不得不从头来一次，为了方便，记录一下全过程以备参考

操作流程

从头开始，全部流程如下，严格按照顺序操作：

# docsy fork
cd ~/work/code/learning
git clone git@github.com:skyao/docsy.git
cd docsy
git checkout learning-202108
git submodule update --init --recursive

# docsy example
cd ~/work/code/learning
git clone git@github.com:skyao/docsy-example.git
cd docsy-example
git checkout learning-clean

# docsy build
cd ~/work/code/learning
git clone git@github.com:skyao/docsy-example.git docsy-example-build
cd docsy-example-build
git checkout build
cp clone.sh init.sh server.sh addremote.sh ../

# try one project
cd ~/work/code/learning
sh clone.sh hugo
cd learning-hugo
npm install -D --save autoprefixer
npm install -D --save postcss-cli

# build
cd ~/work/code/learning
cd learning-hugo
h

搞定！m1 下运行正常。

3.5 - material-docs主题

~~介绍hugo的material-docs主题，使用方式和订制化~~

material-docs主题非常适合用于文档，但常年不更新，已不能支持新版本的Hugo，不得已放弃改为使用 Google Docsy 主题。

主题介绍

material-docs官网：

http://themes.gohugo.io/theme/material-docs/：已经报错404
https://github.com/digitalcraftsman/hugo-material-docs

这个主题非常适合用于文档，左边的导航栏支持多级菜单，样式也简单美观，而且对移动设备支持很好。

我从2018年出开始使用 material-docs 主题，主要用它来做学习笔记，替代之前长期使用的gitbook（gitbook的问题主要是本地生成内容速度太慢，而gitbook官方网站访问速度又不好）。但很遗憾，material-docs主题的作者已经消失，2017年后再没有更新，包括PR也没有人处理。

随着hugo的版本越来越新，这个主题的问题也越来越多，甚至为了能兼容我的hugo长期停留在0.54版本。

因此，在2021年，正式弃用 material-docs 主题，改为 Google Docsy 主题。当前您看到的这个Hugo学习笔记就是基于 Google Docsy 主题。