This repository holds Codelabs created by Google Developers Experts (GDE) in collaboration with contributors from the community. In case you are wondering what Codelabs are, take a look here. This repository is primarily maintained by Chansung Park (@deep-diver) and Sayak Paul (@sayakpaul) who both are Machine Learning GDEs.
This repository builds static web pages using Hugo, and the generated static web pages are hosted on GitHub Pages. The applied theme makes the appearance of the pages similar to google codelabs. This Hugo theme was originally ported by nekocode, and customized by Chansung Park.
- Install Hugo (instructions)
- Run
git submodule update --init exampleSite/themes/codelabs/
- Run
git submodule foreach git pull origin master
- Write a post under
exampleSite/content/posts
directory- You can follow the format guide. However, since this is not the actual Codelabs, you have to check locally if the features are supported
- Run
hugo server -D
inexampleSite
for local test- You don't have to kill and run this process whenever you add more contents. You can see the reflected changes if you refresh the browser
- Commit & Pull Request
- Skip the first step above since Hugo is preinstalled
- Run
hugo server -D --baseUrl=/ --appendPort=false
for local test instead
---
title: TITLE
date: YYYY-MM-DD
categories: [MAIN_CATEGORY, SUB_CATEGORY]
tags: [TAG1, TAG2, ...]
duration: MM:SS
authors: AUTHOR_NAME
---
The categories can have two values. The first is the main, and the second is the sub, and they will appear at the bottom of the card in the front page. Only the main category is used to filter by categories and colorize the bottom color of the card. Here is the list of currently supported categories:
- mlops (Machine Learning Operations)
- gcp (Google Cloud Platform)
- tfx (TensorFlow Extended)
If you want to add more categories, please leave proporsal issues, then we can add them in the theme repository.
Each step should be contained with {{< step >}}
template string like below. You can give title for each step with the label
attribute, and the estimated duration can be specified in duration
attribute as well.
{{< step label="Overview" duration="1:00" >}}
WRITE YOUR OWN CONTENT
{{< /step >}}
In the WRITE YOUR OWN CONTENT
, you can simply write anything in Markdown format. If you need to include images, you can put images in exampleSite/content/assets/images
directory, and don't forget to refer those images with the /
in the path (i.e. ![IMAGE](/assets/images/YOUR_CODELAB/IMAGE.png)
). You can check out the following source repositories of a few popular Codelabs for reference:
- https://github.com/googlecodelabs/automl-vision-edge-in-mlkit
- https://github.com/googlecodelabs/integrating-ml-apis
- https://github.com/flutter/codelabs/tree/master/firebase-get-to-know-flutter
In order to make codelabs as appealing as possible, here are few recommendation:
- Codelabs are meant to be primarily about code. So it's recommended to not consider theory-focused posts for Codelabs.
- Make the title more noticible within no more than 60 characters long.
- Always add environmental setup for readers to reproduce your experiments.
- Keep each steps as compact as possible:
- Don't try to explain every underlying technologies.
- Add links to other resources for keeping things compact and interesting to the readers.
- Write multi part codelabs:
- If you need more detailed explanation on certain topics, simply write more codelabs and leave links. In this way, readers can consume the whole concept/tutorials bite by bite.
There are many wonderful codelabs at Google Codelabs, so please take a look how they are written. Here are some of them: