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

学习笔记定制化

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

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

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.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>

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.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.toml
content/_index.html

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

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

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 这三个依赖的方式来规避这个问题，这样就不必每个项目都安装这些依赖了。

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 命令查看效果了，没问题的话就可以提交，这样一个空白的学习笔记就创建出来了。后续填充内容即可。