同样地，如果想添加一个顶层section，只需添加一个新的子目录，不过如果您想使用任何现有的Docsy模板，而不是默认的模板，您需要在每个页面的前言中明确指定布局或内容类型。例如，如果您创建了一个新的目录 content/en/amazing，并希望该自定义部分中的一个或多个页面使用 Docsy 的 docs 模板，您可以在每个页面的前言中添加 type: docs。

---
title: "My amazing new section"
weight: 1
type: docs
description: >
    A special section with a docs layout.    
---

或者，在你的项目的布局目录中，根据现有的模板之一，为你的新栏目创建你自己的页面模板。

TODO: 理论上只要找到合适的页面模版，就可以在 docsy 主题中支持更多的section。有需要时再研究。

从Hugo 0.76开始，不需要在每一个页面上都指定 type: blog，可以在索引页中指定:

---
title: "Latest News"
linkTitle: "News"
menu:
  main:
    weight: 30

cascade:
- type: "blog"
---

这就方便太多了。不然每个页面都要指定很麻烦的。

RSS feeds

rss_sections = ["docs", "docsy"]

1.2 - 外观和体验

docsy的外观和体验

参考： Look and Feel | Docsy

颜色和css

这些暂时先用默认吧。

代码高亮

继续用默认的 Chroma 和 tango style。

Mermaid的支持

有 plantuml 就先不用这个。

plantuml的支持

试试这个：

participant participant as Foo
actor       actor       as Foo1
boundary    boundary    as Foo2
control     control     as Foo3
entity      entity      as Foo4
database    database    as Foo5
collections collections as Foo6
queue       queue       as Foo7
Foo -> Foo1 : To actor 
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue

开启方式：

