Repository files navigation

Codelabs are interactive instructional tutorials, which can be authored in Google Docsusing some simple formatting conventions. You can also author codelabs using markdown syntax.This repo contains all the tools and documentation you’ll need for building and publishingyour own codelabs.

If you're interested in authoring codelabs, create a doc following theCodelab Formatting Guide.and see theclaat directory for a detailed description of theclaat command line tool.

Also, consider joining thecodelab-authors Google Group,which connects you with other authors and provides updates on new releases.

For the past 3+ years, the CLaaT (Codelabs as a Thing) project has given developers around theworld a hands-on experience with Google products and tools. We’ve accumulated over 500 high qualitycodelabs, served millions of web visitors, and supported over 100 events, from local meetupsall the way up to Google I/O.

This project has been implemented as a volunteer project by a small group of dedicated Googlerswho care deeply about this kind of “learning by doing” approach to education.

• Powerful and flexible authoring flow via Google Docs
• Optional support for authoring in Markdown text
• Ability to produce interactive web or markdown tutorials without writing any code
• Easy interactive previewing
• Usage monitoring via Google Analytics
• Support for multiple target environments (kiosk, web, markdown, offline, etc.)
• Support for anonymous use - ideal for public computers at developer events
• Looks great, with a responsive web implementation
• Remembers where the student left off when returning to a codelab
• Mobile friendly user experience

Yes, the claat tool and the serving mechanism can be used by anyone to author theirown codelabs and to serve up their own codelabs on the web.

You can also use this tool to create a nice looking summary page like the one you see on the officialGoogle Codelabs site.

If you're interested in authoring codelabs, joincodelab-authors group,which connects you with other authors and provides access to theCodelab Formatting Guide.

Check out thisexcellent tutorial.

1. Create a doc following the syntax conventions described in theCodelab Formatting Guide. Here’s anexample doc. Feel free to copy that doc as a starter template. Once you have your own source doc, note its DocId, which is the long string near the end of the URL (right after docs.google.com/document/d/).

2. Make one or more changes and preview your codelab, using the preview app provided by Google. To preview a codelab, install thePreview Codelab Chrome extension in your browser. Now you can preview a codelab directly from the Google Doc view by clicking the Chrome extension’s button, which will open a new tab to display the preview. Alternatively, navigate manually tohttps://codelabs-preview.appspot.com/?file_id=

3. Install the claat command -- see theREADME in the claat directory of this repo for instructions..

4. Run the claat command to transform the doc contents into one of the supported output formats. The default supported formats are html and markdown but the claat tool supports adding additional formats by specifying a path to a Go template. For example, using the example document above:

    $ claat export 1rpHleSSeY-MJZ8JvncvYA8CFqlnlcrW8-a4uEaqizPY   ok      your-first-pwapp

   You can also specify a markdown document (.md file) as input. It has to adhere to the syntax conventions describedhere

    $ claat export document.md ok      your-md-based-codelab

5. Run the claat serve command.

    $ claat serve

This will start a local web server and open a browser tab to the local server. Click on thehyperlink represent your codelab of interest to experience a fully rendered version.

See instructions in thesite directory's readme.

Copy thesample view, customize it to your liking,tag and rebuild the codelabs you want included, and then generate your view.

The output generated byclaat is a purely static set of HTML or Markdown code. As such,it can be served by any web serving mechanism, including any of the following options:

• Github Pages (*.github.io)
• Google App Engine
• Firebase Static Serving
• Google Cloud Storage
• Amazon Web Services S3
• Netlify
• Any open source web server (Nginx, Apache)
• python -m SimpleHTTPServer (Python 2)
• python3 -m http.server (Python 3)

Simply commit the artifacts generated by the claat command into your preferred serving vehicleand you should be ready to go.

Thesite directory contains tools for building your own custom landing page(s) and publishing both landingpages and codelabs to Google Cloud Storage.

