Setup and Usage

1. Getting started¶

One-time Setup¶

1. Clone this repo
2. cd into newly cloned repo
3. pip install -r requirements.txt
4. Run ./update.sh ( ) or .\update.ps1 ()

Mkdocs Requirements¶

In mkdocs.yml, have the required properties:

theme:
  name: material
  custom_dir: codelab

markdown_extensions:
  - attr_list
  - pymdownx.superfences

Create a bare minimum docs/*.md codelab page:

---
codelab: true
---

# My Lab's Title

## This becomes Step 1

Hello world instructions for Task 1

## This becomes Step 2

Blah blah for Task 2

By default, the codelab considers the H2 heading as a new step. Content under a ## (Heading 2) until the next H2 is considered a step.

2. YAML frontmatter¶

Explicitly set a title, author, report link and date. The date can also be rendered with git revision date.

---
title: Example Workshop
author: "Anonymous Penguin"
revision_date: 2022-01-10
report_bugs: http://endless.horse/
codelab: true
---

## This becomes Step 1

Hello world

## This becomes Step 2

Blah blah

Hide tabs¶

If the tabs feature enabled, you can hide tabs on a particular page:

---
hide:
  - tabs
---

3. Theme Config¶

In mkdocs.yml theme:

theme:
  name: material # Mkdocs Material is the base theme
  custom_dir: codelab # folder to overrides, in this case 'codelab'
  report_bugs: to:an@email.com # url for the Bug Report button
  global: true # default false

Global¶

If the global option is enabled, then non-index pages will be turned into codelabs by default if no codelab property is specified.

Exclude a page by setting codelab to false in the page's frontmatter.

---
title: This page isn't a lab
codelab: false
---

Report Bugs¶

Set the default link for reporting bugs. It will be overridden by page-specific report_bugs property.

4. Plugin Config¶

Auto Number Headings¶

Headings will automatically be numbered, and wrong numbers will be corrected according to their logical order.

In mkdocs.yml:

plugins:
  - codelab:
      auto_number: true # Whether to auto-number sections

5. Set a custom delimiter¶

In mkdocs.yml plugins, the delimiter is a CSS selector.

plugins:
  - search
  - codelab:
      delimiter: '[step]'

Then in a markdown page, assign an attribute to a heading.

---
codelab: true
author: Anonymous Penguin
---

# My Lab's Title

## This becomes Step 1 { step }

Hello world

## This becomes Step 2 { step }

Blah blah

# This doesn't count

Using more than one H1 is not recommended, but the plugin can handle it.

## This doesn't count

Just in case

## Here is another step { step=3 }

This will be step 3

Additional examples:

plugins:
  - codelab:
      delimiter: '.my-class'

---
codelab: true
author: Anonymous Penguin
title: My Lab
---

## This becomes Step 1 { .my-class }

Hello world

### This becomes Step 2 { .my-class }

1. Text and list items won't count as a heading or a step.
  { .my-class }
2. Substep
3. Substep

plugins:
  - codelab:
      delimiter: 'h2.my-class'

---
codelab: true
author: Anonymous Penguin
title: My Lab
---

## This becomes Step 1 { .my-class }

Hello world

## This becomes Step 2 { .my-class }

Blah blah

### H3 won't be a step { .my-class }

Using more than one H1 is not recommended, but the plugin can handle it.

plugins:
  - codelab:
      delimiter: '[duration]'

---
codelab: true
author: Anonymous Penguin
title: My Lab
---

## This becomes Step 1 { duration=1:00 }

Hello world

## This becomes Step 2 { duration=5:00:00 }

Blah blah

# This becomes Step 3 { duration=6:00 }

Using more than one H1 is not recommended, but the plugin can handle it.

6. Duration calculated¶

Optional: set the duration attribute for steps to calculate the estimated time.

## Wash the dishes { duration="10:00" }

Etc...

You can set durations for list items and paragraphs, too.

## Wash the dishes

1. Grab a towel.
    { duration=1:00 }
2. Run it around the rim.
    {duration=1:00 }

Optional: Grab Barkeeper's Friend and some gloves for powerwashing tea stains.
{ duration=5:00 }

Note that all durations will be added together, so the step duration is not needed.

7. Finishing Touches¶

Printing¶

The theme is configured to have a print version. Press Ctrl+P to take a look.

References¶

• Google
• Google
• Google