Hugo快速构建简洁的Apache官网

tool
go, hugo, website

因为最近要快速构建一个待上线的 Apache 的官网, 所以包括选型在内, 记录了下使用其中最经典主题 docsy 的一些核心事项.

0x00. 安装准备

个人博客时期多用 Hexo 来构建静态页面, 现在 Go 编写的 Hugo 逐渐代替 Node 具有更好的性能和更适宜多类型网站的需求, 而关于 Hexo/Hugo/Jekyll 对比就不多说了, 其中 docsy 作为 google 开源的技术官网模板, 也只支持 hugo 目前, 整体很适合开源项目展示 + 文档使用

核心参考官方文档, 这里仅以 Linux (Ubuntu) 为例做一个示例, 大概也就几步:

  1. 安装 Hugo 相关依赖
  2. 下载喜欢的主题然后初始化 (可在此修改主题配置)
  3. 丢一个 md 文档然后启动测试
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 0. 使用最新版的 hugo_extend (必须选扩展版, 否则有些主题无法使用), 解压后是单文件放/usr/bin 下
wget
https://github.do/https://github.com/gohugoio/hugo/releases/download/v0.95.0/hugo_extended_0.95.0_Linux-64bit.tar.gz

sudo install hugo /usr/bin # 一键添加环境变量
sudo apt install -y npm

# -1. (可选)直接 apt 即可安装 v0.8 版 (版本过低不建议)

# 2. 创建一个 /path/to/site 文件夹然后初始化
mkdir site && hugo new site quickstart

# 3. 下载喜欢的主题, 然后加入 git 子项目
git clone https://github.com/themefisher/meghna-hugo.git themes/meghna
git init
git submodule add https://github.com/themefisher/meghna-hugo.git themes/meghna

# 修改配置, 创建一个测试文章
echo theme = \"meghna\" >> config.toml
hugo new posts/hello.md && vi content/posts/hello.md # 修改 draft 为 false

# 4. 启动服务 (注意要绑定堆外访问, 不知道为何官方把这个选项给去了, 填写 ip 是不行的..)
 hugo server -D -b http://ip -p port --bind=0.0.0.0

PS: 以下是我简单挑选比较适合官网的主题

  • Meghna - demo 320 star - 2021-9-01 - 全栏目滚动响应式, 支持多语言 (文档)
  • Docsy - 1512star - 2022-1-18
  • Arcana - demo - 1 star - 2022-2-20 - 简洁, 简单
  • Tella - 12 star - 202-2-17 - 简洁, 简单
  • Grayscale - 36 star - 2021-1-23
  • Html5up-alpha - 9 star - 2020-5-29 - 简约, 美观

Docsy

因为热度和文档相关性等问题, docsy 是一个很实用文档功能很强的主题, 单独说一下, 稍微麻烦一些, 强烈建议主题都使用官方模板 (example site), 当然也可以直接使用 docsy 的实际生产部署的具体 example:

1
2
3
4
5
6
7
8
9
10
11
12
# 在 hugo 项目下安装相关依赖
git clone https://api.mtr.pub/google/docsy-example.git
#git clone https://api.mtr.pub/google/docsy.git themes/docsy # 这个不用下, 上面包含

# 修改 .gitsubmodules 文件的链接, 否则下载可能巨慢无比

git submodule sync # 否则更新不生效...真坑呀 (后续我离线让它固化下来了)

# 官方建议分开安装, 按照说的来把
npm install -D autoprefixer # v10.4.4
npm install -D postcss-cli # v9.1.0
npm install -D postcss # v8.4.12

从 hugegraph-website 中部署 hugo 也需要先生成 html 等静态文件 (默认在 public) 中, 然后我们需要将其转移到 asf-site 分支上, 原本 github action 里有一个很好用可以一键完成这个 push & public 操作的应用, 但是由于 Apache 严格的 action 限制, 也没法使用, 只有类似 gitook 那样封装一个脚本来执行了…

0x02. 社区用户

因为上述所说 docsy 因为网络问题, 可能会让社区同学上手就卡住半天, 这里我先采用了自行把依赖全部以非git submodule的模式直接固化下来, 这样社区的同学就可以 3 步快速启动官网并进行修改, 在果内的网络环境下是一个可行的解决方案… 如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 0. install npm & hugo if you don't have it

# Mac version (0.95 extend)
wget https://github.do/https://github.com/gohugoio/hugo/releases/download/v0.95.0/hugo_extended_0.95.0_macOS-64bit.tar.gz

# Linux version (0.95 extend)
wget https://github.do/https://github.com/gohugoio/hugo/releases/download/v0.95.0/hugo_extended_0.95.0_Linux-64bit.tar.gz

# 解压后 hugo 是单二进制文件, 可直接使用, 或推荐放 /usr/bin 及环境变量下.
sudo install hugo /usr/bin # 如果 mac 提示没有权限, 你可以直接使用它, 也可以 mv hugo /usr/bin 代替

# 1. download website's source code
git clone -b website https://github.com/hugegraph/hugegraph-doc.git website

# if download slowly or failed, try the proxy url
git clone -b website https://api.mtr.pub/hugegraph/hugegraph-doc.git website # or https://github.do/https://github.com/hugegraph/hugegraph-doc.git

# 2. install npm dependencies in project root dir
cd website && npm install

# 3. just start server in localhost now (Don't need do anything else)
hugo server

# (optional) if you want modify ip or port, try like this
hugo server -b http://127.0.0.1 -p 80 --bind=0.0.0.0

如何参与贡献官网

其实核心就是 html + css + js 以及文档相关的调整, 基本是纯前端内容, 详细的主题修改配置可参考Docsy Content and Customization, 下面我列了一下最主要的几个部分, 社区同学则可快速上手:

  1. config.toml in the root dir is global config
  2. config.toml in the ./themes/docsy is theme config
  3. content dir contains multi language contens (docs/index-html/blog/about/bg-imgage), it’s the most important dir
    • content/en represent english site, we do need translate the doc in it (可先用 google 翻译，紧急)
    • content/cn represent chinese site (需要汉化其中英文部分)

然后很贴心的, docsy 给了一些典型的开源社区使用的例子 example website , 非常适合人手紧缺的情况下, 普通人快速进行一些 DIY 和参考

然后社区同学参与需要有个计划和概览才方便管理, 这里推荐直接使用 github 自带的project看板, 如下:

image-20220602224100659

0x03. 上线

Apache 的官网提供了两个方式进行映射, 但是由于 asf 的文档有段时间没有更新, 所以其中有一些很关键的信息缺失, 导致普通人如果只看官方文档可能会折腾很久都映射不成功…下面直接说解决办法, 问题的关键是因为我们需要在特定映射分支里也附带一个.asf.yml 文件, 而不能只在 master 中, 而这点很难发现.. (因为并不合理)

image-20220602223127909

那么我们就可以愉快的拥有两个域名, 其中一个对大众开放是稳定版本, 另一个作为过渡和测试新版使用, 这样比直接操作稳定版合理

image-20220602223324565

参考资料:

  1. Hugo 官网
  2. Docsy 官网
  3. .asf.yml doc - Apache Wiki