Some people like the Google Docs authoring flow, others prefer to specify their codelabsdirectly in Markdown. Using the Docs approach, one source format can be used to generatenumerous output formats. Also, you can use a doc for the initial formulation stage, whereWYSIWYG and easy collaboration are extremely useful. Once the content stabilizes, typicallyafter the first launch, you are free to make the generated markdown your source of truthand discard the Google Doc as a controlling source. This is desirable because it gives youthe ability to manage the content as code in a source control system, but it comes at thecost of having to commit to one specific output format, or having to maintain multiplesources of truth.

This tool and corresponding authoring approach are agnostic with respect to whether (and when)you choose to manage your source as a Google Doc or as Markdown text checked into a repo.The only hard and fast rule is that, at any one point in time, you should choose one or theother. Trying to simultaneously maintain a doc and a corresponding repository is a recipefor disaster.

• Google Docs (following FORMAT-GUIDE.md formatting conventions)
• Markdown

• Google Codelabs - HTML and Markdown
• Qwiklabs - Markdown
• Cloud Shell Tutorials - Markdown with special directives
• Jupyter, Kaggle Kernels, Colaboratory, et. al. - Markdown with format specific cells

There’s no one “best” publication format. Each format has its own advantages,disadvantages, community, and application domain. For example, Jupyter has a very strongfollowing in the data science and Python communities.

This variety of formats is healthy because we’re seeing new innovative approaches all thetime (for example, see observablehq.com, which recently launched their Beta release).

While this evolving format ecosystem is generally a good thing, having to maintain tutorials inmultiple formats, or switch from one format to another can be painful. The Codelabs doc format(as specified in FORMAT-GUIDE.md) can provide a high level specification for maintaininga single source of truth, programmatically translated into one or more tutorial specific formats.

Yes, by all means. Have feature ideas? Send us a pull request or file a bug.

For several years, Googlers would rush to build new tutorials and related assets for ourannual developer event, Google I/O. But every year the authoring platform and distributionmechanism changed. As a result, there was little reuse of content and serving infrastructure,And every year we essentially kept reinventing the same wheel.

For Google I/O 2014, Shawn Simister wrote a Python program which retrievedspecially formatted documents from Google Drive, parsed them, and generateda nice interactive web-based user experience. This allowed authors to design theircodelabs using Google Docs, with its great interactivity and collaboration features,and automatically convert those documents into beautiful web based tutorials,without needing to write a single line of code.

Later, Ewa Gasperowicz wrote a site generator, supporting the ability topublish custom landing pages, with associated branding and an inventory of codelabsspecially curated for a given event.

Alex Vaghin later rewrote Shawn's Python program as a statically linked Go program (the claat command in this repo), eliminating many runtime dependencies, improving translationperformance. Alex also added, among many other enhancements, a proper abstract syntaxtree (to facilitate translation to different output formats), an app engine based previewer, an extensible rendering engine, support for generating markdown output. Alex also wrote the web serving infrastructure, the build tooling (based on gulp), and, with the author, the ability to self-publish codelabs directly from the preview app.

Clare Bayley has been the guru of onsite codelab experiences, running events large and small, while Sam Thorogood and Chris Broadfoot made major contributions to the onsite kiosks you may have seen at Google I/O.

Eric Bidelman redesigned the codelab user interface using Polymer components and built the g.co/codelabs landing page, to provide a beautiful user experience that looks great and works equally well on desktop and mobile devices.

Lots of other contributions have been made over the years and I’m sure that I’m neglecting some important advances but for the sake of brevity, I’ll leave it at that.

Google Codelabs exists thanks to the talents and efforts of many fine volunteers, including:Alex Vaghin, Marc Cohen, Shawn Simister, Ewa Gasperowicz, Eric Bidelman, Robert Kubis, Clare Bayley, Cassie Recher, Chris Broadfoot, Sam Thorogood, Ryan Seys, and the many codelab authors, inside and outside of Google, who have generated a veritabletreasure trove of content.

This is not an official Google product.