Last Updated: 2019-07-24
This codelab serves a guide on how to contribute your own IoTeX product related codelab.
What is codelab?
Codelabs are hands-on interactive coding tutorials developed by Google. Claat (Codelabs As A Thing), the tool used to build them, is open-sourced, and as such, anyone can create their own codelab and contribute to the community!
What you'll learn
- How to install Google Codelab tools
- How to format a code lab
- How to export codelabs
- How to apply iotex theme
What you'll need
- Computer
- Google account (preferred)
Install claat
Follow the instructions provided by Google here.
If you are on mac, the easiest installation is through golang:
$ brew install go $ go get -u -v -x github.com/googlecodelabs/tools/claat
Setup environment variables:
$ export GOPATH=$HOME/Go $ export GOROOT=/usr/local/opt/go/libexec $ export PATH=$PATH:$GOPATH/bin $ export PATH=$PATH:$GOROOT/bin
Verify installation:
$ claat -h
Fork codelabs repository
Codelab contributions will be added through pull requests. Create a fork of the codelabs repository and add a branch of your choice. This guide about open-source contributions may be helpful.
Choice of format
There are two methods of formatting codelabs:
Google Docs is recommended, as it offers easy methods of previewing your work, however both work as intended. Follow the syntax and formatting conventions outlined by their respective format documents.
Codelab Metadata
The codelab metadata consists of a summary, url, category, environment, status, feedback link, and analytics account.
You can set each of these fields to whatever you want, however for category, environment, and status, url, please adhere to the standards outlined below:
- Category: You can choose one of five categories: blockchain, smart-contract, iot, web, misc
- Environment: Please set environment to Web. Additionally, if your codelab is in a language other than English, such as Chinese, include this in your environment. Set environment to Web, chinese
- Status: Please set to Published
- Url: Please make sure your url is not already taken. Taken urls are shown in the codelabs folder of your forked branch. (For example, deploy-smart-contract and full-node-setup are taken)
For example (Google docs):
Previewing your codelab
WIth Google Docs, there are two ways of previewing your codelab:
- Install Chrome extension and click the extension's button while you're in your codelab
Google Doc tab
- Navigate manually to https://codelabs-preview.appspot.com/?file_id=[google-doc-id]. (Your
docid is the long string near the end of the URL, right after docs.google.com/document/d/)
Navigate to your fork's branch's codelabs directory:
$ cd codelabs
Next, use claat to build your Google Doc or Markdown file.
Google Doc:
$ claat export docid
Your docid is the long string near the end of the URL (right after docs.google.com/document/d/)
Markdown file:
$ claat export file-name.md
You should see a folder created titled the metadata url that you defined in the source file. Within that folder is the static html website and json file containing metadata generated by claat.
To preview your codelab, call claat serve:
$ claat serve
This will create a local server to host your static website.
The claat generated static html website uses Google's codelab theme, however in IoTeX Codelabs, we use a custom theme that adheres to IoTeX colors.
To change to the IoTeX theme colors, open the static html file in the code editor of your choice
You should see something like this:
View Example
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1.0, user-scalable=yes">
<meta name="theme-color" content="#4F7DC9">
<meta charset="UTF-8">
<title>Setting up a full node</title>
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Source+Code+Pro:400|Roboto:400,300,400italic,500,700|Roboto+Mono">
<link rel="stylesheet" href="//fonts.googleapis.com/icon?family=Material+Icons">
<link rel="stylesheet" href="https://storage.googleapis.com/codelab-elements/codelab-elements.css">
...Replace the Google stylesheet link with the IoTeX stylesheet link:
Original:
<link rel="stylesheet" href="https://storage.googleapis.com/codelab-elements/codelab-elements.css">New:
<link rel="stylesheet" href="../style/codelab-elements.css">Push your new files to your forked branch and create a pull request. We will review your pull request soon!
Thank you for contributing!