summary: Sample Blockly Codelab id: sample-blockly-codelab categories: Blockly tags: status: Published authors: The Blockly Team Feedback Link: https://github.com/google/blockly-samples/issues/new
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. When creating a Codelab you have two authoring options:
In this codelab we are going to use the second option and author our codelab using a markdown file. 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:
In order to create a CodeLab you need Go and claat (the codelabs command line tool) installed.
The instructions below are what worked for me on Mac, but you can also find instructions here
Install Go if you don’t have it. You can use Homebrew if you have it on mac
$ brew install go
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
$ go get -u -v -x github.com/googlecodelabs/tools/claat
You should now have the claat command available to you.
Now that we have the environment setup let’s go ahead and create a markdown file where we’ll create the actual codelab.
$ vim codelab.md
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 categories: codelab,markdown environments: Web status: Published feedback link: A link where users can go to provide feedback (Maybe the git repo) analytics account: Google Analytics ID
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:
Next add your title using a single ‘#’ character
# Title of codelab
Then for each section use Header 2 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 I’ve found that the time is formatted hh:mm:ss
## Section 1 Duration: 0:10:00 ## Section 2 Duration: 0:05:00
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 and paste the example below:
Copy into section 1 (Below Duration and above Section 2):
### Info Boxes Plain Text followed by green and 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 Adding a link! [Example of a Link](https://www.google.com) ### Add an Image Adding an image! ![image_caption](https://googlecloud.tips/img/031/codelabs.png) ### 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.
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 and serve the content locally using the
claat command that we installed earlier.
$ claat export codelab.md $ claat serve
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.
Now that you have the static content you can host it however you want. One option is pushing it to github and serving it up from Netlify.
If you’d like to create your own landing page for codelabs, like this one, there is a tool to do that as well! Check it out here: CodeLabs Site