Are you trying to create easy to use, visually appealing content for the tech community? This Codelab will show you how to quickly create your own Google Codelab just like the one you're using right now.

We'll be authoring the codelabs using markdown format. This gives us the flexibility of using our markdown file for other things and also storing it in our github repo with any code that might be used for a tutorial.

Here is an example image of another Codelab that I created: image_caption

Resources

Video

You can also watch a video on how you can contribute to authoring a codelab by visiting this YouTube link or watching the video below

In order to create a Codelab you need

You have two options to download the dependencies:

Option A: Download from source

Option B: Download from cli: MacOS/Linux setup

Install Go

$ brew install go

Setup Go Environment Variables

Below is what I set on mac, but instructions are here for other OS options

$ export GOPATH=$HOME/Go
$ export GOROOT=/usr/local/opt/go/libexec
$ export PATH=$PATH:$GOPATH/bin
$ export PATH=$PATH:$GOROOT/bin

Install claat

Option A: from CLI using go

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

Option B: pre-compiled binary

Navigate to the Google Codelabs release page and install it from there

Confirm claat installment

You should now have the claat command available to you.

$ claat

Note if you have Go v1.17+

As of Go v1.17+, the go get command for installing executables is deprecated https://go.dev/doc/go-get-install-deprecation

A workaround for isntalling the claat command is the follwing:

  1. Clone the google tools project repo into a google-tools directory git clone git@github.com:googlecodelabs/tools.git google-tools
  2. Navigate to the claat command directory cd google-tools/claat
  3. Build the claat command go build .. This will create a claat command executable that you can use.
  4. Now you can update your PATH env variable (this is either done in your .bashrc, .profile, or .zshrc depending on what your shell is). At the end of the file, isert the following lineexport PATH=$PATH:$HOME/google-tools/claat. Note: this assumes you clones the google-tools repo in your $HOME directory. If cloned elsewhere, make sure you use the right path in your path export
  5. After you do this, you can open up a new terminal window and executing claat from the command line should work

Content Guidance

✅ Each codelab should be focused on one topic or a very small group of related topics.
✅ Use sections to separate steps for ease of navigation
✅ Include an "Overview" or "What You'll Learn Section" at the beginning of a codelab
✅ Include an "Environment Setup" or "What You'll Need Section" section that sets up the environment, if necessary.
✅ Try to make the codelab fun and engaging using images and/or gifs
✅ Provide code used in a separate public git repo

Tips

💡 To capture a multi-part topic, create smaller sections of the topic and organize the section titles as parts and sub-sections to capture the grouping of content. image_caption

💡 Attempt to give complete context when specifying properties, configuration etc as much as possible. image_caption

Where to create your codelab

📌 Create your codelab in the Solace codelabs repo for version tracking
📌 All other code can be kept in a separate repo
📌 Example codelab markdown structure can be found on the Battleship markdown and the Battleship source code

Content Reviewer

Upon authoring of your codelab, we request you have two reviewers:

1️⃣ Technical reviewer who is knowledgeable with the content. Make sure they are tagged on github as a reviewer
 2️⃣ A member of the Developer Relations team to confirm the structure of your codelab and merge it into the main github repo

✨ Now that we have the environment setup, you have two options you can follow to create your first codelab: Automated or Manual

Start by

  1. Forking the solace-dev-codelabs repo from https://github.com/SolaceDev/solace-dev-codelabs
    image_caption
  2. Clone your fork. Note: replace with your github username and with the name of your codelabs. See note below if you do not have ssh setup
git clone git@github.com:<Your_Github_User>/solace-dev-codelabs.git
cd solace-dev-codelabs
git checkout -b add-codelab-<name_of_codelab>

Positive : If you do not have SSH setup on your machine and got an error cloning the repo, you can clone the https link instead as follows:

git clone https://github.com//solace-dev-codelabs.git

Negative : Do not forget to checkout the code into a new branch git checkout -b <add-codelab-name_of_codelab>. This would help facilitating a peer review and approve/reject changes without affecting the published content.

Then follow one of the two options in the next two steps: Automated or Manual

Prerequisites

Steps

  1. After cloning the repository as per the earlier step, from the root directory, run the init script as follows ./init.sh
  2. Navigate to the /markdown/ directory
  3. Install the required dependencies for watching any changes you make in your markdown file by running the following from terminal npm install
  4. Compile and start the claat server by running npm run watch. Note: This will open a tab in your browser and serve your markdown file
  5. Edit your .md file in your text editor of choice
  6. When ready, run the export script as follows ./export.sh

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

Positive : Exporting your codelab will create the html static files under the codelabs/ directory

🚀 Go ahead to the Step 8 and add your codelabs on the main repo

Create a folder under the markdown directory. This is where your markdown file and related artifacts (such as images) will reside.

Navigate to the directory.

Go ahead and create a markdown file where you'll create the actual codelab. Please have your markdown file name match the id in the header metadata that you will set in the next subsection.

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

$ vim unique-codelab-identifier.md

Fill-in the header metadata

Copy and paste the headers below into 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:

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 an optional duration beneath for time remaining calculations Optional section times will be used to automatically total & remaining tutorial times In markdown I've found that the time is formatted 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

Negative
: This will appear in a yellow info box.

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.

Export & Serve Locally

Now that you have an initial codelab defined in your markdown file let's go ahead and generate the static site content. We can export & serve the content locally using the claat command that we installed earlier.

$ claat export codelab.md
$ claat serve

Repeat the export and serve locally every ime you make a new change in the markdown file

Positive : When you ran the claat export command you created the static web content needed to host your codelab. It placed static web content in a directory specified by your unique "id" and you can view it locally by opening the index.html page.

Negative : Note that when you view it locally by opening index.html some of the graphics may not show up (such as access_time, Next, Back), but they work once online.

Export for production

When you're done, export your static web content to the codelabs folder.

Positive : Make sure your markdown file name matches your header metadata id for ease of future updates.

# If creating a new codelab
mkdir markdown/<header-metadata-id>
# Add your markdown content in the markdown/<header-metadata-id>/<file-name>.md directory
# Add your images in the markdown/<header-metadata-id>/img directory

cd markdown/<header-metadata-id>
# Export into static content
# Note the google analytics code used. Keep as is below
claat export -o ../../codelabs/ <header-metadata-id>.md

Positive : Exporting your codelab will create the html static files under the codelabs/ directory

🚀 Go ahead to Step 8 and add your codelabs on the main repo

Steps

  1. Navigate to the /markdown/ directory
  2. Compile and start the claat server by running npm run watch. Note: This will open a tab in your browser and serve your markdown file
  3. Edit your .md file in your text editor of choice
  4. When ready, run the export script as follows ./export.sh

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

Positive : Exporting your codelab will create the html static files under the codelabs/ directory

🚀 Go ahead to Step 8 and add your codelabs on the main repo

Stage your Codelab

Add your changes and any newly created files, then commit & push the changes. From your codelabs root directory, execute:

cd solace-dev-codelabs
git add .
git commit -m 'Added or Updated <header-metadata-id> codelab'
git push origin add-codelab-<id>

Create a Pull Request

Now that your changes have been pushed to a new branch, navigate to your fork https://github.com//solace-dev-codelabs and create a pull request against master.

Since your commit has already been pushed you should see a highlighted box near the top of the page; Choose the "Pull Request" button next to it and fill out the form with comments on what changes are being requested. Upon submitting the Pull Request the Codelabs team will be notified, perform a review and ensure the codelab goes live on the site.

Positive : We recommend a technical review of the codelab to verify the technical steps and make sure they work as mentioned in the codelab.

Thank You!

Thank you for contributing to Solace Codelabs! Please reach out to the Solace DevRel team with any questions.