GitHub pages에 Google Codelab 만들기 How to make a Google codelab in Github pages

Google Codelab 은 절차적인 설명을 가독성 높게 제공하는 매우 유용한 도구입니다. 남은 시간 표시, 남은 스텝 표기, 보던 페이지 그대로 반영 등등 기본적으로 제공하는 기능들이 많고, markdown 을 활용하기 때문에 가이드 문서를 만드는 것이 매우 편리한 도구입니다.

이 문서의 내용 자체도 Google Codelab 으로 구성되어 있으며, 해당 Codelab 페이지에서 확인 가능합니다.

This article has same contents for the codelab, you can check the codelab in this page.

Introduction

This codelab page describe the process that making codelab page in Github pages.

GitHub Pages is a feature offered by GitHub that allows you to host static websites directly from a GitHub repository. It’s commonly used to publish personal projects, portfolios, documentation, or even blogs.

Google Codelab is an online platform provided by Google that offers step-by-step, interactive tutorials designed to teach developers how to use Google technologies and tools effectively. These tutorials cover a wide range of topics, including web development, Android app development, machine learning, cloud computing, and more.

Why Use Google Codelabs?

• Beginner-Friendly: They simplify complex technologies into easy-to-follow steps.
• Hands-On Learning: Practical examples help you understand real-world applications of the technology.
• Frequent Updates: Google keeps adding and updating content to reflect the latest tools and features.
• Global Accessibility: Tutorials are accessible online to developers worldwide.

Pre-requisites

In local machine, brew should be installed.

To install Homebrew on macOS, follow these steps:

Step 1: Open Terminal

1. Press Command(⌘) + Space to open Spotlight Search.
2. Type Terminal and press Enter.

Step 2: Install Xcode Command Line Tools

Before installing Homebrew, ensure that the Xcode Command Line Tools are installed:

1. Run the following command:

   xcode-select --install
   

2. A dialog box will appear. Click Install to proceed.
3. Wait for the installation to complete.

Step 3: Install Homebrew

1. Run the following command in Terminal:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. The script will prompt you to confirm the installation and provide your admin password. Enter it when prompted.

Step 4: Add Homebrew to Your PATH (if not automatically added)

Depending on your shell, you may need to update your PATH:

1. For zsh (default in macOS Catalina and later):

   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
   eval "$(/opt/homebrew/bin/brew shellenv)"
   

2. For bash:

   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile
   eval "$(/opt/homebrew/bin/brew shellenv)"
   

Step 5: Verify Installation

1. Run the following command to check if Homebrew is installed correctly:

   brew --version
   

   This will display the installed version of Homebrew.

Step 6: Update Homebrew

To ensure everything is up to date, run:

brew update

You’re now ready to use Homebrew! 🎉

Step 1: Install go and claat

googlecodelab will be deployed and served by(using) claat, and claat can be installed by go lang. So, first of all, install go using brew and then, install claat using go.

Install go:

brew install go

When brew install go lang, it add the go binary to the PATH, but if it does not add binary to the PATH, add it manually.

Add go binary to PATH:

echo 'export PATH=$PATH:~/go/bin' >> ~/.zshrc

Refresh .zshrc file to activate PATH:

source ~/.zshrc

Then, install claat:

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

To check claat installed successfully:

claat --help

Step 2: create a markdown .md file

Duration: 0:05:00

Make a markdown file(sample.md) like:

summary: Title of the Codelab
id: codelab-id
categories: Web, Beginner
status: Published

# Title of the Codelab

## Introduction
Brief introduction of the blog/tutorial.

## Step 1: Do Something
Instructions for step 1.

## Step 2: Do Something Else
Instructions for step 2.

Because this md path can be a web root path, so make the .md file in git repository root path.

Step 3: export the contents and check in local

Export the markdown file by claat

In the same directory with markdown file:

claat export sample.md

claat create a codelab-id directory in the same path. (id based directory.)

When using images in markdown file, those are included in img folder in exported directory.

the codelab-id will be a folder that can represent as a web path /codelab-id. So, if you want to change the web path, you should change the id value in .md file.

Check in local

After export the file, codelab can be check in local:

claat serve

When run this command, the default browser is open. If you type this command in same directory for .md file, you can see as below:

You can check the codelab with clicking the codelab-id path.

Step 4: push to github pages

Copy the codelab-id directory to the github repo’s docs folder.

Then, in the settings in the repository, enable pages as below:

For this codelab, the directory structure is:

Step 5: Check in the browser

Finally, we can check the codelab in:

https://<username>.github.io/<repo>/codelab-id/

Tips and Tricks: Syntax

If you’re using Windows make sure to set your text editor to use UNIX line endings!

Open your markdown file

$ vim <name-of-codelab>.md

Header metadata [Auto generated]

Update the headers metadata in your markdown file and change the values appropriately. Guidelines are available below the sample headers.

author: Author Name
summary: Summary of your codelab that is human readable
id: unique-codelab-identifier
tags: workshop,iguide
categories: Java,Spring
environments: Web
status: Published
feedback link: A link where users can go to provide feedback (e.g. the git repo or issue page)

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:

• Author: Author name or git username
• 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. This will be in the URL of the codelab
• Tags: Leave “workshop” if creating a Developer workshop or “iguide” if creating an integration guide. Remove both if neither. Note: this is used for the “Filter by Type” feature on the landing page
• Categories: A comma-separated list of the topics or technologies the codelab covers. Include items such as language(s) and protocol(s) used. The first one is used to create a new “Filter by category” feature on the landing page and the styling of the category. The remaining will be used for the filtering.
  • Note that the list of available categories can be found in the main site repo
  • The current list is (case insensitive): [amqp, boomi, codelab, java, jms, kafka, mqtt, rest, solace, spring, kubernetes, javascript, helm, azure, opentelemetry, mulesoft, rabbitmq, keda, apama, hermesjms, flink, nifi, nagios, jboss, weblogic, websphere, webspherelib, spark, sap, terraform]
• Environments: Leave as “Web”
• 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. Link to git repo where code for the tutorial will live.

Add the Title

Next add your title using a single ‘#’ character

# Title of codelab

Add Sections & Durations

Then for each section use Header 2 or ‘##’ & specify q duration beneath for time remaining calculations

Duration is in the following time format: hh:mm:ss

Example

## Section 1
Duration: 0:10:00

## Section 2
Duration: 0:05:00

Add Section Content

Now that we have 2 sections to our titled codelab let’s go ahead and add some content to each section. Make up your own or copy & paste the example below:

Copy into section 1 (Below Duration and above Section 2):

### Info Boxes
Plain Text followed by green & yellow info boxes

> aside negative
> This will appear in a yellow info box.
> This is line two of the negative block
> ```
> this is a code block
> with multiple lines
> ```

> aside positive
> This will appear in a green info box.

You created info boxes!

### Bullets
Plain Text followed by bullets
* Hello
* Codelab
* World

You created bullets!

### Numbered List
1. List
1. Using
1. Numbers

You created a numbered list!

Copy into section 2 (Below Duration):

### Add a Link
Add a link!
[Example of a Link](https://www.google.com)

### Add an Image
Add an image!
![image_caption](https://solace.com/wp-content/uploads/2019/09/goodbye_otter_v3.gif)

### Embed an iframe
![https://codepen.io/tzoght/embed/yRNZaP](https://en.wikipedia.org/wiki/File:Example.jpg "Try Me Publisher")

More Markdown Parser examples can be found here.

참고자료 및 출처

• https://codelabs.solace.dev/codelabs/codelab-4-codelab/?index=..%2F..index#0