avatar

目录
CodeLabs Env Setup

Codelabs环境搭建

本文对应的Codelab已同步值Codelabs.top

前言

在日常工作中,文档管理无疑很是重要。

说到文档管理,一般第一个会想到的解决方案是搭建wiki服务器。但wiki有一个不好的体验就是界面步骤不够友好,对于教程类的文档体验更是糟糕。前段时间在逛Google官方网站的时候,看到Google-Codelabs页面,发现里面的流水线式的案例呈现很是流畅,页面展示如下

codelabs-office

其实这个是google-codelab-tools工具生成的,目前已在github上开源。不仅仅支持直接将文档上传到google官方的codelab服务器上,也支持发布在自己的私服或者一些免费的公网服务器上。

接下来我们将借助codelab-toos,一步步搭建属于自己的code-lab服务。

环境准备

本文以ubuntu18.04为例进程环境搭建,macOs,以及其他Linux环境的搭建流程也大致一致在此就不在复述。

安装软件

  • Go 语言
    Code
    1
    sudo apt install golang
  • Node.jsV10+ and npm
    Code
    1
    sudo apt install nodejs
  • claat(google官网维护的开源终端命令行工具)
    Code
    1
    go get github.com/googlecodelabs/tools/claat

安装完成后会在$HOME/go/bin下生产claat的执行文件

环境配置

安装完Go软件后,默认会使用$HOME/go为工作目录,也可以手动指定目录,设置GOPATH为自定义目录。为当前用户配置环境变量,编辑.bashrc或者.profile.

Code
1
2
3
4
5
## not required if you’re only using Go modules 
export GOPATH=$HOME/go
export GOROOT=/usr/local/go
## required
export PATH=$PATH:$HOME/go/bin

启动页面

克隆

