feature: 完成“使用 Google Codelab 编写技术教程”

.github/workflows/deploy.yml

@@ -35,18 +35,18 @@ jobs:
       # Step 3: Install dependencies
       - name: Install dependencies
         run: |
-          npm install && npm install -g gulp-cli # 安装项目依赖
+          npm install && npm install -g gulp-cli
 
       # Step 4: Build the project
       - name: Build project
         run: |
-          gulp dist --codelabs-dir=codelabs  # 运行打包命令
+          gulp dist --codelabs-dir=codelabs
 
       # Step 5: Upload dist folder
       - name: Upload dist directory as artifact
         uses: actions/upload-pages-artifact@v1
         with:
-          path: ./dist  # 上传 dist 目录中的内容
+          path: ./dist
 
   # Deployment job
   deploy:

codelabs/publish-technical-tutorials-in-google-godelab-format.md

@@ -12,14 +12,20 @@ Feedback Link: https://github.com/webtechwiki/codelabs/issues
 
 Duration: 1
 
-### Codelabs是什么？
+Google Developers Codelab 提供了一种引导式编码实践教程体验。大部分 Codelab 会逐步介绍开发小应用或在现有应用中新增功能的过程。其友好的交互体验，以及丰富的资源，使得 Codelab 成为学习新技能的好方法。Google Codelabs 网站可以通过 <https://codelabs.developers.google.cn/?hl=zh-cn> 网址访问。
 
-Google Developers Codelab 提供了一种引导式编码实践教程体验。大部分 Codelab 会逐步介绍开发小应用或在现有应用中新增功能的过程。其友好的交互体验，以及丰富的资源，使得 Codelab 成为学习新技能的好方法。Google Codelabs 网站可以通过 <https://codelabs.developers.google.cn/?hl=zh-cn> 网址访问。当然，因为 Google 开源了这个网站构建工具，我们也可以基于该工具搭建我们自己的 Codelabs。
+当然，因为 Google 开源了这个网站构建工具，我们也可以基于该工具搭建我们自己的 Codelabs。我们要搭建的网站效果如下截图
+
+![alt text](assets/202411/1701.webp)
+
+> 本文参考自: <https://medium.com/@zarinlo/publish-technical-tutorials-in-google-codelab-format-b07ef76972cd>，并使用该作者的素材，加以优化。
 
 ---
 
 ## 安装基础环境
 
+Duration: 2
+
 需要的环境如下
 
 - `Golang`: <https://golang.google.cn/>，需要使用到 Golang 语言插件，因此需要安装 Golang 语言环境；
