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

学习笔记定制化

为自己的各种学习笔记定制Docsy主题

1: 定制化概述
2: 定制化的准备工作
3: 为学习笔记特别定制
4: 总结
5: 升级现有学习笔记
6: 发布学习笔记
7: 本地搭建
8: 创建一个新的学习笔记

1 - 定制化概述

定制化的目标和主要工作内容概述

对 docsy 主题进行定制化的主要目标是：

网络加速：docsy主题使用时需要载入的图片/css/js 文件，网络地址会被被 GFW 墙，导致访问速度缓慢甚至无法加载。
- 这个工作直接重用 cloudruntime 中的修改
修改内容：为学习笔记定制，以便后续在几十个学习笔记中重用这套修改之后的模版。

2 - 定制化的准备工作

准备fork仓库，建立分支

为了避免遗忘，记录定制化的全过程。

以学习笔记为例，时间为 2023/12/27.

安装hugo

node 安装版本：

Node.js v20.10.0 to /usr/local/bin/node
npm v10.2.3 to /usr/local/bin/npm

hugo 安装版本为：

hugo v0.121.1 extended 版本

Fork 仓库

docs：

从官方仓库： https://github.com/google/docsy

Fork 为自己的仓库：https://github.com/skyao/docsy-learning

docs-example：

从官方仓库：https://github.com/google/docsy-example

Fork 为自己的仓库：https://github.com/skyao/docsy-example-learning

克隆代码

注意：

一定要确保 fork 后的仓库的 master 分支上是干净的，即不做任何代码修改，只用于从 upsream 仓库拉取最新的代码。

所有自己的代码改动，在自己 fork 的仓库中新建新的branch

clone 仓库代码到本地，

mkdir learning
cd learning
git clone git@github.com:skyao/docsy-learning.git docsy
git clone git@github.com:skyao/docsy-example-learning.git docsy-example

建立分支

然后建立 local-files 分支并增加 upstream。

docsy：

cd docsy
git checkout -b local-files
git push --set-upstream origin local-files

# 这里直接重用上一次cloudruntime制作好的 local-files 分支
git remote add upstream git@github.com:cloudruntime/docsy.git

git fetch -a
git merge upstream/local-files
git push

这样就搞定了本地文件化的事情。

docsy-example：

cd docsy-example
git checkout -b learning2024
git push --set-upstream origin learning2024

git remote add upstream git@github.com:google/docsy-example.git
git fetch -all

运行

docsy 这边要先安装 npm 依赖：

cd docsy
npm install --save-dev autoprefixer
npm install --save-dev postcss-cli
npm install -D postcss

docsy-example 这边要修改一下对 docsy 的依赖，hugo新版本有内置支持，只要修改 hugo.toml 文件，取消 workspace 的注释即可：

[module]
  # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace:
  # workspace = "docsy.work"
  workspace = "docsy.work"

然后执行:

alias h='hugo -D -F server --disableFastRender --bind "0.0.0.0"'

为了简单起见，修改 ~/.zshrc 增加 alias：

alias h='hugo -D -F server --disableFastRender --bind "0.0.0.0"'
// 以后只要敲一个 h 就可以跑起来了
h

这时候就可以打开 http://localhost:1313/ 访问了。

此时的代码完全是上游的代码，除了将依赖关系修改为本地之外，还没有做任何修改。

提交代码改动，此时准备工作完成。

3 - 为学习笔记特别定制

修改模版内容，为学习比较特别定制

准备修改 docsy 和 docsy-example 仓库的内容，为CloudRuntime网站特别定制。

修改 docsy-example 仓库

准备分支

使用之前新建 learning2024 分支，为后续的各种学习准备 code base：

git checkout learning2024

修改内容

修改hugo.toml

删除 no 和 fa 语言的内容：

[languages.no]
......
[languages.fa]
......

增加中文内容，网站只保留 en 和 zn-cn 两种语言，相关配置为：

# Language settings
contentDir = "content"
defaultContentLanguage = "zh-cn"
defaultContentLanguageInSubdir = false

......

# Language configuration

[languages]
# [languages.en]
# en 配置全部删除

[languages.zh-cn]
languageName ="中文"
# Weight used for sorting.
weight = 1
[languages.zh-cn.params]
title = "xxx学习笔记"
description = "xxx学习笔记，记录学习xxx的过程和相关资料"
contentDir = "content"
time_format_default = "2006.01.02"
time_format_blog = "2006.01.02"

