Codelab Theme for Mkdocs

Jan 10 2022

I’ve been working on a side project: a Codelab theme based off of Mkdocs Material.

Mkdocs codelab page showing step 1 of the theme.

Features #

  • Generate an interactive tutorial from Markdown (Python-flavored)
  • Uses Mkdocs Material (v8.1.3) as a base. I think it should work on any 8.X version as long as the update script is used properly.
  • Printer-friendly
  • Right-to-left compatible

Why? #

I’ve been asked to do help consolidate a happy path for Learning & Development. For now, the potential project is mostly voiceovers and PowerPoints for internal onboarding. I have no idea if I’ll ever need something like a dedicated workshop and tutorial repository, but I like to be prepared.

I did this in my free time so I won’t have liability with my job, but I’m hoping to use it at work.

The static site generator Hugo has a few ripoff themes of an old version of Google’s codelabs, a collection of tutorials.

I wanted one for Mkdocs instead of Hugo, but I don’t know if anything exists, so I went ahead and replicated it.

I still have some styling issues to look out for, but it’s mostly complete.

Contest Idea #

I’m wondering if I could bring up the idea of a contest for encouraging training and mentorship.

  1. Submit an outline of a tutorial/codelab/workshop to the contest, before the due date. MS Word and Markdown templates will be provided for convenience.
  2. During a voting period, all entries will be shown in a public pool. Anyone from the company can upvote tutorials that they’d like to see.
  3. The top 80% upvoted will have priority and special polish. The writing team should work with the submitter to fill the outline of a tutorial and turn it into a finished lab.
  4. Prizes will go to 1st, 2nd and 3rd place. Prizes are kind of difficult to figure out. Maybe PTO or some gadget, or a subscription voucher, I don’t know. The 4-10th places get a free UberEats giftcard or something. Throw a party so everyone gets a participation prize 🍕
  5. The last 20% will be worked on later. It’s possible they contain niche ideas, or would be better suited in a different medium.