diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index b99efb4..dae4829 100644 --- a/.github/workflows/deploy.yml +++ b/.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: diff --git a/codelabs/assets/202411/1702.webp b/codelabs/assets/202411/1702.webp new file mode 100644 index 0000000..3aaf7c8 Binary files /dev/null and b/codelabs/assets/202411/1702.webp differ diff --git a/codelabs/assets/202411/1703.webp b/codelabs/assets/202411/1703.webp new file mode 100644 index 0000000..d525271 Binary files /dev/null and b/codelabs/assets/202411/1703.webp differ diff --git a/codelabs/assets/202411/1704.webp b/codelabs/assets/202411/1704.webp new file mode 100644 index 0000000..1b3eb8d Binary files /dev/null and b/codelabs/assets/202411/1704.webp differ diff --git a/codelabs/publish-technical-tutorials-in-google-godelab-format.md b/codelabs/publish-technical-tutorials-in-google-godelab-format.md index c87bccc..b3ca048 100644 --- a/codelabs/publish-technical-tutorials-in-google-godelab-format.md +++ b/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 网站可以通过 网址访问。 -Google Developers Codelab 提供了一种引导式编码实践教程体验。大部分 Codelab 会逐步介绍开发小应用或在现有应用中新增功能的过程。其友好的交互体验，以及丰富的资源，使得 Codelab 成为学习新技能的好方法。Google Codelabs 网站可以通过 网址访问。当然，因为 Google 开源了这个网站构建工具，我们也可以基于该工具搭建我们自己的 Codelabs。 +当然，因为 Google 开源了这个网站构建工具，我们也可以基于该工具搭建我们自己的 Codelabs。我们要搭建的网站效果如下截图 + +![alt text](assets/202411/1701.webp) + +> 本文参考自: ，并使用该作者的素材，加以优化。 --- ## 安装基础环境 +Duration: 2 + 需要的环境如下 - `Golang`: ，需要使用到 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 +``` diff --git a/codelabs/publish-technical-tutorials-in-google-godelab-format/codelab.json b/codelabs/publish-technical-tutorials-in-google-godelab-format/codelab.json index 028dbb7..fce2ee1 100644 --- a/codelabs/publish-technical-tutorials-in-google-godelab-format/codelab.json +++ b/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 编写技术教程", diff --git a/codelabs/publish-technical-tutorials-in-google-godelab-format/img/3f84eaa8f616f1f8.webp b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/3f84eaa8f616f1f8.webp new file mode 100644 index 0000000..b18b79a Binary files /dev/null and b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/3f84eaa8f616f1f8.webp differ diff --git a/codelabs/publish-technical-tutorials-in-google-godelab-format/img/6e6113b543a9f0e.jpg b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/6e6113b543a9f0e.jpg new file mode 100644 index 0000000..dd9f4f9 Binary files /dev/null and b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/6e6113b543a9f0e.jpg differ diff --git a/codelabs/publish-technical-tutorials-in-google-godelab-format/img/a994f5e0b3688714.webp b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/a994f5e0b3688714.webp new file mode 100644 index 0000000..d525271 Binary files /dev/null and b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/a994f5e0b3688714.webp differ diff --git a/codelabs/publish-technical-tutorials-in-google-godelab-format/img/c027539655f6f6f0.webp b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/c027539655f6f6f0.webp new file mode 100644 index 0000000..3aaf7c8 Binary files /dev/null and b/codelabs/publish-technical-tutorials-in-google-godelab-format/img/c027539655f6f6f0.webp differ diff --git a/codelabs/publish-technical-tutorials-in-google-godelab-format/index.html b/codelabs/publish-technical-tutorials-in-google-godelab-format/index.html index 2a7e5f1..2e316a9 100644 --- a/codelabs/publish-technical-tutorials-in-google-godelab-format/index.html +++ b/codelabs/publish-technical-tutorials-in-google-godelab-format/index.html @@ -29,13 +29,15 @@ feedback-link="https://github.com/webtechwiki/codelabs/issues"> -

Codelabs是什么？

-

Google Developers Codelab 提供了一种引导式编码实践教程体验。大部分 Codelab 会逐步介绍开发小应用或在现有应用中新增功能的过程。其友好的交互体验，以及丰富的资源，使得 Codelab 成为学习新技能的好方法。Google Codelabs 网站可以通过 https://codelabs.developers.google.cn/?hl=zh-cn 网址访问。当然，因为 Google 开源了这个网站构建工具，我们也可以基于该工具搭建我们自己的 Codelabs。

+

