From cc88f25486e5667a3a1d5c5a703f7310dd86717c Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 17:40:23 -0300 Subject: [PATCH 1/8] feat: try use a google colab scheme for new paths --- .github/workflows/gh-deploy.yml | 21 +++ google-colab/codelab-101.md | 225 ++++++++++++++++++++++++++++++++ 2 files changed, 246 insertions(+) create mode 100644 google-colab/codelab-101.md diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index e3627b46..9581d6ea 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -53,3 +53,24 @@ jobs: - name: Deploy πŸš€ run: python3 -m mkdocs gh-deploy --force --remote-branch ${{ steps.branch_check.outputs.env_name }} + + - name: Deploy Colabs from google-colab directory πŸš€ + run: | + # Access google-colab folder + # Install go + # Install go install github.com/googlecodelabs/tools/claat@latest + # List all .md files in a variable + # Execute claat export for all .md files + # Checkout branch ${{ steps.branch_check.outputs.env_name }} + # Commit google-colab folder + cd google-colab + go get github.com/googlecodelabs/tools/claat@latest + files=$(find . -name "*.md") + for file in $files; do + claat export $file + done + cd .. + # See actual branch + git branch + # git add google-colab + # git commit -m "Update google-colab paths" \ No newline at end of file diff --git a/google-colab/codelab-101.md b/google-colab/codelab-101.md new file mode 100644 index 00000000..7c273fe4 --- /dev/null +++ b/google-colab/codelab-101.md @@ -0,0 +1,225 @@ +author: samlinux +summary: PΓ‘gina modelo sobre o novo modelo de Codelabs. +id: codelab-101 +categories: codelab, 101-category +environments: Web +status: Published +feedback link: https://github.com/orgs/codaqui/discussions/new/choose +analytics account: G-CL043JTTND + +# Create a CodeLab with CLaaT + +## CodeLab Overview +Duration: 0:01:00 + +In this Codelab we create a short tutorial with the CLaaT (Codelabs as a Thing) tool and publish it as a static site. + +Codelabs are interactive instructional tutorials which can be authored in Google Docs using some simple formatting conventions. You can also author codelabs using markdown syntax like in this tutorial. For more information about Codelabs check out the references. + +The basic building process of a Codelab tutorial can be divided into following steps: + +1. Install the CLaat tool if not already done. +2. Write your tutorial with markdown or Google Docs. +3. Use to CLaat tool to build the static HTML site. +4. Publish the tutorial on the internet into the Web2 or Web3 sphere. + +___This tutorial is written by Bole Roland.___ + +## Install Claat +Duration: 0:04:00 + +Firstly, you have to install the CLaat tool. For the installation process you have two possibilities: You can use the native bianry version or a Docker based version. + +In this tutorial we use the binary MacOs version. You can download the proper version for your OS here https://github.com/googlecodelabs/tools/releases/tag/v2.2.4. + +After the download copy the claat-darwin-amd64 file to the $HOME/usr/local/bin folder and rename it for better usage. + +```bash +# copy the bianry file to the users bin folder +cp claat-darwin-amd64 $HOME/usr/local/bin + +# rename the command, alternatively you can create a symlink as well +mv $HOME/usr/local/bin/claat-darwin-amd64 $HOME/usr/local/bin/claat +``` + +Make sure that you have the $HOME/usr/local/bin folder in your $PATH. Check your setup with the following command which should bring up the command's help section. + +```bash +claat -h +``` + +Well done! Your preparation is completed. Now you can move forward and write your first tutorial. + + +## Create the tutorial +Duration: 0:04:00 + +The tutorial is basically written in one markdown file. CLaat itself divides your tutorial into sections. The section is represented by a HTML header h2 tag which is expressed in markdown with the '##' sign. + +You can start by selecting a base folder for your tutorial. You can call this folder lab01. Then, create a markdown file for your content inside of this folder. + +The markdown file is divided into two sections: + +1. metadata +2. content + +### Add the metadata +Copy and paste the headers below into your markdown file and change the values appropriately. Guidelines are available below the sample headers. + +``` bash +author: Author Name +summary: Summary of your codelab that is human readable +id: unique-codelab-identifier +categories: codelab,markdown,internet computer +environments: Web +status: Published +feedback link: A link where users can go to provide feedback (e.g. the git repo) +analytics account: Google Analytics ID +``` +According to the offical documentation the metadata consists of key-value pairs of the form "key: value". Keys cannot contain colons and separate metadata fields must be separated by blank lines. At present, values must all be on one line. All metadata must come before the title. Any arbitrary keys and values may be used. However, only the following will be understood by the renderer: + +* Summary: A human-readable summary of the codelab. Defaults to blank. +* Id: An identifier composed of lowercase letters ideally describing the + content of the codelab. This field should be unique among + codelabs. +* Categories: A comma-separated list of the topics the codelab covers. +* Environments: A list of environments the codelab should be discoverable in. + Codelabs marked "Web" will be visible at the codelabs index. Codelabs marked + "Kiosk" will only be available at codelabs kiosks which have special + equipment attached. +* Status: The publication status of the codelab. Valid values are: + - Draft: Codelab is not finished. + - Published: Codelab is finished and visible. + - Deprecated: Codelab is considered stale and should not be widely advertised. + - Hidden: Codelab is not shown in index. +* Feedback Link: A link to send users to if they wish to leave feedback on the + codelab. +* Analytics Account: A Google Analytics ID to include with all codelab pages. + +### Add the Content +Next, add your title using a single '#' character. For your content you can use any valid markdown. + +Example +```bash +# Title of your codelab +``` + +#### Add Section and Duration +Then, for each section use Header 2 h2 or '##' and specify an optional duration beneath for time remaining calculations. Optional section times will be used to automatically total and remaining tutorial times. In markdown you have to use the following format: hh:mm:ss. + +Example +``` bash +## Section 1 +Duration: 0:02:00 +``` + +#### Add Section Content +Now, as you have a section to your titled codelab, go ahead and add some content for this section. + +Example +``` bash +## Content section 1 +Write some valid markdown to represent your tutorial content. +``` + +Finally, a full example would look like this: +```bash +author: Author name +summary: Summary of your codelab that is human readable +id: unique-codelab-identifier +categories: codelab,markdown,internet computer +environments: Web +status: Published +feedback link: A link where users can go to provide feedback (e.g. the git repo) +analytics account: Google Analytics ID + +# Title of codelab + +## Section 1 +Duration: 0:02:00 + +Content of section 1. +``` + +After finishing your content writing you are ready to build the static HTML version of this tutorial. + +## Build static HTML +Duration: 0:04:00 + + +To create a ready to use static codelab you can use the following command. +```bash +claat export index.md +``` + +Below, you can find the result. The result is a ready to use index.html file. In detail the CLaat tool creates a folder with the name of the "id" value from your metadata and puts the needed HTML and used images into that folder. + +```bash +β”œβ”€β”€ index.md +└── lab01 + β”œβ”€β”€ codelab.json + └── index.html +``` + +After building the static version of your short tutorial you can use the CLaat tool for a preview as well. + +## Preview the tutorial +Duration: 0:04:00 + +The CLaat tool also allows the preview of your tutorial. Use the following command to run a local webserver on port 9090. Make sure you are in your base folder. + +```bash +claat serve +``` + +Now, open your browser and open the following link http://localhost:9090. The CLaat tool has placed static web content in a directory specified by your unique "id" and you can view it locally by opening the index.html page. + +## Use custom CSS +Duration: 0:04:00 + +The CLaat tool comes with a ready to use HTML implementation that includes CSS as well. Sometimes you want to change the CSS settings. One way to do that is presented below. + +To make things easier, make a short build script. In the base folder of your tutorial create the following script. + +```bash +#!/bin/bash + +# export or rebuild codelabs +claat export index.md + +# add a custom css file before the end of the html body tag +sed -i "" -e "/body/i\\ +" lab01/index.html +``` + +Create a CSS folder in the new lab01 folder and put your custom CSS in it. Name your CSS file format.css. Every time you rebuild your tutorial the **sed** command will add the link to the custom CSS file before the end of the HTML body. In this approach you overwrite the pre-built CSS definitions. + +The ready structure should look like this. + +```bash +tree . +. +β”œβ”€β”€ build.sh +β”œβ”€β”€ index.md +└── lab01 + β”œβ”€β”€ codelab.json + β”œβ”€β”€ css + β”‚ └── format.css + β”œβ”€β”€ img + └── index.html +``` + +Make sure that the build script has the proper execution rights. +```bash +chmod 755 build.sh +``` + +Now, you can rebuild your tutorial with custom CSS every time you make some changes to your tutorial. + +```bash +./build.sh +``` + +## References + +- [codelabs.developers.google.com](https://codelabs.developers.google.com/) \ No newline at end of file From 011a06047ec2daabdc543d562f6228a7c0f27b33 Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 17:42:47 -0300 Subject: [PATCH 2/8] setup go on workflows --- .github/workflows/gh-deploy.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index 9581d6ea..2c535296 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -54,6 +54,11 @@ jobs: - name: Deploy πŸš€ run: python3 -m mkdocs gh-deploy --force --remote-branch ${{ steps.branch_check.outputs.env_name }} + - name: Set up Go + uses: actions/setup-go@v4 + with: + go-version: '>=1.18.0' + - name: Deploy Colabs from google-colab directory πŸš€ run: | # Access google-colab folder From b556301c50e9e4919473fa295e6554b551c9a77d Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 17:44:53 -0300 Subject: [PATCH 3/8] setup go correctly --- .github/workflows/gh-deploy.yml | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index 2c535296..d0c5678b 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -51,7 +51,7 @@ jobs: python3 -m pip install -r requirements.txt python3 -m pip install -e mkdocs-material-insider - - name: Deploy πŸš€ + - name: Deploy mkdocs πŸš€ run: python3 -m mkdocs gh-deploy --force --remote-branch ${{ steps.branch_check.outputs.env_name }} - name: Set up Go @@ -61,15 +61,10 @@ jobs: - name: Deploy Colabs from google-colab directory πŸš€ run: | - # Access google-colab folder - # Install go - # Install go install github.com/googlecodelabs/tools/claat@latest - # List all .md files in a variable - # Execute claat export for all .md files - # Checkout branch ${{ steps.branch_check.outputs.env_name }} - # Commit google-colab folder cd google-colab - go get github.com/googlecodelabs/tools/claat@latest + go install github.com/googlecodelabs/tools/claat@latest + export GOPATH="$HOME/go" + PATH="$GOPATH/bin:$PATH" files=$(find . -name "*.md") for file in $files; do claat export $file From 36bd46327d98da5a0eacbb267454facff7a3de71 Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 17:47:10 -0300 Subject: [PATCH 4/8] see actual branch --- .github/workflows/gh-deploy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index d0c5678b..903e07c7 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -71,6 +71,6 @@ jobs: done cd .. # See actual branch - git branch + echo "Running on branch $(git rev-parse --abbrev-ref HEAD)" # git add google-colab # git commit -m "Update google-colab paths" \ No newline at end of file From 478d389f28b05a9e7cc4ef12ef862ec13f895e76 Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 17:50:09 -0300 Subject: [PATCH 5/8] update --- .github/workflows/gh-deploy.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index 903e07c7..5be52ea8 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -70,6 +70,8 @@ jobs: claat export $file done cd .. + # Checkout on branch gh-pages-* depending on branch + git checkout ${{ steps.branch_check.outputs.env_name }} # See actual branch echo "Running on branch $(git rev-parse --abbrev-ref HEAD)" # git add google-colab From af5beec821db3716cfdb71afadc6ddb3ae6ce3cb Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 17:56:02 -0300 Subject: [PATCH 6/8] update to generate files html --- .github/workflows/gh-deploy.yml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index 5be52ea8..c9a9cab2 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -61,18 +61,25 @@ jobs: - name: Deploy Colabs from google-colab directory πŸš€ run: | + # Go to google-colab directory and install claat cd google-colab go install github.com/googlecodelabs/tools/claat@latest export GOPATH="$HOME/go" PATH="$GOPATH/bin:$PATH" + + # For each .md file, export it to html files=$(find . -name "*.md") for file in $files; do claat export $file done cd .. + # Checkout on branch gh-pages-* depending on branch git checkout ${{ steps.branch_check.outputs.env_name }} + # See actual branch echo "Running on branch $(git rev-parse --abbrev-ref HEAD)" - # git add google-colab - # git commit -m "Update google-colab paths" \ No newline at end of file + + # Git add folder google-colab excluding .md files + git add google-colab -f --all -- ':!*.md' + git commit -m "Update google-colab paths" \ No newline at end of file From fe7bc057800f819e5b38c0c6d2069e8c73c2f762 Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 18:02:53 -0300 Subject: [PATCH 7/8] update --- .github/workflows/gh-deploy.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index c9a9cab2..5017fa64 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -81,5 +81,8 @@ jobs: echo "Running on branch $(git rev-parse --abbrev-ref HEAD)" # Git add folder google-colab excluding .md files + git config --global user.name 'Codaqui Bot' + git config --global user.email 'contato@codaqui.dev' git add google-colab -f --all -- ':!*.md' - git commit -m "Update google-colab paths" \ No newline at end of file + git commit -m "Update google-colab paths" + git push \ No newline at end of file From 90f40d7d3bdac6480e2ede910b8fdc4db52f5bf1 Mon Sep 17 00:00:00 2001 From: Enderson Menezes Date: Tue, 23 Jan 2024 18:04:48 -0300 Subject: [PATCH 8/8] git push --set-upstream origin --- .github/workflows/gh-deploy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/gh-deploy.yml b/.github/workflows/gh-deploy.yml index 5017fa64..2af48ea7 100644 --- a/.github/workflows/gh-deploy.yml +++ b/.github/workflows/gh-deploy.yml @@ -85,4 +85,4 @@ jobs: git config --global user.email 'contato@codaqui.dev' git add google-colab -f --all -- ':!*.md' git commit -m "Update google-colab paths" - git push \ No newline at end of file + git push --set-upstream origin ${{ steps.branch_check.outputs.env_name }} \ No newline at end of file