定制化
定制化Docsy主题以更好的适应中国国情
- 1: cloudruntime定制化
- 1.1: 定制化概述
- 1.2: 定制化的准备工作
- 1.3: 使用本地文件加速网络访问
- 1.4: 为CloudRuntime网站特别定制
- 1.5: 搭建CloudRuntime官方网站
- 1.6: 搭建CloudRuntime用户文档
- 1.7: 搭建CloudRuntime开发文档
- 1.8: 总结
- 1.9: 本地搭建
- 2: 学习笔记定制化
1 - cloudruntime定制化
为cloudruntime网站定制Docsy主题
1.1 - 定制化概述
定制化的目标和主要工作内容概述
对 docsy 主题进行定制化的主要目标是：
- 网络加速：docsy主题使用时需要载入的 图片/css/js 文件，网络地址会被被 GFW 墙，导致访问速度缓慢甚至无法加载。
1.2 - 定制化的准备工作
准备fork仓库，建立分支
为了避免遗忘，记录定制化的全过程。
以 cloudruntime 网站为例，时间为 2023/12/21.
安装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/cloudruntime/docsy
docs-example：
从官方仓库：https://github.com/google/docsy-example
Fork 为自己的仓库：https://github.com/cloudruntime/docsy-example
克隆代码
注意：
一定要确保 fork 后的仓库的 master 分支上是干净的，即不做任何代码修改，只用于从 upsream 仓库拉取最新的代码。
所有自己的代码改动，在自己 fork 的仓库中新建新的branch
clone 仓库代码到本地，
mkdir cloudruntime
cd cloudruntime
git clone git@github.com:cloudruntime/docsy.git
git clone git@github.com:cloudruntime/docsy-example.git
建立分支
然后建立 local-files 分支并增加 upstream。
docsy：
cd docsy
git checkout -b local-files
git push --set-upstream origin local-files
git remote add upstream git@github.com:google/docsy.git
docsy-example：
cd docsy-example
git checkout -b local-files
git push --set-upstream origin local-files
git remote add upstream git@github.com:google/docsy-example.git
运行
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/ 访问了。
此时的代码完全是上游的代码，除了将依赖关系修改为本地之外，还没有做任何修改。
提交代码改动，此时准备工作完成。
1.3 - 使用本地文件加速网络访问
使用本地文件加速，避免被墙
准备修改 docsy ，将可能会被墙的文件修改为使用本地文件。
为了方便修改，建议用 vs code 之类的 IDE 打开 fork 下来的 docsy 仓库。
准备local目录
在 docsy 仓库下建立 static/local 文件夹：
cd docsy
cd static
mkdir local
cd local
修改js文件
在 IDE 中 搜索 “https://”, 然后用 wget 命令下载找到的各个文件中的各种网络文件，主要是js和css：
# layouts/partials/head.html
wget -x https://code.jquery.com/jquery-3.6.3.min.js
wget -x https://unpkg.com/lunr@2.3.9/lunr.min.js
# layouts/shortcodes/redoc.html
wget -x https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js
# layouts/swagger/baseof.html
wget -x https://unpkg.com/swagger-ui-dist@5.1.0/swagger-ui.css
wget -x https://unpkg.com/swagger-ui-dist@5.1.0/swagger-ui-bundle.js
wget -x https://unpkg.com/swagger-ui-dist@5.1.0/swagger-ui-standalone-preset.js
# layouts/partials/scripts.html
wget -x https://cdn.jsdelivr.net/npm/markmap-autoloader
wget -x https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.css
wget -x https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.js
wget -x https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/contrib/mhchem.min.js
wget -x https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/contrib/auto-render.min.js
wget -x https://cdn.jsdelivr.net/npm/mermaid@9.3.0/dist/mermaid.min.js
wget -x https://cdn.jsdelivr.net/npm/@docsearch/js@3.5.2
比较麻烦的是 css 文件，暂时先不修改吧。
修改案例
以 jquery-3.6.3.min.js 文件为例，
cd docsy
cd layouts
find . -type f -exec grep -Hn 'jquery-3.6.3.min.js' {} \;
./layouts/partials/head.html:29: src="https://code.jquery.com/jquery-3.6.3.min.js"
打开这个文件，找到 jquery-3.6.3.min.js ：
<script
src="https://code.jquery.com/jquery-3.6.3.min.js"
integrity="sha512-STof4xm1wgkfm7heWqFJVn58Hm3EtS31XFaagaa8VMReCXAkQnJZ+jEy8PCC/iT18dFy95WcExNHFTqLyp72eQ=="
crossorigin="anonymous"></script>
修改为 :
<script
src="/local/code.jquery.com/jquery-3.6.3.min.js"
integrity="sha512-STof4xm1wgkfm7heWqFJVn58Hm3EtS31XFaagaa8VMReCXAkQnJZ+jEy8PCC/iT18dFy95WcExNHFTqLyp72eQ=="
crossorigin="anonymous"></script>
此时再刷新页面，就能看到这个文件的地址被修改为：
http://localhost:1313/local/code.jquery.com/jquery-3.6.3.min.js
修改css文件
部分css文件修改比较麻烦，单独列出来
fonts.googleapis.com
首先是 assets/scss/main.scss 文件中会引出这个网络访问：
https://fonts.googleapis.com/css.css?family=Open+Sans:300,300i,400,400i,700,700i&display=swap
打开这个地址，将内容保存到文件 static/local/fonts.googleapis.com/css.css 中，
然后查找这个地址的出处，在这里：
@if $td-enable-google-fonts {
@import url($web-font-path);
}
定义在 assets/scss/_variables.scss 文件：
$web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap";
然后修改上面的内容为：
$web-font-path: "/local/fonts.googleapis.com/css.css?family=#{$google_font_family}&display=swap";
继续修改这个保存下来的 fonts.googleapis.com/css.css 文件。
执行 grep "wget -x https://" css.css 命令，将地址提取出来，然后替换前后内容，得到这样一堆wget命令：
# cd static/local
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtE6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWvU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuk6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWu06FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWxU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqW106FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtk6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWt06FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuU6FxZCJgg.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtE6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWvU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuk6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWu06FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWxU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqW106FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtk6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWt06FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuU6FxZCJgg.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtE6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWvU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuk6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWu06FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWxU6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqW106FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtk6FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWt06FxZCJgvAQ.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuU6FxZCJgg.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSKmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSumu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSOmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSymu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS2mu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTVOmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTUGmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSCmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSGmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS-mu0SC55I.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSKmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSumu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSOmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSymu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS2mu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTVOmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTUGmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSCmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSGmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS-mu0SC55I.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSKmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSumu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSOmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSymu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS2mu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTVOmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTUGmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSCmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSGmu0SC55K5gw.woff2
wget -x https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS-mu0SC55I.woff2
执行完成之后所有的文件就都保存到 local 文件夹下了。
再将这个 css.css 文件中所有的 https// 替换为 /local/，这样就会将
src: url(https://fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSGmu0SC55K5gw.woff2) format('woff2');
修改为：
src: url(/local/fonts.gstatic.com/s/opensans/v40/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSGmu0SC55K5gw.woff2) format('woff2');
然后刷新页面，确认地址修改正确。
这个改动完成之后，css加载的速度就非常快了。
但这里有风险，google_font_family 现在相当于被写死为 Open+Sans:300,300i,400,400i,700,700i 了：
$web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap";
后面如果遇到问题再调整。
1.4 - 为CloudRuntime网站特别定制
修改模版内容，为CloudRuntime网站特别定制
准备修改 docsy 和 docsy-example 仓库的内容，为CloudRuntime网站特别定制。
修改 docsy-example 仓库
准备分支
新建 cloudruntime 分支，为后续的各种网站准备 code base：
git checkout -b cloudruntime
git merge local-files
修改通用内容
修改hugo.toml
多语言设置
删除 no 和 fa 语言的内容：
[languages.no]
......
[languages.fa]
......
增加中文内容，网站只保留 en 和 zn-cn 两种语言，相关配置为：
# Language settings
contentDir = "content/zh"
defaultContentLanguage = "zh-cn"
defaultContentLanguageInSubdir = false
......
# Language configuration
[languages]
[languages.en]
languageName ="English"
contentDir = "content/en"
# Weight used for sorting.
weight = 2
[languages.en.params]
title = "CloudRuntime"
description = "CloudRuntime site"
time_format_default = "2006.01.02"
time_format_blog = "2006.01.02"
[languages.zh-cn]
languageName ="Chinese"
contentDir = "content/zh"
# Weight used for sorting.
weight = 1
[languages.zh-cn.params]
title = "CloudRuntime"
description = "CloudRuntime 网站"
time_format_default = "2006.01.02"
time_format_blog = "2006.01.02"
默认语言修改为中文 zh-cn。
复制中文内容
将 content/en 目录复制为 content/zh 目录，先重用英文内容为中文内容的基础，然后后续再修改为中文。
修改为 CloudRuntime
title = "CloudRuntime"
url_latest_version = "https://cloudruntime.net"
github_repo = "https://github.com/cloudruntime/website"
github_project_repo = "https://github.com/cloudruntime/cloudruntime"
gcs_engine_id = "8762eb8456ad6400e"
# enable google analytics
[services.googleAnalytics]
id = "G-RK2ZRH7XPE"
[params.ui.feedback]
enable = false
yes = 'Glad to hear it! Please <a href="https://github.com/cloudruntime/cloudruntime/issues/new">tell us how we can improve</a>.'
no = 'Sorry to hear that. Please <a href="https://github.com/cloudruntime/cloudruntime/issues/new">tell us how we can improve</a>.'
修改 docsy 仓库
准备分支
新建 cloudruntime 分支，为后续的各种网站准备 code base：
git checkout -b cloudruntime
git merge local-files
修改通用内容
百度统计
修改 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?b4f16bb2e57123f6faf09c8b3574d07a";
var s = document.getElementsByTagName("script")[0];
s.parentNode.insertBefore(hm, s);
})();
</script>
</footer>
1.5 - 搭建CloudRuntime官方网站
修改模版内容，搭建CloudRuntime网站
准备修改 docsy-example 的内容，搭建CloudRuntime官方网站。
准备仓库
创建 cloudruntime/website 仓库，使用 main 分支：
cd cloudruntime
git clone git@github.com:cloudruntime/website.git
cd website
git remote add upstream git@github.com:cloudruntime/docsy-example.git
git fetch --all
git merge upstream/cloudruntime --allow-unrelated-histories
修改 README.md 中的冲突内容，然后一起提交。
修改用户案例
文档需要单独作为独立的 hugo 项目存在，cloudruntime 的 website 仓库不存放这个内容，暂时修改用户案例，后续有用户使用之后可以把这块建设起来。
将 docs 目录重命名为 case，修改 _index.md 文件，增加以下内容：
cascade:
- type: "docs"
增加导航条目
主要是增加 使用文档 和 开发文档 两个顶级导航条目，分别指向 docs 和 devdocs 两个子目录。
修改 hugo.toml，增加如下内容，这样可以在增加导航条的同时实现 i18n：
[[languages.en.menu.main]]
name = "Documentation"
weight = 20
url = "https://cloudruntime.net/docs/"
[[languages.en.menu.main]]
name = "Development"
weight = 30
url = "https://cloudruntime.net/devdocs/"
[[languages.zh-cn.menu.main]]
name = "使用文档"
weight = 20
url = "https://cloudruntime.net/docs/"
[[languages.zh-cn.menu.main]]
name = "开发文档"
weight = 30
url = "https://cloudruntime.net/devdocs/"
有多种方式，具体参考：
https://gohugo.io/content-management/multilingual/#menus
删除示例内容
删除 blog 和 case （原docs）下的示例内容，将内容置空以便后续增加。
发布网站内容
准备工作
建立目录：
mkdir -p ~/site/cloudruntime
cd ~/site/cloudruntime
升级 npm
cd ~/temp
wget https://nodejs.org/dist/v20.10.0/node-v20.10.0-linux-x64.tar.xz
tar xvf node-v20.10.0-linux-x64.tar.xz
sudo rm -rf /usr/share/nodejs
sudo mv node-v20.10.0-linux-x64 /usr/share/nodejs
安装新版本的 hugo extension 版本：
cd ~/temp
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 cp hugo /usr/local/bin/hugo121
准备 docsy 主题
cd ~/site/cloudruntime
git clone https://github.com/cloudruntime/docsy.git
cd docsy
git checkout local-files
npm install --save-dev autoprefixer
npm install --save-dev postcss-cli
npm install -D postcss
准备 cloudruntime 的 发布目录
cd /var/www/
sudo mkdir cloudruntime
sudo chown sky cloudruntime
sudo chgrp sky cloudruntime
发布 website 网站
cd ~/site/cloudruntime
git clone https://github.com/cloudruntime/website.git
cd website
./public.sh
配置 nginx
sudo vi /etc/nginx/sites-available/cloudruntime.net
内容如下：
server {
listen 80;
server_name cloudruntime.net www.cloudruntime.net;
root /var/www/cloudruntime;
index index.html;
location / {
try_files $uri $uri/ =404;
}
}
增加 sites-enabled ：
sudo ln -s /etc/nginx/sites-available/cloudruntime.net /etc/nginx/sites-enabled/cloudruntime.net
重启 nginx：
sudo systemctl restart nginx
用浏览器访问地址 http://cloudruntime.net/ 进行验证。
开启 https
执行下面命令生成 ssl 证书：
sudo letsencrypt certonly --webroot -w /var/www/cloudruntime -d cloudruntime.net
增加 https 的 site：
sudo vi /etc/nginx/sites-available/cloudruntime.net.https
内容如下：
server {
listen 443 ssl;
server_name cloudruntime.net www.cloudruntime.net;
root /var/www/cloudruntime;
index index.html;
ssl on;
ssl_certificate /etc/letsencrypt/live/cloudruntime.net/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/cloudruntime.net/privkey.pem;
location / {
try_files $uri $uri/ =404;
}
}
增加 sites-enabled ：
sudo ln -s /etc/nginx/sites-available/cloudruntime.net.https /etc/nginx/sites-enabled/cloudruntime.net.https
重启 nginx：
sudo systemctl restart nginx
用浏览器访问地址 https://cloudruntime.net/ 进行验证。
然后将http请求都自动转为https，修改原来的cloudruntime.net配置文件：
sudo vi /etc/nginx/sites-available/cloudruntime.net
内容修改为：
server {
listen 80;
server_name cloudruntime.net www.cloudruntime.net;
rewrite ^(.*)$ https://$host$1 permanent;
}
用浏览器访问地址 http://cloudruntime.net/ 进行验证，会自动跳转到 https 的页面。
1.6 - 搭建CloudRuntime用户文档
修改模版内容，搭建CloudRuntime用户文档
准备修改 docsy-example 的内容，搭建CloudRuntime 用户文档。
准备仓库
创建 cloudruntime/docs 仓库，使用 main 分支：
cd cloudruntime
git clone git@github.com:cloudruntime/docs.git
cd docs
# 以下方式废弃，会引入原来 docsy 仓库中的所有 commit 内容，造成麻烦
# git remote add upstream git@github.com:cloudruntime/docsy-example.git
# git fetch --all
# git merge upstream/cloudruntime --allow-unrelated-histories
# 直接复制 website 下的所有内容
cp -r ../website/* .
# 各种修改
# ......
# 之后一次性提交
git add -A
修改内容
将 docs 目录重命名为 userguide，增加 example 和 reference 两个类似的子目录。
删除 about, community,blog等内容。
修改各个页面字眼和内容。
增加导航条目
类似website，增加一个返回注册的导航条。
修改 hugo.toml，增加如下内容，这样可以在增加导航条的同时实现 i18n：
[[languages.en.menu.main]]
name = "Home"
weight = 100
url = "https://cloudruntime.net/en/"
pre = "<i class='fa-solid fa-house'></i>"
[[languages.zh-cn.menu.main]]
name = "返回主页"
weight = 100
url = "https://cloudruntime.net/"
pre = "<i class='fa-solid fa-house'></i>"
发布网站内容
内容发布在 cloudruntime.net/docs 子目录下，因此无需单独建立网站，只要将内容复制到 docs 子目录即可。
在 website/publish.sh 的基础上稍微改动一下发布脚本的细节就好了。
1.7 - 搭建CloudRuntime开发文档
修改模版内容，搭建CloudRuntime开发文档
准备修改 docsy-example 的内容，搭建CloudRuntime 用户文档。
准备仓库
创建 cloudruntime/devdocs 仓库，使用 main 分支：
cd cloudruntime
git clone git@github.com:cloudruntime/devdocs.git
cd devdocs
# 以下方式废弃，会引入原来 docsy 仓库中的所有 commit 内容，造成麻烦
# git remote add upstream git@github.com:cloudruntime/docsy-example.git
# git fetch --all
# git merge upstream/cloudruntime --allow-unrelated-histories
# 直接复制 docs 下的所有内容
cp -r ../docs/* .
# 各种修改
# ......
# 之后一次性提交
git add -A
修改内容
将 docs 目录重命名为 userguide，增加 example 和 reference 两个类似的子目录。
删除 about, community,blog等内容。
修改各个页面字眼和内容。
增加导航条目
类似website，增加一个返回注册的导航条。
修改 hugo.toml，增加如下内容，这样可以在增加导航条的同时实现 i18n：
[[languages.en.menu.main]]
name = "Home"
weight = 100
url = "https://cloudruntime.net/en/"
pre = "<i class='fa-solid fa-house'></i>"
[[languages.zh-cn.menu.main]]
name = "返回主页"
weight = 100
url = "https://cloudruntime.net/"
pre = "<i class='fa-solid fa-house'></i>"
发布网站内容
内容发布在 cloudruntime.net/docs 子目录下，因此无需单独建立网站，只要将内容复制到 docs 子目录即可。
在 website/publish.sh 的基础上稍微改动一下发布脚本的细节就好了。
1.8 - 总结
总结改动的内容
定制完成后，总结改动的内容。
docsy 仓库
分支情况：
main: 完全不改，只同步 上游文件，保持和google/docsy仓库main分支内容的一致local-files: 以main分支为 code base，只修改远程访问地址为本地地址，实现网络加速，没有任何文字内容改动cloudruntime：以local-files分支为 code base，修改内容和文字，为 cloudruntime 网站定制
local-files 分支
修改了 js / css 等文件的地址。
增加了 feedback 的中文 i18n 内容。
这些内容是通用的，可以用在其他地方，比如后面我的学习笔记在更新时就重用了 local-files 分支的代码。
cloudruntime 分支
Merge 了 local-files 分支的改动。
额外的功能：
- 增加了 baidu 统计的功能：直接修改了 footer ，hard code 了 cloudruntime 网站的 baidu 统计代码
docsy-example 仓库
分支情况：
main: 完全不改，只同步 上游文件，保持和google/docsy-example仓库main分支内容的一致cloudruntime：以main分支为 code base，修改内容和文字，为 cloudruntime 网站定制
cloudruntime 分支
- 修改
hugo.toml - 修改
content目录下的内容：主要工作在这里
就没有别的改动了。上面这些改动是 cloudruntime 特有的，不适合用在其他网站。
1.9 - 本地搭建
本地从头开始搭建cloudruntime的编辑环境。
简单记录备忘和快速重复搭建。
准备工作
先安装好：
-
go
-
nodejs
-
hugo
vi ~/.zshrc增加一个 h alias，方便后续使用: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/cloudruntime
cd ~/work/code/cloudruntime
主题仓库
docsy 仓库：
cd ~/work/code/cloudruntime
git clone git@github.com:cloudruntime/docsy.git
cd docsy
git checkout cloudruntime
npm install --save-dev autoprefixer
npm install --save-dev postcss-cli
npm install -D postcss
内容仓库
website 仓库
cd ~/work/code/cloudruntime
git clone git@github.com:cloudruntime/website.git
cd website
# start hugo locally
# h
docs 仓库
cd ~/work/code/cloudruntime
git clone git@github.com:cloudruntime/docs.git
cd docs
# start hugo locally
# h
devdocs 仓库
cd ~/work/code/cloudruntime
git clone git@github.com:cloudruntime/devdocs.git
cd devdocs
# start hugo locally
# h
2 - 学习笔记定制化
为自己的各种学习笔记定制Docsy主题
2.1 - 定制化概述
定制化的目标和主要工作内容概述
对 docsy 主题进行定制化的主要目标是：
- 网络加速：docsy主题使用时需要载入的 图片/css/js 文件，网络地址会被被 GFW 墙，导致访问速度缓慢甚至无法加载。
- 这个工作直接重用 cloudruntime 中的修改
- 修改内容：为学习笔记定制，以便后续在几十个学习笔记中重用这套修改之后的模版。
2.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/ 访问了。
此时的代码完全是上游的代码，除了将依赖关系修改为本地之外，还没有做任何修改。
提交代码改动，此时准备工作完成。
2.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.net"
privacy_policy = ""
url_latest_version = "https://skyao.net/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>
2.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 的内容，重新打造。
2.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.net/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.net整个网站的 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.tomlcontent/_index.html
2.6 - 发布学习笔记
记录发布现有学习笔记到nginx的过程，备用
背景
我的学习笔记发布在 https://skyao.net/learning-xxx 这样的地址下，其中 https://skyao.net 这个网站是我的个人博客网站，也是 基于 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
2.7 - 自动发布学习笔记
自动发布现有学习笔记到nginx
学习笔记有几十个, 平时更新频繁, 内容更新之后往往没有发布最新内容.
因此还是需要一个自动发布的机制, 定期检查各个学习笔记有没有更新, 如果有则触发发布流程, 将最新的内容发布到 nginx 下.
目录结构
学习笔记的父目录一般为 /home/sky/work/code/learning/ , 子目录为 “learning-” 开头的几十个文件夹, 每个子目录是一个独立的 git 仓库.
如:
$ pwd
/home/sky/work/code/learning
$ ls -l
total 196
drwxr-xr-x 9 sky sky 4096 Oct 9 20:15 learning-golang
drwxr-xr-x 9 sky sky 4096 Oct 21 10:33 learning-grpc
drwxr-xr-x 10 sky sky 4096 Oct 21 10:26 learning-hugo
drwxr-xr-x 9 sky sky 4096 Oct 21 10:29 learning-inoreader
drwxr-xr-x 9 sky sky 4096 Oct 21 10:26 learning-java-aot
drwxr-xr-x 9 sky sky 4096 Oct 21 10:29 learning-jdk
drwxr-xr-x 9 sky sky 4096 Oct 21 10:24 learning-kuasar
drwxr-xr-x 9 sky sky 4096 Oct 21 10:33 learning-linux-mint
......
脚本内容(串行版本)
串行版本是一个接一个的处理子目录, 因为子目录比较多,所以速度有点慢:
vi /home/sky/work/code/learning/auto_publish.sh
内容为:
#!/bin/bash
# 自动检查并发布 learning-* 子目录
# 运行环境: Debian 12/13
BASE_DIR="/home/sky/work/code/learning"
PUBLISH_SCRIPT="$BASE_DIR/publish.sh"
# 遍历所有以 learning- 开头的子目录
for repo in "$BASE_DIR"/learning-*; do
if [ -d "$repo/.git" ]; then
cd "$repo" || continue
echo ">>> 检查仓库: $(basename "$repo")"
# 获取远程更新
git fetch origin &>/dev/null
# 判断是否有更新
LOCAL=$(git rev-parse @)
REMOTE=$(git rev-parse @{u} 2>/dev/null)
BASE=$(git merge-base @ @{u} 2>/dev/null)
if [ "$LOCAL" = "$REMOTE" ]; then
echo " 已是最新，无需更新"
elif [ "$LOCAL" = "$BASE" ]; then
echo " 检测到远程更新，执行 git pull..."
git pull --ff-only
echo " 调用发布脚本..."
"$PUBLISH_SCRIPT" "$(basename "$repo")"
elif [ "$REMOTE" = "$BASE" ]; then
echo " 本地有未推送的提交，跳过发布"
else
echo " 本地与远程有分歧，请手动处理"
fi
fi
done
增加执行属性:
chmod +x /home/sky/work/code/learning/auto_publish.sh
跑起来确实比较慢,因为子目录太多了(30上下). 不过可以清晰的看到哪个仓库有更新.
脚本内容(并行版本)
并行版本同时检查所有子目录的更新情况, 好处是执行起来特别快,尤其大部分情况下子目录都是没有内容更新的:
vi /home/sky/work/code/learning/auto_publish_parallel.sh
内容为:
#!/bin/bash
# 自动检查并发布 learning-* 子目录 (并发版本)
# 运行环境: Debian 12/13
BASE_DIR="/home/sky/work/code/learning"
PUBLISH_SCRIPT="$BASE_DIR/publish.sh"
check_and_publish() {
repo="$1"
cd "$repo" || exit 1
repo_name=$(basename "$repo")
echo ">>> 检查仓库: $repo_name"
# 获取远程更新
git fetch origin &>/dev/null
LOCAL=$(git rev-parse @)
REMOTE=$(git rev-parse @{u} 2>/dev/null)
BASE=$(git merge-base @ @{u} 2>/dev/null)
if [ "$LOCAL" = "$REMOTE" ]; then
echo " [$repo_name] 已是最新"
elif [ "$LOCAL" = "$BASE" ]; then
echo " [$repo_name] 检测到远程更新，执行 git pull..."
git pull --ff-only
echo " [$repo_name] 调用发布脚本..."
"$PUBLISH_SCRIPT" "$repo_name"
elif [ "$REMOTE" = "$BASE" ]; then
echo " [$repo_name] 本地有未推送的提交，跳过发布"
else
echo " [$repo_name] 本地与远程有分歧，请手动处理"
fi
}
export -f check_and_publish
export BASE_DIR PUBLISH_SCRIPT
# 遍历所有 learning-* 子目录并发执行
for repo in "$BASE_DIR"/learning-*; do
if [ -d "$repo/.git" ]; then
check_and_publish "$repo" &
fi
done
# 等待所有后台任务完成
wait
echo ">>> 所有仓库检查完成"
增加执行属性:
chmod +x /home/sky/work/code/learning/auto_publish_parallel.sh
手工执行:
/home/sky/work/code/learning/auto_publish_parallel.sh
输出为:
$ ./auto_publish_parallel.sh
>>> 检查仓库: learning-ai-agent
>>> 检查仓库: learning-durabletask
>>> 检查仓库: learning-golang
>>> 检查仓库: learning-computer-hardware
>>> 检查仓库: learning-debian
>>> 检查仓库: learning-grpc
>>> 检查仓库: learning-cloudstate
>>> 检查仓库: learning-esxi
>>> 检查仓库: learning-distributed-state
>>> 检查仓库: learning-datamesh
>>> 检查仓库: learning-inoreader
>>> 检查仓库: learning-mockito
>>> 检查仓库: learning-macos
>>> 检查仓库: learning-git
>>> 检查仓库: learning-openwrt
>>> 检查仓库: learning-cloud-hypervisor
>>> 检查仓库: learning-kuasar
>>> 检查仓库: learning-distributed-transaction
>>> 检查仓库: learning-linux-mint
>>> 检查仓库: learning-hugo
>>> 检查仓库: learning-python
>>> 检查仓库: learning-jdk
>>> 检查仓库: learning-rust
>>> 检查仓库: learning-java-aot
>>> 检查仓库: learning-tokio
>>> 检查仓库: learning-spring-cloud
>>> 检查仓库: learning-ubuntu-server
>>> 检查仓库: learning-windows-server
>>> 检查仓库: learning-windows11
>>> 检查仓库: learning-photoshop
>>> 检查仓库: learning-pve
>>> 检查仓库: learning-serverless
>>> 检查仓库: learning-vscode
[learning-jdk] 已是最新
[learning-grpc] 已是最新
[learning-kuasar] 已是最新
[learning-windows-server] 已是最新
[learning-computer-hardware] 已是最新
[learning-vscode] 已是最新
[learning-cloudstate] 已是最新
[learning-hugo] 已是最新
[learning-windows11] 已是最新
[learning-mockito] 已是最新
[learning-java-aot] 已是最新
[learning-tokio] 已是最新
[learning-esxi] 已是最新
[learning-cloud-hypervisor] 已是最新
[learning-python] 已是最新
[learning-rust] 已是最新
[learning-durabletask] 已是最新
[learning-golang] 已是最新
[learning-pve] 已是最新
[learning-inoreader] 已是最新
[learning-macos] 已是最新
[learning-linux-mint] 已是最新
[learning-spring-cloud] 已是最新
[learning-openwrt] 已是最新
[learning-distributed-state] 已是最新
[learning-debian] 已是最新
[learning-git] 已是最新
[learning-ubuntu-server] 已是最新
[learning-distributed-transaction] 已是最新
[learning-datamesh] 已是最新
[learning-serverless] 已是最新
[learning-photoshop] 已是最新
[learning-ai-agent] 已是最新
>>> 所有仓库检查完成
没有内容更新的情况下, 大概15到20秒就检查完成,速度快多了.
如果多个仓库同时更新, 可能会有并发执行发布人物的性能问题,不过通常我不太会在10分钟内更新多个仓库的内容,所以就不额外处理了(比如设置最大并发数)
设置定时任务
设置定时任务, 每 10 分钟执行一次.
编辑 crontab：
crontab -e
添加一行：
*/10 * * * * /bin/bash /home/sky/work/code/learning/auto_publish_parallel.sh >> /home/sky/work/code/learning/auto_publish_parallel.log 2>&1
这样脚本会每 10 分钟运行一次，并把日志写到 auto_publish.log。
如果不想打印日志:
*/10 * * * * /bin/bash /home/sky/work/code/learning/auto_publish_parallel.sh >/dev/null 2>&1
注意: 用 sky 帐号执行 crontab -e,不要用 root 帐号或者 sudo 执行 crontab -e, 那样编辑的是 root 帐号的 cron,执行命令是用的是 root 用户来执行自动发布版本. 而我的 git 仓库一般都是用 sky 帐号 clone 的. 在新版本的 git 中会报错:
fatal: detected dubious ownership in repository at '/home/sky/work/code/learning/learning-windows-server'
To add an exception for this directory, call:
git config --global --add safe.directory /home/sky/work/code/learning/learning-windows-server
全部发布
有时自动发布脚本因故没能成功执行，而因为 git pull 已经执行，git 的更新已经拉到本地，导致不会激活内容的发布。
因此，新增一个全部发布的脚本，手动执行，强制发布所有内容。作为必要时的补充。
cd /home/sky/work/code/learning
vi all_publish.sh
内容为:
#!/bin/bash
# 自动拉取并发布 learning-* 子目录（带错误处理）
# 运行环境: Debian 12/13
BASE_DIR="/home/sky/work/code/learning"
PUBLISH_SCRIPT="$BASE_DIR/publish.sh"
# 遍历所有以 learning- 开头的子目录
for repo in "$BASE_DIR"/learning-*; do
if [ -d "$repo/.git" ]; then
cd "$repo" || continue
echo ">>> 仓库: $(basename "$repo")"
echo " 执行 git pull..."
if git pull --ff-only; then
echo " git pull 成功，调用发布脚本..."
if "$PUBLISH_SCRIPT" "$(basename "$repo")"; then
echo " 发布成功"
else
echo " 发布脚本执行失败，跳过"
fi
else
echo " git pull 失败，跳过发布"
fi
fi
done
增加执行属性:
chmod +x all_publish.sh
手工执行:
./all_publish.sh
2.8 - 本地搭建
本地从头开始搭建学习笔记的编辑环境。
简单记录备忘和快速重复搭建。
准备工作
先安装好：
-
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
备注：在腾讯云的轻量服务器上，会遇到莫名其妙的问题，需要把上面三个命令修改为：
npm install -g postcss postcss-cli autoprefixer
以全局安装的方式来规避，具体看附录说明。
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
附录：腾讯云问题
我在将 skyao.io 域名修改为 skyao.net 域名之后，网站服务器就从香港搬到了国内，继续使用腾讯云的轻量服务器。
然后就遇到一个莫名其妙的问题，之前从来没有遇到过。具体为，在上面的安装过程中，docsy 仓库和docsy-example 仓库安装完成后，在 learning-xxx 的学习笔记仓库下，执行 hugo 命令时会莫名其妙的失败，报错如下：
Start to build learning-hugo ...
Start building sites …
hugo v0.121.1-00b46fed8e47f7bb0a85d7cfc2d9f1356379b740+extended linux/amd64 BuildDate=2023-12-08T08:47:45Z VendorInfo=gohugoio
Total in 2913 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
Fail to build html content by hugo, exit
当我记得之前都是可以自动下载成功的，而且速度很快，这个方式我在各种服务器上都试过，包括本地机器（windows，linux，macos都有试过），从来没有出现过这个问题。
考虑到这是因为 npm 需要为本项目安装一些依赖，比如前面提到的 postcss postcss-cli autoprefixer，因此尝试增加 –loglevel=silly 参数来查看详细信息：
$ npm install --save-dev autoprefixer --loglevel=silly
......
npm http fetch GET 200 https://registry.npmjs.org/mkdirp/-/mkdirp-3.0.1.tgz 4559ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/hugo-extended/-/hugo-extended-0.120.4.tgz 4603ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz 4645ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.21.tgz 4688ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/isarray/-/isarray-2.0.5.tgz 4701ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz 4703ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz 4703ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz 4730ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001747.tgz 4788ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz 4781ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz 4817ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/log-symbols/-/log-symbols-5.1.0.tgz 4863ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/debug/-/debug-4.4.3.tgz 4874ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz 4889ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz 4893ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/commander/-/commander-2.20.3.tgz 4898ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/file-type/-/file-type-3.9.0.tgz 4914ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/pify/-/pify-3.0.0.tgz 4968ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/file-type/-/file-type-6.2.0.tgz 4999ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/entities/-/entities-6.0.1.tgz 5014ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/entities/-/entities-6.0.1.tgz 5054ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz 5052ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/@popperjs/core/-/core-2.11.8.tgz 5130ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz 5170ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/type-fest/-/type-fest-1.4.0.tgz 5203ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/bootstrap/-/bootstrap-5.2.3.tgz 5330ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/is-stream/-/is-stream-3.0.0.tgz 5549ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/@fortawesome/fontawesome-free/-/fontawesome-free-6.4.2.tgz 6036ms (cache miss)
npm http fetch GET 200 https://registry.npmjs.org/unbzip2-stream/-/unbzip2-stream-1.4.3.tgz 6404ms (cache miss)
npm info run @fortawesome/fontawesome-free@6.4.2 postinstall node_modules/@fortawesome/fontawesome-free node attribution.js
npm info run @fortawesome/fontawesome-free@6.4.2 postinstall { code: 0, signal: null }
npm info run hugo-extended@0.120.4 postinstall node_modules/hugo-extended node postinstall.js
发现是卡死在这个 hugo-extended 的 postinstall 阶段。
google 之后发现：
https://discourse.gohugo.io/t/hugo-115-1-and-postcss-do-not-work-well-enough-to-be-usable/45342/9
最后以全局安装 postcss postcss-cli autoprefixer 这三个依赖的方式来规避这个问题，这样就不必每个项目都安装这些依赖了。
2.9 - 创建一个新的学习笔记
本地从头开始创建一个新的学习笔记的过沉。
简单记录备忘和快速重复搭建。
创建新仓库
创建新仓库，如 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.net/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 命令查看效果了，没问题的话就可以提交，这样一个空白的学习笔记就创建出来了。后续填充内容即可。