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

cloudruntime定制化

为cloudruntime网站定制Docsy主题

1: 定制化概述
2: 定制化的准备工作
3: 使用本地文件加速网络访问
4: 为CloudRuntime网站特别定制
5: 搭建CloudRuntime官方网站
6: 搭建CloudRuntime用户文档
7: 搭建CloudRuntime开发文档
8: 总结
9: 本地搭建

1 - 定制化概述

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

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

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

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 - 使用本地文件加速网络访问

使用本地文件加速，避免被墙

准备修改 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";

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

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>

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

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

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

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

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

cloudruntime定制化

1 - 定制化概述

2 - 定制化的准备工作

安装hugo

Fork 仓库

克隆代码

建立分支

运行

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

准备local目录

修改js文件

修改案例

修改css文件

fonts.googleapis.com

4 - 为CloudRuntime网站特别定制

修改 docsy-example 仓库

准备分支

修改通用内容

修改hugo.toml

多语言设置

复制中文内容

修改为 CloudRuntime

修改 docsy 仓库

准备分支

修改通用内容

百度统计

5 - 搭建CloudRuntime官方网站

准备仓库

修改用户案例

增加导航条目

删除示例内容

发布网站内容

准备工作

准备 docsy 主题

准备 cloudruntime 的 发布目录

发布 website 网站

配置 nginx

开启 https

6 - 搭建CloudRuntime用户文档

准备仓库

修改内容

增加导航条目

发布网站内容

7 - 搭建CloudRuntime开发文档

准备仓库

修改内容

增加导航条目

发布网站内容

8 - 总结

docsy 仓库

local-files 分支

cloudruntime 分支

docsy-example 仓库

cloudruntime 分支

9 - 本地搭建

准备工作

主题仓库

内容仓库

website 仓库

docs 仓库

devdocs 仓库

准备 cloudruntime 的发布目录