[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/"

注意 guessSyntax 必须设置为false，否则无法生效：

[markup]
  [markup.highlight]
      guessSyntax = "false"

1.3 - 导航

docsy的导航

参考：https://www.docsy.dev/docs/adding-content/navigation/

顶级菜单

每个 section 都可以通过 weight 参数指定在顶级菜单中的排序，从小到大，从左到右排序：

---
title: "Welcome to Docsy"
linkTitle: "Documentation"
menu:
  main:
    weight: 30
    pre: <i class='fas fa-paper-plane'></i>
---

注意这里可以通过 pre 设置每个菜单项的css，如为每个菜单项设置一个图标，非常实用。

图标来自 Font Awesome，具体选择可以参考：

https://fontawesome.com/v5.15/icons?d=gallery&p=2 内容有点多
http://www.fontawesome.com.cn/faicons/ ：看这里会比较简单直接

也可以单独增加一个带链接的菜单项，修改 config.toml：

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"
    pre = "<i class='fab fa-github'></i>"
    post = "<span class='alert'>New!</span>"

这里同样可以使用 pre 来增加图标，用 post 来增加说明。

左侧导航菜单的设置

默认显示section所有的页面，当页面数量较多/层次较深时不太好看，而且太长也不好找内容。

可以通过 params.ui 参数来控制 sidebar 的显示：

[params.ui]
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = true
ul_show = 1
sidebar_menu_foldable = true
sidebar_cache_limit = 100

具体解释参见： https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options

为每个页面加图标

可以在左侧的 sidebar 中为每个页面设置图标，如本页面展示的：

title: "导航"
date: 2021-08-13
weight: 230
icon: fas fa-tools

可以手工添加一个链接到左侧的 sidebar，新建一个页面，内容如下：

---
title: "手工链接1"
date: 2021-08-13
weight: 231
manualLink: "https://skyao.io"
description: >
  docsy的手工链接展示
---

也可以通过 manualLinkRelref 指定一个 hugo 的 relref：

---
title: "手工链接2"
date: 2021-08-13
weight: 232
manualLinkRelref: "/docsy/content/navigation"
description: >
  docsy的手工链接展示2
---

详见：https://www.docsy.dev/docs/adding-content/navigation/#add-manual-links-to-the-section-menu

同样也可以通过 icon 来为链接增加图标。

搜索

我使用 google custom search engine，具体见启用CSE搜索

1.4 - 手工链接1

docsy的手工链接展示

1.5 - 手工链接2

docsy的手工链接展示2

1.6 - 版本

docsy的多版本支持

参考：Doc Versioning | Docsy

用的时候再验证吧，现在做学习笔记没有这个需要。

1.7 - shortcodes

docsy的shortcodes支持

参考：Docsy Shortcodes | Docsy

Hugo让你定义和使用快捷代码，而不是从头开始编写你的所有网站页面。这些是可重复使用的内容片段，你可以将其包含在你的页面中，通常使用HTML来创造在简单的Markdown中很难或无法做到的效果。短码也可以有参数，例如，让你在一个花哨的短码文本框中添加自己的文字。除了Hugo的内置短代码，Docsy还提供了一些自己的短代码来帮助你建立你的页面。

Blocks

cover/lead/section/feature/link-down，这是 docsy 首页用到的几个 shortcode。

helpers

alert/警告

警报短代码创建了警报块，可用于显示通知或警告：

Warning

This is a warning.

color 是 theme colors, 可以是： primary, info, warning 等。

pageinfo

pageinfo短代码创建了一个文本框，您可以用它来为一个页面添加横幅信息：例如，让用户知道该页面包含占位符内容，该内容已被废弃，或者它记录了一个测试版功能。

This is placeholder content.

imgproc

imgproc短码在当前页面包中找到一张图片，并根据一组处理指令对其进行缩放。

TODO: 没想好什么情况下需要用，平时还是简单的图片插入容易直接看到图片结果

swaggerui

swaggerui短码可以放置在具有swagger布局的页面内的任何地方；它使用任何OpenAPI YAML或JSON文件作为源文件渲染Swagger UI。这可以托管在你喜欢的任何地方，例如在你的网站的根/static文件夹中。

iframe

TODO: 暂时没想到用的地方

标签式面板

这个在涉及多种实现，如多个系统/多个编程需要/多个条件时特别有用。

有时，在编写内容时，采用标签式窗格是非常有用的。一个常见的用例是显示多个语法高亮的代码块，展示同一个问题，以及如何用不同的编程语言来解决这个问题。作为一个例子，下面的表格显示了著名的Hello world！程序的特定语言变体，当人们从头开始学习一种新的编程语言时，通常会先写这个程序。

Docsy模板提供了两个快捷键tabpane和tab，让你轻松地创建标签式窗格。为了了解如何使用它们，请看下面的代码块，它显示为一个有三个标签的窗格。

    Welcome!

    Herzlich willkommen!

    Karibu sana!

标签式面板是通过两个 shortcode 实现的:

tabpane 短代码，它是标签的容器元素。这个 shortcode 可以选择性地持有命名的参数lang和/或highlight。这些可选参数的值作为第二个LANG和第三个OPTIONS参数传递给Hugo内置的highlight函数，该函数用于渲染各个标签的代码块。如果标签的标题文本等于标签代码块中使用的语言（如上面第一个标签窗格的例子），你可以在周围的标签窗格短代码中指定langEqualsHeader=true。然后，单个标签的标题文本被自动设置为各自标签的语言参数。
各种 tab 短代码，实际上代表了你想显示的标签。我们建议为每个文本指定命名参数header，以便设置每个标签的标题文本。如果需要，你还可以为每个标签指定命名参数lang和highlight。这允许你覆盖在父标签页短代码中给出的设置。如果语言既没有在tabpane中也没有在tabshortcode中指定，它默认为Hugo的站点变量 .Site.Language.Lang 。

卡片面板

在编写内容时，有时将类似的文本块或代码片

TODO: 没用过，看着不错，在需要并排展示，或者对比展示时非常有用。效果会比简单的 list 要好看。

1.8 - 图标图片

docsy的图标图片支持，在项目中添加和定制标识、图标和图像。

参考：Logos and Images | Docsy

Logo

在项目中添加项目标识作为 assets/icons/logo.svg。这将覆盖主题中默认的 Docsy 标志。

如果当前项目没有设置，则默认使用 docsy 模版下的 assets/icons/logo.svg 和 assets/icons/logo.png。其中在每个页面的左上角出现的 Logo 必须是要通过设置 svg 图片来覆盖，png 格式的 Logo 文件暂时还没有看到用的地方。

备注：logo 图片不要求是正方形，长方形的图片也是可以的，而且显示效果也还可以。比如 hugo 学习的 Logo 图片就是长条形的。

favicon

最简单的方法是通过 http://cthedot.de/icongen（它可以让你在一张图片上创建大量的图标尺寸和选项）和/或 https://favicon.io ，并把它们放在你的网站项目的 static/favicons 目录中。这将覆盖主题中的默认图标。

请注意，https://favicon.io 并不像Icongen那样可以创建广泛的尺寸，但可以让你快速地从文本中创建图标：如果你想创建文本图标，你可以使用这个网站来生成它们，然后使用 Icongen 从你生成的 .png 文件中创建更多尺寸（如果需要）。

如果你有特殊的favicon要求，你可以用你的链接创建你自己的 layouts/partials/favicons.html 。

实践：

准备png文件：先找一个项目对应的 Logo 文件，最好是正方形，png格式，背景透明。如果不是，用 photoshop 等工具进行修改，如通过选择工具或者抓图的方式将主体复制出来到新的图片（注意新图片的背景设置为透明），然后将画布大小调整为正方形，四周留一点空白。然后导出为 png 格式。
通过 http://cthedot.de/icongen 网站生成各种格式的 icon 文件，主要在默认的前四个选项的基础上勾选增加第五个 andord app
将生成的文件下载下来，将各种icon图片复制到当前项目下的 static/favicons 目录中

2 - 常见问题

Docsy主题常见问题和解决方式

2.1 - scss报错文件找不到

scss报错 File to import not found or unreadable 的解决方式

问题描述

有时，在使用 docsy 的项目中，执行 hugo 命令时会遇到这样的报错：

$ hugo101 -D -F server --disableFastRender --bind "0.0.0.0" --port 4343

Start building sites … 
hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended darwin/arm64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): "/Users/sky/work/code/dapr-cn/docsy/assets/scss/main.scss:6:1": File to import not found or unreadable: ../vendor/bootstrap/scss/bootstrap.
Built in 37 ms