学习笔记只保留中文。

其他修改：

enableGitInfo = false

[params]
copyright = "skyao.io"
privacy_policy = ""

url_latest_version = "https://skyao.io/learning-xxx"
github_repo = "https://github.com/skyao/learning-xxx"
github_project_repo = "https://github.com/skyao/learning-xxx"

gcs_engine_id = "d3c56aefaae284df1"
# enable google analytics
[services.googleAnalytics]
  id = "G-4BVWTNS4MB"

prism_syntax_highlighting = true
footer_about_disable = true

[params.ui.feedback]
enable = false

修改通用页面内容

修改 content/_index.md 为学习笔记的页面。文字内容按照之前的学习笔记内容修改。这个页面是所有学习笔记都通用的。
修改 featured-background.jpg 为学习笔记的背景图片。
修改 search.md : 只修改一个 title
将之前 content/en 目录下的 _index.md 复制到当前 content 目录。

修改完这些之后，一个学习笔记通用的模版内容就准备好了。

修改 docsy 仓库

docsy 仓库本来可以不用改了，但是百度统计这个功能最简单的办法就是修改 docsy 模版的 footer ，为了后续免的折腾就在这里修改吧。

修改通用内容

准备分支

使用 learning2024 作为学习笔记的定制化分支：

cd docsy
git checkout local-files
git checkout -b learning2024
git push --set-upstream origin learning2024

百度统计

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

<footer class="td-footer row d-print-none">
<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>  
</footer>

4 - 总结

总结改动的内容

定制完成后，总结改动的内容。

docsy 仓库

分支情况：

main: 完全不改，只同步上游文件，保持和 google/docsy 仓库 main 分支内容的一致
local-files: 以main 分支为 code base，只修改远程访问地址为本地地址，实现网络加速，没有任何文字内容改动
learning2024 以 local-files 分支为 code base，修改内容和文字，为学习笔记网站定制

local-files 分支

重用 cloudruntime 的 local-files 分支。

learning2024 分支

Merge 了 local-files 分支的改动。

额外的功能：

增加了 baidu 统计的功能：直接修改了 footer ，hard code 了 cloudruntime 网站的 baidu 统计代码

docsy-example 仓库

分支情况：

main: 完全不改，只同步上游文件，保持和 google/docsy-example 仓库 main 分支内容的一致
learning2024: 以main 分支为 code base，修改内容和文字，为学习笔记定制
learning-clean-2024: 内容来自 learning2024，但清除了git的历史记录，在空白分支上复制 learning2024 的内容制作的全新的分支，用于给各个学习笔记同步最新改动用。

learning2024 分支

修改 hugo.toml
修改 content 目录下的内容：主要工作在这里

就没有别的改动了。上面这些改动是学习笔记特有的，不适合用在其他网站。

learning-clean-2024 分支

复制 learning2024 的内容，重新打造。

5 - 升级现有学习笔记

记录升级现有学习笔记的过程，备用

背景：现有几十份学习笔记，需要更新到 leanring2024 分支的最新，这里记录更新的过程。

以 learning-hugo 为例。

merge 最新内容

merge learning-clean-2024 分支

cd learning2024
git clone git@github.com:skyao/learning-hugo.git
cd learning-hugo

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

git merge upstream/learning-clean-2024

解决 merge 冲突

需要处理 merge 的冲突文件：

CONFLICT (add/add): Merge conflict in README.md
CONFLICT (content): Merge conflict in config.toml
CONFLICT (content): Merge conflict in content/docs/_index.md
CONFLICT (content): Merge conflict in package.json

README.md

选择 “Accept Current Change” 保留当前仓库的内容。

config.toml

这个文件后面不会再使用，所以简单的选择 “Accept Current Change” 保留当前仓库的内容。

package.json

选择 “Accept Incoming Change” 更新本地仓库的内容。

content/docs/_index.md

选择 “Accept Current Change” 保留当前仓库的内容。

人工迁移内容

有几个文件的内容必须人工迁移。

config.toml

这个文件在新版本中将被 hugo.toml 文件替代，所以里面的设置内容需要手工迁移到 hugo.toml 文件中。

需要修改的内容：