[Codelabs](git clone https://github.com/googlecodelabs/tools)启动页面已开源在github仓储

Code
1
git clone https://github.com/googlecodelabs/tools

依赖

工程clone后进入site文件夹,安装依赖

Code
1
2
3
4
5
## navigate to folder
cd site/
## install dependencies
npm install
npm install -g gulp-cli

运行

在开发模式下为该站点提供服务,运行以下命令:

Code
1
gulp serve

启动成功后,访问[http// localhost:8000](http// localhost:8000)就可以看到主页效果了。

Codelabs-main-page

现在我们已经设置了主页面,但没有codelab的item入口,接下来让我们编写一个codelab。

编写Codelab

目前codelab支持markdown和Google Doc,由于国内的的一些原因,Google Doc接触的机会不多,因此下文将以md文档为示例。

创建文件夹

在site目录创建codelabs文件夹,然后在codelabs文件夹下创建assets文件夹,asserts文件夹下你可以存储图片等素材。

Code
1
2
3
4
5
6
## create codelabs folder
mkdir codelabs
## go into directory
cd codelabs/
## create assets folder
mkdir assets

现在文件目录结构应该如下所示

Code
1
2
3
4
tools
|-- site
|--|-- codelabs
|--|--|-- assets

创建md文档

在codelabs文件夹下,创建一个md文档,命名如下:how-to-write-a-codelab.md
文件内容如下:

Code
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
summary: 如何编写Codelab
id: how-to-write-a-codelab-md
categories: Sample
tags: sample
status: Published
authors: laird.li
Feedback Link: https://lairdli.top

# 如何编写一个Codelab by MD

## 概述
Duration: 1

### 您将学到什么
- 如何设置标题格式
- 如何设置每张滑动页面的显示时间
- 如何包含代码段
- 如何设置超链接项目
- 如何包含图像
- 其他



## 设置标题
Duration: 2

codelab中标题格式如下:
- 主标题 主标题为一级标题(即“#”)
- 次标题 次标题为二级标题(即“##”)
- 页面标题 页面类的标题从二级标题往后依次类推

注意:标题前无需手动加上序号,序号在生成codelab时会自动生成、

## 设置时间
Duration: 2

为了表明每张滑动页面需要花费多长时间,请将每个次标题下添加“Duration”字段。
单位为分钟。 例如您设置“Duration:4”,那么一张特定的滑动页面将需要4分钟才能完成。

总时间将自动为您计算,并在创建后显示在代码实验室入口上。


## 引用代码
Duration: 3

同md格式
要包含代码段,您可以做一些事情。
- 双击键盘 "`"来进行内联突出显示:
- 在"`"嵌入式代码

### JavaScript
```javascript
{
key1: "string",
key2: integer,
key3: "string"
}
``

### Java

```java
for (statement 1; statement 2; statement 3) {
// code block to be executed
}
``


## 超链接和嵌入式图像
Duration: 1
### 超链接
同md格式
[lairdli.top](https://lairdli.top)
[codelabs.top](https://codelabs.top)

### 图片
同md格式
![alt-text-here](assets/puppy.png)

## 其他
Duration: 1

在此处查看官方文档: [Codelab Formatting Guide](https://github.com/googlecodelabs/tools/blob/master/FORMAT-GUIDE.md)

添加素材

md内容中我们引用了一张puppy.png的图片,因而需要在assets文件夹中,添加一张名为puppy.png的图片

转换网页

在完成md文档的编写工作后,需要用claat工具将md文档转换为html的网页文档

codelables目录下,运行如下命令

shell
1
2
3
4
# go into codelabs folder
cd codelabs
## export md to html
claat export how-to-write-a-codelab.md

转换完成后,clatt工具会根据md文档中头部声明的id字段,在当前目录下生成对应的文件夹。md文档的每一次修改,都需要转换一次。现在目录结构如下

Code
1
2
3
4
5
6
7
8
9
├── assets
│   └── puppy.png
├── how-to-write-a-codelab-md
│   ├── codelab.json
│   ├── img
│   │   └── 8590eca3e4b7c6ef.png
│   └── index.html
├── how-to-write-a-codelab.md
└── README.md

现在完成了md文档的的格式转换后,需要重新启动web服务

启动服务

Ctr+C断开之前的gulp serve启动的cmd-session.运行如下命令

shell
1
2
3
4
# go back to site folder
cd ..
# re-run command
gulp serve --codelabs-dir=codelabs
codelabs-page codelab-detail

展示优化

通过上一步骤,已经完成了一个codelab编写,转换,运行的主要流程,但为了UI展示的更加美观,还可以自定义分类,事件,颜色等等。

分类图标

  1. 编辑site/app/styles/_categories.scss,在文件尾部添加自定义的分类主题,例如:
Code
1
@include codelab-card(['sample'], #FC0023, 'sample.svg');
  1. 前往iconfont.cn,搜索关键字“sample”,找到一个你喜欢的素材,然后下载对应svg文件。

    将下载的文件重命名为sample.svg,并放置在site/app/images/icons目录下。

  2. Ctr+C断开之前的gulp serve启动的cmd-session.重新启动web服务

Code
1
gulp serve --codelabs-dir=codelabs

category-icon

如上图,箭头所指示的地方即为刚添加的sample分类图标。

需要注意的是,当只有一个codelabs时,默认不会显示分类选择框,要显示分类显示类别,需要至少两个不同分类的codelab。现在我们创建第二个分类codelab

  1. 拷贝上面的how-to-write-a-codelab.md文档
  2. 重命名文档为how-to-write-a-codelab-web.md
  3. 重命名文档头部id为how-to-write-a-codelab-web.md
  4. 重命令文档头部categories为“Web”
  5. claat命令转换文档
  6. 重新运行web服务
codelabs-categorylist

如上图,箭头所指示的地方即为刚添加的sample和web分类图标。 选择对应的分类能过滤不同的codelabs

事件归档

codelabs除了支持类别过滤外,还支持事件主页分类。点击choose an event默认会出现Visual Studio Live选项,选中点击后页面会跳转到 http://localhost:8000/vslive

codelab-vslive-view

Codelabs的分类页面位于site/app/views文件夹下,进入到site/app/views,会发现vslive文件夹,在此我们可以删除或者新建编辑分类页面。如需删除直接删除对应文件夹即可。下面演示如何新建一个事件页面。

  1. 拷贝vslive文件夹,并重命名为lairdli

  2. 进入lairdli文件夹,修改view.json相关内容

    json
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    {
    "title": "黎明鸟飞去",
    "description": "黎明鸟飞去 博文对应相关教程,博客地址:http://lairdli.top,微信公众号:黎明鸟飞去",
    "logoUrl": "/lairdli/lairdli-logo.png",
    "tags": ["lairdli"],
    "exclude": [
    ".*-about$",
    "^lang-.*"
    ]
    }
  3. 在同级目录新增lairdli-logo.png

  4. 修改site/codelabs文件夹下对应的md文档头部tags描述,改为新增的lairli,这样codelab就和事件绑定了

    Code
    1
    2
    3
    4
    5
    6
    7
    summary: 如何编写Codelab
    id: how-to-write-a-codelab-md
    categories: Sample
    tags: lairdli
    status: Published
    authors: laird.li
    Feedback Link: https://lairdli.top
  5. 重新export文档,并重启web服务

codelab-lairdli-view

主页图标栏

默认的主题栏目展示如下

codelabs-title-icon-default

替换步骤如下

  1. 进入site/app/images文件夹
  2. 用自己的logo,替换logo.png素材
  3. 重启web服务
codelabs-title-logo-modify

主页提示语

codelabs默认主要提示语为一串英文,且页面没做多语言适配,此处我们不讨论多语言适配,只简单定位如何修改主要提示语。

修改步骤如下

  1. 打开site/app/view/default/index.html文件

  2. 定位banner部分,修改相关内容

    html
    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
    {# Event pages force down attribute. On homepage, it's applied dynamically. #}
    <header id="banner" {% if view.id != 'default' -%}down{%- else %}down$="[[_toBoolean(selectedFilter)]]"{%- endif %}>
    <div class="site-width">
    {% if view.id == 'default' %}
    <h2 class="banner-title">欢迎来到 Codelabs.top!h2>
    <div class="banner-description"
    data-filter-selected$="{% raw %}[[_toBoolean(selectedFilter)]]{% endraw %}">
    <p class="banner-info">
    Codelabs.top 提供了一种引导式动手编码教程体验。对应黎明鸟飞去相关技术博客。
    <br>
    <a href="https://lairdli.top">黎明鸟飞去博客a>
    p>
    {%- else -%}
    <div class="banner-description">
    <img id="logo" src="{{view.logoUrl}}" alt="Event logo">
    <div class="banner-meta">
    <h3>{{view.title}}h3>
    {% if view.description -%}
    <p>{{view.description}}p>
    {%- endif %}
    div>
    {%- endif %}
    div>
    div>
    header>
    1. 重启运行web服务
codelabs-tips.jpg

底部链接条

codelabs默认底部链接没有实现,添加底部链接步骤如下

  1. 打开site/app/view/default/index.html文件

  2. 定位到

  3. 修改对应的链接地址

    html
    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
    26
    27
    28
    29
       
    <footer id="footer">
    <div class="footer-wrapper site-width">
    <div class="link-list">
    <label>联系label>
    <ul>
    <li><a href="https://lairdli.top/about/">关于我a>li>
    ul>
    div>
    <div class="link-list">
    <label>博客label>
    <ul>
    <li><a href="https://lairdli.top/">主页a>li>
    ul>
    div>
    <div class="link-list">
    <label>留言label>
    <ul>
    <li><a href="https://lairdli.top/link/">反馈a>li>
    ul>
    div>
    <div class="link-list">
    <label>友链label>
    <ul>
    <li><a href="https://lairdli.top/link/">交换a>li>
    ul>
    div>
    div>
    footer>
  4. 重新运行web服务

codelab-foot

发布Codelabs

codelabs支持发布到Google官方网站,也支持发布到私有服务器,当然也支持发布到公网服务器。

发布到官方服务器

由于国内网的一些原因,发布到Google官方网站步骤,暂不做复述,具体参考:

Publish Codelabs to Google Codelabs

发布到公网服务器

本文以github-page(*.github.io)为例 其他静态web服务器类似。

步骤如下:

  1. site目录执行gulp serve --codelabs-dir=codelabs,会在site目录下生成build文件夹。我们通过浏览器访问的网页资源,其实就是build文件夹中的产物。

  2. 拷贝build文件夹,重命名为web

  3. 拷贝codelabs文件夹到web文件夹

  4. 在github服务上新建一个仓储*username*.github.io空间,用做静态网站仓储.

    具体开启GitHub Pages参考https://pages.github.com/

  5. 将web文件夹同步到github上

设置完成后就可以通过https://username.github.io访问codelabs了。

发布到私有服务器

发布到私有服务器,需要服务器已搭建好apache或tomcat或nginx等web服务器。

本文以ubuntu上的apache服务器为说明。步骤如下

  1. site目录执行gulp serve --codelabs-dir=codelabs,会在site目录下生成build文件夹。我们通过浏览器访问的网页资源,其实就是build文件夹中的产物。

  2. 拷贝build文件夹,重命名为web

  3. 拷贝codelabs文件夹到web文件夹

  4. 将web文件夹内容同步到ubuntu服务上,例如我的目录为

    /home/lairdli/codelabs/web

  5. 进入apache配置目录 /etc/apache2/

  6. 进入sites-available拷贝默认配置sudo cp 000-default.conf codelabs.conf

  7. 编辑 codelabs.conf,修改对应的端口号,资源路径等

    Code
    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
    26
    27
    28
    29
    30
    31
    32
    33

    # The ServerName directive sets the request scheme, hostname and port that
    # the server uses to identify itself. This is used when creating
    # redirection URLs. In the context of virtual hosts, the ServerName
    # specifies what hostname must appear in the request's Host: header to
    # match this virtual host. For the default virtual host (this file) this
    # value is not decisive as it is used as a last resort host regardless.
    # However, you must set it for any further virtual host explicitly.
    ServerName codelabs.top

    ServerAdmin webmaster@localhost:9001
    DocumentRoot /home/lairdli/codelabs/web


    AllowOverride All


    # Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
    # error, crit, alert, emerg.
    # It is also possible to configure the loglevel for particular
    # modules, e.g.
    #LogLevel info ssl:warn

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined

    # For most configuration files from conf-available/, which are
    # enabled or disabled at a global level, it is possible to
    # include a line for only one particular virtual host. For example the
    # following line enables the CGI configuration for this host only
    # after it has been globally disabled with "a2disconf".
    #Include conf-available/serve-cgi-bin.conf

  8. 编辑/etc/apache2/ports.conf新增监听端口号

    Code
    1
    Listen 9001
  9. 重启appach服务 sudo service apache2 restart

设置完成后就可以通过https://local-server-ip:9001访问codelabs了。

其他

可能遇到的问题

  1. fatal: unable to access ‘https://github.com/googlecodelabs/tools/': Failed to connect to github.com port 443: 连接超时
    解决方法:

    Code
    1
    2
    3
    1 下载离线包https://github.com/googlecodelabs/tools/tree/master/claat
    2 $GOPATH/src/github.com/googlecodelabs/tools目录下解压
    3 执行 go get github.com/googlecodelabs/tools/claat
  2. package golang.org/x/net/… timeout
    package golang.org/x/oauth2:…timout
    解决方法:

    Code
    1
    2
    3
    4
    mkdir -p $GOPATH/src/golang.org/x/
    cd $GOPATH/src/golang.org/x/
    git clone https://github.com/golang/net.git net
    git clone https://github.com/golang/oauth2.git oauth2
  3. npm install fail
    解决方法:nodejs版本太低,ubuntu升级

    Code
    1
    2
    3
    sudo apt-get install  npm
    sudo npm install n -g
    sudo n stable
  4. gulp启动web服务后,http://localhost:8000可以访问,但通过http://ip:8000访问不了
    解决方法:修改site/node_modules/gulp-webserver/src/index.js.
    将host:localhost更改为“host”:"0.0.0.0"
    这样通过localhost或ip地址都可以访问,当然如果有需要,端口号也可以在此处修改

    Code
    1
    2
    3
    4
    5
    6
    7
    //host:'localhost'
    host: '0.0.0.0',
    port: 8000,
    path: '/',
    fallback: false,
    https: false,
    open: false,

参考

文章作者: laird.li
文章链接: https://lairdli.top/2020/09/26/CodeLabs-Env-Setup/
版权声明: 本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 黎明鸟飞去

评论