@@ -46,7 +52,270 @@ go install github.com/googlecodelabs/tools/claat@latest
 安装完成 `Nodejs` 之后，直接使用以下命令全局安装 `gulp-cli`
 
 ```bash
+# 设置阿里云镜像
 npm config set registry https://registry.npmmirror.com
+# 安装gulp-cli
+npm install -g gulp-cli
+```
+
+## 运行Codelabs网站
+
+Duration: 2
+
+Codelabs 构建工具已经开源，我们可以从 Github 下载源代码，使用如下命令拉取最想项目
+
+```bash
+git clone https://github.com/googlecodelabs/tools
+```
+
+拉下来的是整个项目的源代码，我们只需要使用到网站基础框架代码即可，网站基础框架在 `site` 目录中，执行如下命令运行网站
+
+```bash
+# 进入网站目录
+cd site
+# 安装依赖
+npm install
+# 运行网站
+gulp serve
+```
+
+看到如下结果表示运行成功
+
+![alt text](assets/202411/1702.webp)
+
+现在网站已经运行起来了，使用浏览器打开 `http://127.0.0.1:8000`，可以看到如下页面
+
+![alt text](assets/202411/1703.webp)
+
+现在网站还没有内容，我们将在下一节中添加内容。
+
+## 新增Codelab和分类
+
+Duration: 3
+
+先创建一个 `codelabs` 文件夹，并在该目录下创建资源目录
+
+```bash
+# 创建codelabs文件夹
+mkdir codelabs
+# 进入文件夹
+cd codelabs/
+# 创建资源目录
+mkdir assets
+```
+
+此时，文件目录结构如下
+
+```bash
+tools
+|-- site
+|--|-- codelabs
+|--|--|-- assets
+```
+
+我们先准备一张图片叫 `puppy.jpg` 放到 `assets` 目录中。然后在 `codelabs` 目录下，创建一个 markdown 文件，命名为 `how-to-write-a-codelab.md`，并在文件中添加如下内容
+
+````md
+summary: 如何编写 Codelab
+id: how-to-write-a-codelab
+categories: codelab
+tags: codelab
+status: Published
+authors: panhy
+Feedback Link: https://github.com/webtechwiki/codelabs/issues
+
+# 如何编写 Codelab
+
+## 概述  
+
+Duration: 1
+
+### 你将学到什么  
+
+- 如何设置每个幻灯片所需的时间  
+- 如何包含代码片段  
+- 如何超链接项目  
+- 如何插入图片  
+- 其他技巧  
+
+---
+
+## 设置时长  
+
+Duration: 2
+
+要指示浏览每张幻灯片所需的时间，请在每个二级标题（即 `##`）下设置 `Duration` 为一个整数。  
+这个整数代表分钟数。例如，设置 `Duration: 4` 表示完成这一张幻灯片需要 4 分钟。  
+
+总时间将会自动计算，并在你创建 Codelab 后显示出来。  
+
+---
+
+## 代码片段  
+
+Duration: 3
+
+要包含代码片段，你可以采用以下方法：  
+
+- **内联高亮**：使用键盘上的反引号（`` ` ``）来实现。  
+- **嵌入代码**：使用代码块显示完整代码。  
+
+### JavaScript 示例  
+
+```javascript
+{ 
+  key1: "string", 
+  key2: integer,
+  key3: "string"
+}
+```
+
+### Java 示例  
+
+```java
+for (statement 1; statement 2; statement 3) {
+  // 要执行的代码块
+}
+```
+
+---
+
+## 超链接和嵌入图片  
+
+Duration: 1
+
+### 超链接  
+
+[YouTube - Halsey 播放列表](https://www.youtube.com/user/iamhalsey/playlists)  
+
+### 图片  
+
+![图片替代文本](assets/puppy.jpg)  
+
+---
+
+## 其他技巧  
+
+Duration: 1
+
+查看官方文档：[Codelab 格式指南](https://github.com/googlecodelabs/tools/blob/master/FORMAT-GUIDE.md)  
+````
+
+因为我们在创建文章的时候，指定了元信息中的分类为 `codelab` ，并且指定的 tag 为 `codelab`，我们必须新建 `codelabs` 分类。
+
+在 `site/app/views` 目录下新建一个 `codelab`，并在该目录下新建 `view.json` 文件，用于写入分类的基本信息
+
+```json
+{
+  "title": "Codelab",
+  "description": "与Codelab相关的介绍与帮助",
+  "logoUrl": "/codelab/codelab-logo.png",
+  "tags": ["codelab"],
+  "exclude": [
+    ".*-about$",
+    "^lang-.*"
+  ]
+}
+```
+
+另外，可以我们新进分类的 css 样式，在 `/site/app/styles` 目录下有一个名为 `_categories.scss` 的文件。打开该文件并在底部添加自己的条目，因为我们新增了一个类别叫`codelab`，所以添加了以下内容：
+
+```css
+@include codelab-card(['codelab'], #FC0023, 'codelab.svg');
+```
+
+最后准备好一个 `codelab.svg` 图标，并放在 `/site/app/images/icons` 目录下，完成这些操作后，该分类系的 codelab 条目将显示 css 中配置的图标，并且按钮会按照我们配置的颜色显示。到此，我们就新建好了一个 `codelab` 文章以及一个分类。
+
+## 运行Codelabs
+
+Duration: 1
+
+使用 `claat` 工具来将我们编写的 markdown 导出 html 网页，如下命令
+
+```bash
+## go into codelabs folder
+cd codelabs
+## export md to html
+claat export how-to-write-a-codelab.md
 ```
 
-## 运行 codelabs 网站
+现在我们已经编写了第一个 codelab 并成功导出了 html 文件。在 site 目录中执行以下命令运行网站
+
+```bash
+# 指定codelabs目录为codelabs网站内容目录并运行网站
+gulp serve --codelabs-dir=codelabs
+```
+
+成功执行之后，再次打开浏览器，我们新建的文章就显示在 Codelabs 主页里了，并且也在对应的 `codelab` 分类中。效果如下图：
+
+![alt text](assets/202411/1704.webp)
+
+## 发布到GithubPages
+
+Duration: 3
+
+完成已经步骤之后，我们可以将 site 目录添加到 github 仓库中，并设置 GithubAction 来执行自动部署，我配置好的 Action 如下
+
+```yml
+name: Deploy Website
+
+on:
+  push:
+    branches:
+      - main  # 监听 main 分支的 push 事件
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Step 1: Checkout the repository
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      # Step 2: Set up Node.js 12 environment
+      - name: Set up Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: '12'
+
+      # Step 3: Install dependencies
+      - name: Install dependencies
+        run: |
+          npm install && npm install -g gulp-cli
+
+      # Step 4: Build the project
+      - name: Build project
+        run: |
+          gulp dist --codelabs-dir=codelabs
+
+      # Step 5: Upload dist folder
+      - name: Upload dist directory as artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+```

codelabs/publish-technical-tutorials-in-google-godelab-format/codelab.json

@@ -3,9 +3,9 @@
   "format": "html",
   "prefix": "https://storage.googleapis.com",
   "mainga": "UA-49880327-14",
-  "updated": "2024-11-17T13:33:48+08:00",
+  "updated": "2024-11-17T21:18:31+08:00",
   "id": "publish-technical-tutorials-in-google-godelab-format",
-  "duration": 1,
+  "duration": 12,
   "title": "使用 Google Codelab 格式编写技术教程",
   "authors": "panhy",
   "summary": "使用 Google Codelab 编写技术教程",