Google Developers Codelab 提供了一种引导式编码实践教程体验。大部分 Codelab 会逐步介绍开发小应用或在现有应用中新增功能的过程。其友好的交互体验，以及丰富的资源，使得 Codelab 成为学习新技能的好方法。Google Codelabs 网站可以通过 https://codelabs.developers.google.cn/?hl=zh-cn 网址访问。

+

当然，因为 Google 开源了这个网站构建工具，我们也可以基于该工具搭建我们自己的 Codelabs。我们要搭建的网站效果如下截图

+

alt text

+

本文参考自: https://medium.com/@zarinlo/publish-technical-tutorials-in-google-codelab-format-b07ef76972cd

 - +

需要的环境如下

  • Golang: https://golang.google.cn/，需要使用到 Golang 语言插件，因此需要安装 Golang 语言环境；
    • @@ -54,14 +56,238 @@

    Codelabs是什么？

    go install github.com/googlecodelabs/tools/claat@latest

    安装完成 Nodejs 之后，直接使用以下命令全局安装 gulp-cli

    -
    npm config set registry https://registry.npmmirror.com
+
    # 设置阿里云镜像
+npm config set registry https://registry.npmmirror.com
+# 安装gulp-cli
+npm install -g gulp-cli
 
    
 
 
       
     
-      
+      
+        
    Codelabs 构建工具已经开源，我们可以从 Github 下载源代码，使用如下命令拉取最想项目
    
+
    git clone https://github.com/googlecodelabs/tools
+
    
+
    拉下来的是整个项目的源代码，我们只需要使用到网站基础框架代码即可，网站基础框架在 site 目录中，执行如下命令运行网站
    
+
    # 进入网站目录
+cd site
+# 安装依赖
+npm install
+# 运行网站
+gulp serve
+
    
+
    看到如下结果表示运行成功
    
+
    alt text
    
+
    现在网站已经运行起来了，使用浏览器打开 http://127.0.0.1:8000，可以看到如下页面
    
+
    alt text
    
+
    现在网站还没有内容，我们将在下一节中添加内容。
    
+
+
+          
+    
+      
+        
    先创建一个 codelabs 文件夹，并在该目录下创建资源目录
    
+
    # 创建codelabs文件夹
+mkdir codelabs
+# 进入文件夹
+cd codelabs/
+# 创建资源目录
+mkdir assets
+
    
+
    此时，文件目录结构如下
    
+
    tools
+|-- site
+|--|-- codelabs
+|--|--|-- assets
+
    
+
    我们先准备一张图片叫 puppy.jpg 放到 assets 目录中。然后在 codelabs 目录下，创建一个 markdown 文件，命名为 how-to-write-a-codelab.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 文件，用于写入分类的基本信息
    
+
    {
+  "title": "Codelab",
+  "description": "与Codelab相关的介绍与帮助",
+  "logoUrl": "/codelab/codelab-logo.png",
+  "tags": ["codelab"],
+  "exclude": [
+    ".*-about$",
+    "^lang-.*"
+  ]
+}
+
    
+
    另外，可以我们新进分类的 css 样式，在 /site/app/styles 目录下有一个名为 _categories.scss 的文件。打开该文件并在底部添加自己的条目，因为我们新增了一个类别叫codelab，所以添加了以下内容：
    
+
    @include codelab-card(['codelab'], #FC0023, 'codelab.svg');
+
    
+
    最后准备好一个 codelab.svg 图标，并放在 /site/app/images/icons 目录下，完成这些操作后，该分类系的 codelab 条目将显示 css 中配置的图标，并且按钮会按照我们配置的颜色显示。到此，我们就新建好了一个 codelab 文章以及一个分类。
    
+
+
+          
+    
+      
+        
    使用 claat 工具来将我们编写的 markdown 导出 html 网页，如下命令
    
+
    ## go into codelabs folder
+cd codelabs
+## export md to html
+claat export how-to-write-a-codelab.md
+
    
+
    现在我们已经编写了第一个 codelab 并成功导出了 html 文件。在 site 目录中执行以下命令运行网站
    
+
    # 指定codelabs目录为codelabs网站内容目录并运行网站
+gulp serve --codelabs-dir=codelabs
+
    
+
    成功执行之后，再次打开浏览器，我们新建的文章就出来了，可以通过这个链接访问我新建的效果 https://codelabs.webtech.wiki/codelabs/how-to-write-a-codelab/index.html#0
    
+
+
+          
+    
+      
+        
    完成已经步骤之后，我们可以将 site 目录添加到 github 仓库中，并设置 GithubAction 来执行自动部署，我配置好的 Action 如下
    
+
    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'  # 设置 Node.js 版本为 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  # 上传 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
+
    
+