问题发生的比较奇怪，因为之前还正常工作，内容也没有修改。git statu 没有文件改动，但就是报上述错误。

暂时只在 mac m1 max 上发现过一次。

文件夹目录如下：

$ ls
dapr-cn-site-source  docsy

dapr-cn-site-source 中的 config.toml 文件设置为 :

[module]
  # uncomment line below for temporary local development of module
  replacements = "github.com/google/docsy -> ../../docsy"

解决方式

进入 docsy 目录，执行 npm i bootstrap 可以解决问题：

$ cd docsy
$ npm i bootstrap
npm WARN deprecated popper.js@1.16.1: You can find the new Popper v2 at @popperjs/core, this package is dedicated to the legacy v1

added 180 packages, and audited 181 packages in 27s

40 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

参考资料

google 之后找到这个文章，学习到 npm i bootstrap 命令解决问题：

javascript - Error: File to import not found or unreadable: ~bootstrap/scss/bootstrap - Stack Overflow

3 - 定制化

定制化Docsy主题以更好的适应中国国情

3.1 - cloudruntime定制化

为cloudruntime网站定制Docsy主题

3.1.1 - 定制化概述

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

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

网络加速：docsy主题使用时需要载入的图片/css/js 文件，网络地址会被被 GFW 墙，导致访问速度缓慢甚至无法加载。

3.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/ 访问了。

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

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

3.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";

后面如果遇到问题再调整。

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

3.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 的页面。

3.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 的基础上稍微改动一下发布脚本的细节就好了。

3.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 的基础上稍微改动一下发布脚本的细节就好了。

3.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 特有的，不适合用在其他网站。

3.2 - 学习笔记定制化

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

3.2.1 - 定制化概述

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

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

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

3.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/ 访问了。

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

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

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

3.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 的内容，重新打造。

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

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

3.2.7 - 本地搭建

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

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

准备工作

先安装好：

go
nodejs

hugo

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

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

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

Docsy主题

1 - 内容定制

1.1 - 添加内容

content section

自定义section

RSS feeds

1.2 - 外观和体验

颜色和css

代码高亮

Mermaid的支持

plantuml的支持

1.3 - 导航

顶级菜单

左侧导航菜单的设置

为每个页面加图标

手工添加链接到sidebar

搜索

1.4 - 手工链接1

1.5 - 手工链接2

1.6 - 版本

1.7 - shortcodes

Blocks

helpers

alert/警告

Warning

pageinfo

imgproc

swaggerui

iframe

标签式面板

卡片面板

1.8 - 图标图片

Logo

favicon

2 - 常见问题

2.1 - scss报错文件找不到

问题描述

解决方式

参考资料

3 - 定制化

3.1 - cloudruntime定制化

3.1.1 - 定制化概述

3.1.2 - 定制化的准备工作

安装hugo

Fork 仓库

克隆代码

建立分支

运行

3.1.3 - 使用本地文件加速网络访问

准备local目录

修改js文件

修改案例

修改css文件

fonts.googleapis.com

3.1.4 - 为CloudRuntime网站特别定制

修改 docsy-example 仓库

准备分支

修改通用内容

修改hugo.toml

多语言设置

复制中文内容

修改为 CloudRuntime

修改 docsy 仓库

准备分支

修改通用内容

百度统计

3.1.5 - 搭建CloudRuntime官方网站

准备仓库

修改用户案例

增加导航条目

删除示例内容

发布网站内容

准备工作

准备 docsy 主题

准备 cloudruntime 的 发布目录

发布 website 网站

配置 nginx

开启 https

3.1.6 - 搭建CloudRuntime用户文档

准备仓库

准备 cloudruntime 的发布目录