前言
来啦老铁！
最近，我所在的测开团队，有意使用统一的文档工具，并给我提供了一个关键词，那就是：
-
Google Codelabs
想想这个东西已经欠了 1 个多礼拜了，是时候调研一下了，我们的目标：
- 能拥有自己的codelabs~
- 对比过去接触过的文档工具，如基于 vuepress 的（下一篇文章学习）；
开始前，先附几个链接：
- Git 地址：https://github.com/googlecodelabs/tools.git
- Google Codelabs 官网中国镜像：http://clmirror.storage.googleapis.com/index.html
- 学习如何搭建自己的codelabs：https://zhuanlan.zhihu.com/p/338303316
整体步骤
- 开发环境搭建；
- 项目准备；
- Example 探索；
- 开发第一个页面；
- 定制化 landing page；
- 图床；
- 发布；
1. 开发环境搭建；
（以 macOS 为例）
1）安装 GO 语言；
命令行依次执行命令：
brew search go
brew install [email protected]
brew link [email protected] --force
go version
2）安装 Node.js v10+；
安装 nodejs (以安装 v14 为例)：
brew search nodejs
brew install node@14
环境变量设置：
echo 'export PATH="/usr/local/opt/node@14/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
如果使用 zsh 终端，则:
echo 'export PATH="/usr/local/opt/node@14/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
2. 项目准备；
1）clone 项目；
git clone https://github.com/googlecodelabs/tools.git
2）安装项目依赖；
npm install
3）安装 Codelabs command line tool；
- 首先拿到 claat/bin 的全路径，如：/Users/dylan.z.zhang/Desktop/learning/google-codelabs/claat/bin
- 设置 claat/bin 的环境变量；
vi ~/.bash_profile
i
添加 claat 路径
esc
:wq!
source ~/.bash_profile
- 如果使用zsh终端，类似地修改 ~/.zshrc 文件，即可。
4) 安装 Codelabs command line tool 的依赖；
cd claat
go get ./...
5) 验证 claat 是否设置正确；
claat
3. Example 探索；
1）Example - 本地文件式浏览页面；
- 项目根目录下的 example 文件夹，下的 codelab.md 文件可以做演示用；
- 生成 example 的静态页面；
// example 文件夹下执行命令
claat export codelab.md
执行完成后悔生成一个新文件夹，双击打开文件夹下的 index.html 就可以以本地方式打开 example；
可以看到一个交互式的页面已经展示在我们面前了，离成功越来越近啦~
2）Example - web serve 式浏览页面；
// example 文件夹下执行命令
claat serve
执行完成后会自动在浏览器上打开页面：
点击页面上的 “codelab-4-codelab-markdown” 就可以浏览 example 页面了；
不过截止目前位置，都还是直接浏览文件，不像一个文档空间，咱们继续学习~
4. 开发自己的页面；
1）在项目下创建自己的文件夹，名字随意，如：codelabs；
2）在 codelabs 下创建 .md 文件，也可以在 codelabs 下再建文件夹，例如：codelabs/test/hello.md；
3）在 codelabs/test/hello.md 内按 codelabs 的格式要求（后续介绍），编写页面内容，如：
summary: 测试，第一个codelab
id: hello
categories: android
tags: inwebinar
status: Published
authors: kk
Feedback Link: https://github.com/wkk-knight/
# 第一个codelab
## 开始学习
Duration: 1
## 啦啦啦
测试
写你想写的内容
用md语法写就行
## 学会了吗？
Duration: 2
学会了吗？
来点代码
```kotlin
fun main() {
println("hello world")
}
## 学废了吗？
Duration: 3
学废了吗？
再来点代码
'''
kotlin
fun main() {
println("hello world")
}
'''
## 结束
Duration: 1
注意：
-
categories 字段配置，取的是 site/app/images/icons/ 文件夹下 .svg 文件的文件名（也不全是，有的可以，有的不行，可以多试试不同名字，看看效果），如 android、cloud 等，如:
- android:
- cloud：
cloud
4）“编译” codelabs/test/hello.md 文件；
cd codelabs
claat export test/hello.md
5）在 site/app/views 底下创建 codelabs 文件夹，然后拷贝 codelabs 文件夹下的内容至 site/app/views/codelabs 文件夹下；
6）本地部署 codelabs 站点；
cd site
npm install
gulp serve --codelabs-dir=./app/codelabs
7）访问本地 codelabs 站点；
浏览器访问站点：http://localhost:8000
8）将上述命令行操作简化；
- 修改 site/package.json 文件，增加：
"scripts": {
"gulp_serve": "gulp serve --codelabs-dir=./app/codelabs",
"gulp_dist": "gulp dist --codelabs-dir=./app/codelabs",
"gulp_serve_dist": "gulp serve:dist --codelabs-dir=./app/codelabs"
}
- 修改根目录的 package.json 文件，scripts 下增加：
"compile": "cd codelabs && claat export **/*.md",
"serve": "rm -rf ./site/app/views/codelabs/ && cp -rf codelabs/ ./site/app/codelabs/ && cd site && npm run gulp_serve",
"dist": "rm -rf ./site/app/views/codelabs/ && cp -rf codelabs/ ./site/app/codelabs/ && cd site && npm run gulp_dist",
"build:dev": "npm run compile && npm run serve",
"publish":"npm run compile && npm run dist && scp XXX"
这样，本地部署，我们就只需要执行一个命令即可：
npm run build:dev
到此为止，我们已基本完成了第一个 codelabs 页面的开发和本地部署，成功已近在咫尺，继续加油！
5. 定制化 landing page；
官方参考文档：https://github.com/googlecodelabs/tools/blob/main/site/README.md
1）修改主页布局、logo、文字内容等；
修改 site/app/views/default/index.html 和 site/app/views/default/view.json 文件，特别是 site/app/views/default/index.html 文件，读者可自行修改、验证；
2）类别；
- 主页上有一个类别入口，我们可以修改、添加自己的类别:
-
如何修改、添加自己的类别？
site/app/views 底下创建自己的文件夹，文件夹下创建 view.json，并按照规则编写 view.json 文件，如 site/app/views/inwebinar/view.json
{
"title": "Inwebinar",
"description": "这是 Inwebinar 板块",
"logoUrl": "https://pic2.zhimg.com/80/v2-c5c66d7e2d6b99ae9cc4f3f61dc6354d_1440w.jpg",
"tags": [
"inwebinar"
]
}
特别注意的是，tags 是和 codelab 文件上tags 设置的tags是有关联的，相同的话，就会在这个类别显示这个codelab，一个类别可以拥有多个 tags；
6. 图床；
页面中，若使用到图片、文件等，我们可以考虑使用 Minio 对象存储服务，这块在上一篇文章中已介绍，详情请见：
- Minio 对象存储服务实践
7. 发布；
后续服务器部署，执行以下命令输出静态文件，然后将产物丢到 nginx 服务器即可，这个命令已在根目录下的 package.json 写好（上传到服务器的命令 scp 命令除外）；
npm run publish
好了，codelabs 的基本情况我们都摸了一遍，今天就到此为止吧，下一篇文章，我们尽可能来学习一下基于 vuepress 的文档工具，欢迎留意~
如果本文对您有帮助，麻烦动动手指点点赞？
非常感谢！