替换所有的 xxx 为 “hugo”

title = "hugo学习笔记"
title = "hugo学习笔记"
description = "hugo学习笔记，记录学习hugo的过程和相关资料"

url_latest_version = "https://skyao.io/learning-hugo"
github_repo = "https://github.com/skyao/learning-hugo"
github_project_repo = "https://github.com/skyao/learning-hugo"

修改 gcs_engine_id 和 googleAnalytics id
```
gcs_engine_id = "8f763efbce07435e9"
```
这个参数按说每个学习笔记都应该设置自己独有的 id。

如果没有的话就用默认值 “d3c56aefaae284df1”，这是 https://skyao.io 整个网站的 gcs_engine_id。

修改 googleAnalytics id

这个参数应该不用改。

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

增加 plantuml 的参数

[params.plantuml]
enable = true
theme = "default"
#Set url to plantuml server 
#default is http://www.plantuml.com/plantuml/svg/
svg_image_url = "https://www.plantuml.com/plantuml/svg/"

TBD: 直接修改 upstream/learning-clean-2024 ，增加这个内容。

content/_index.html

这个文件在新版本中将被 _index.md 文件替代，所以里面的设置内容需要手工迁移到 _index.md 文件中。

需要修改的内容：

替换所有的 xxx 为 “hugo”

清理不再需要的内容

删除以下不再需要的文件：

config.toml
content/_index.html

6 - 发布学习笔记

记录发布现有学习笔记到nginx的过程，备用

背景

我的学习笔记发布在 https://skyao.io/learning-xxx 这样的地址下，其中 https://skyao.io 这个网站是我的个人博客网站，也是基于 hugo，使用 nginx 发布。

准备工作

准备目录和仓库

使用 ~/site/learning 目录存放所有学习笔记相关的内容，将相关的仓库 clone 到这个目录下：

mkdir -p ~/site/learning

# docsy 相关的仓库
git clone https://github.com/skyao/docsy.git
git clone https://github.com/skyao/docsy-example.git
git clone https://github.com/skyao/docsy-example.git docsy-example-build

准备 docsy

cd docsy
git checkout learning2024

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

安装最新的 hugo 0.121.1 版本

wget https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_extended_0.121.1_linux-amd64.tar.gz
tar xvf hugo_extended_0.121.1_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/hugo121

发布过程

clone.sh

addremote.sh

publish.sh

遇到的问题

中间遇到一个奇怪的错误（其他平台没有遇到）：

$ hugo

Start building sites … 
hugo v0.121.1-00b46fed8e47f7bb0a85d7cfc2d9f1356379b740+extended linux/amd64 BuildDate=2023-12-08T08:47:45Z VendorInfo=gohugoio

Total in 7829 ms
Error: error building site: POSTCSS: failed to transform "scss/main.css" (text/css). Check your PostCSS installation; install with "npm install postcss-cli". See https://gohugo.io/hugo-pipes/postcss/: binary with name "npx" not found

后来在 learning-hugo 目录下，执行

cd learing-hugo
npm install postcss-cli
hugo

就可以了。这个问题稍后再看是怎么回事。

附录

其他学习笔记：

# 学习笔记的仓库
git clone https://github.com/skyao/learning-servicemesh.git
git clone https://github.com/skyao/learning-vscode.git
git clone https://github.com/skyao/learning-openwrt.git
git clone https://github.com/skyao/learning-microservice.git
git clone https://github.com/skyao/learning-mtls.git
git clone https://github.com/skyao/learning-macos.git
git clone https://github.com/skyao/learning-kubernetes.git
git clone https://github.com/skyao/learning-grpc.git
git clone https://github.com/skyao/learning-git.git
git clone https://github.com/skyao/learning-envoy.git
git clone https://github.com/skyao/learning-docker.git
git clone https://github.com/skyao/learning-xds.git
git clone https://github.com/skyao/learning-consul.git
git clone https://github.com/skyao/learning-azure.git
git clone https://github.com/skyao/learning-actor.git
git clone https://github.com/skyao/learning-mockito.git
git clone https://github.com/skyao/learning-java-aot.git
git clone https://github.com/skyao/learning-jdk.git
git clone https://github.com/skyao/learning-linux-mint.git
git clone https://github.com/skyao/learning-ubuntu-server.git
git clone https://github.com/skyao/learning-computer-hardware.git
git clone https://github.com/skyao/learning-dapr.git
git clone https://github.com/skyao/learning-temporal.git
git clone https://github.com/skyao/learning-spring-cloud.git
git clone https://github.com/skyao/learning-hugo.git

以下是还没有更新到 2024 版 docsy 主题的其他学习笔记：

git clone https://github.com/skyao/learning-sentinel.git
git clone https://github.com/skyao/learning-distributed-transaction.git
git clone https://github.com/skyao/learning-pve.git
git clone https://github.com/skyao/learning-esxi.git
git clone https://github.com/skyao/learning-kafka.git
git clone https://github.com/skyao/learning-flatbuffers.git
git clone https://github.com/skyao/learning-github-action.git
git clone https://github.com/skyao/learning-fortio.git
git clone https://github.com/skyao/learning-webassembly.git
git clone https://github.com/skyao/learning-tokio.git
git clone https://github.com/skyao/learning-inoreader.git
git clone https://github.com/skyao/learning-windows-server.git
git clone https://github.com/skyao/learning-go.git
git clone https://github.com/skyao/learning-drawing-tool.git
git clone https://github.com/skyao/learning-unit.git
git clone https://github.com/skyao/learning-erpc.git
git clone https://github.com/skyao/learning-cloudstate.git
git clone https://github.com/skyao/learning-cloudnative.git
git clone https://github.com/skyao/learning-serverless.git
git clone https://github.com/skyao/learning-reactor.git
git clone https://github.com/skyao/learning-distributed-capability.git
git clone https://github.com/skyao/learning-nginx.git
git clone https://github.com/skyao/learning-prometheus.git
git clone https://github.com/skyao/learning-maven.git
git clone https://github.com/skyao/learning-dns.git
git clone https://github.com/skyao/learning-hessian.git
git clone https://github.com/skyao/learning-cillium.git
git clone https://github.com/skyao/learning-udpa.git
git clone https://github.com/skyao/learning-eventbrige.git
git clone https://github.com/skyao/learning-knative.git
git clone https://github.com/skyao/learning-linkerd2-proxy.git
git clone https://github.com/skyao/learning-linkerd2.git
git clone https://github.com/skyao/learning-istio.git
git clone https://github.com/skyao/learning-proto3.git
git clone https://github.com/skyao/learning-http2.git

7 - 本地搭建

本地从头开始搭建学习笔记的编辑环境。

简单记录备忘和快速重复搭建。

准备工作

先安装好：

go
nodejs

hugo

vi ~/.zshrc 增加一个 h alias，方便后续使用:

# 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'

git
markdown编辑器：如 typora

准备好目录:

mkdir -p ~/work/code/learning
cd ~/work/code/learning

主题和构建脚本

docsy 仓库：

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

cd docsy
git checkout learning2024

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

docsy-example 仓库

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

cd docsy-example
git checkout build
cp *.sh ../

验证

以 hugo 学习笔记为例：

cd ~/work/code/learning
sh clone.sh learning-hugo

cd learning-hugo/
h

# 或者 
sh server.sh learning-hugo

8 - 创建一个新的学习笔记

本地从头开始创建一个新的学习笔记的过沉。

简单记录备忘和快速重复搭建。

创建新仓库

创建新仓库，如 https://github.com/skyao/learning-debian

clone 到本地 learning 目录:

cd ~/work/code/learning
sh clone.sh learning-debian

初始化笔记

修改字眼

git merge upstream/learning-clean-2024

用 vscode 打开这个目录，然后搜索 “xxx”，替换为 “Debian” 或者 Debian :

hugo.toml
README.md
content/_index.md
content/docs/_index.md
config.toml

修改 gcs_engine_id

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

创建一个新的搜索引擎：

名称： learning-debian
搜索内容： skyao.io/learning-debian/*

创建成功后的页面就会显示

<script async src="https://cse.google.com/cse.js?cx=a44bd639f3a554e52">
</script>
<div class="gcse-search"></div>

a44bd639f3a554e52 就是 gcs_engine_id

打开 config.toml，设置 gcs_engine_id。

# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "a44bd639f3a554e52"

此时就可以执行 h 命令查看效果了，没问题的话就可以提交，这样一个空白的学习笔记就创建出来了。后续填充内容即可。