Contributor Guide

Thank you for interest in contributing to the Academy! ✨.

Before anything else, please read our Code of Conduct to understand our community's guidelines.

This guide is to help Academy contributors understand how all materials contained this repository are structured, how to interact with and modify them. Multiple tools are provided for contributors to make slideshows, leader-guided workshops, and self-directed activities.


The Academy is Rust heavy and as such, you need to install rust before anything else here.

In order to make your life easy 😉, there is a set of tasks that use cargo make.

With cargo make installed, you can list all tasks included to facilitate further installation, building, serving, formatting, and more with:

# Run from the top-level working dir of this repo
makers --list-all-steps

The tasks should be self-explanatory, if they are not - please file an issue to help us make them better.

# Install all dependencies
makers i
(Not advised) Manual Install

You may opt out of cargo make described, but minimally will need to hav:

Book - mdBook

Serve the book offline with:

# Run from the working dir of this repo
mdbook serve --open

Slides and Tooling - bun

Use bun to install and run the javascript and node tooling. With bun installed, from the academy top level dir:

if ! $(echo "type bun" | sh > /dev/null ); then
    echo "🥟 Installing ..."
    curl -fsSL | bash
echo "💽 Bun installed."

echo "🥟 Install slides tooling with Bun..."
bun install
echo "✅ Slides instalation complete!"

This should open a new browser tab with a simple listing of all slide decks to choose from.

Embedded Slides

At this time, there is a "hack" to get the slides embedded in the book, where the static HTML assets from a slides build are coppiced into the book so that they function in an iframe. See the Makefile.toml for [tasks.serve] to see the commands required to manually get this working. Again, it's much more convenient to use cargo make here vs. manually running this!

Content Design

The academy is focused on practical application of web3 concepts we cover, more than simply understanding.


The entirety of the book, including assets (images, code, etc.) needed in this book lives in ./content/*. The directory structure is as follows:

├── <module>
├──                  # Student facing module overview
├──          # Faculty facing guide on running this module
├── ->     # Soft link `ln -s` - for Github web reading
│  ├── <lesson>               # Lecture related, has slides
│  │  ├── img
│  │  │  ├── <media>          # png, gif, mp4, jpg, etc. used in *this lesson*
│  │  │  ├── ...
│  │  ├──             # Typically a stub file for embedding ``
│  │  └──           # A `reveal-md` formatted document
│  ├── _materials             # Workshop, Exercise, or Activity related
│  │  ├── img
│  │  │  ├── <media>          # png, gif, mp4, jpg, etc. used in *this lesson*
│  │  │  ├── ...
│  │  ├── <material>.md       # Student facing instructions on some material
.  .  .   ...
  • <module>/ - required soft link to
  • <module>/ - required book page, must be listed in
  • <module>/ - required page not used in the book, must NOT be listed in
  • <module>/<lesson>/ - required book page, must be listed in
  • <module>/<lesson>/ - optional slides, embedded into a, must be embedded into page.mdif slides are used.
  • <module>/<lesson>/img - optional directory with media used in slides or pages in this lesson.
  • <module>/<lesson>/_materials - optional directory with inclusions referenced in slides or pages

Development Workflow

Typically, most work for lessons centers on the development of slides. The pages they are embedded into are primarily static stubs to host the slides within. Workshop and Activity pages are an exception, where they do not usually have slides associated, or need more information outside slides. Viewing the rendered markdown of slides is more important than when iterating on pages, in practice.

Working on Slides with reveal-md

Slides include primarily lecture materials used to present in class, and those slides must contain Notes: sections with detailed student facing information about what is covered on a slide, not only speaker-facing notes! Typically the slide notes should embed all the references, resources, and further considerations for students to have as a resource during and after class.

To view and edit slides (only) in watching mode (updates immediately on changes to any file changes in the content):

# WATCHING server for slides only
makers serve-slides
# Or simply:
bun s

See the Using this Book page for more details on reveal.js features and use.

If this is your first time using reveal.js, we encourage you to explore the official demo to see what sort of things you can do with it! We are creating and customizing slides with reveal-md: a tool built with reveal.js to allow for Markdown only slides, with a few extra syntax items to make your slides look and feel awesome with as little effort as possible on style and visual design.

Copy & Paste Slides

The Copy and Paste Slide Templates page and source for the embedded slideshow demonstrate use and code snippets to accommodate many common slide archetypes. It should be possible to modify examples in your slides from these templates, including:

  • Multi-column slides
  • Embedded media
  • Diagrams (mermaid, and more)

Working on Pages with mdBook

Pages embed slides, and may include links to materials, references and other things when it's impractical to include it within speaker notes for slides. Most pages are just "stub" files to embed the slides into.

To work on both the embedded slides and the book in tandem in non-watching mode:

makers s # Build the slides (clobbering those tracked by the book repo in `./slides`), embed in the book, view the updated book.

# ... Make changes to the book and/or the slides ...
# ... kill the server with `ctrl+c` ...

makers s # Build the slides (clobbering those tracked by the book repo in `./slides`), embed in the book, view the updated book.

😭 At this time, this is a non-watching server, you must manually open the page and hard refresh pages served before to see them updated.

You must rerun this command to update on file changes!

Lesson Template

Head over to the Lesson Template page, and carefully read through the source before you continue. The entire directory is intended to be copied & pasted into the correct module to kickoff new lesson development:

# Copy this whole thing 👇😀
└── template
   ├── img
   │  └── REMOVE-ME-example-img.png

The file should _embed the slides.html page that isn't going to work until the build process creates it, but it will exist once that happens & render 😉.

File Size Considerations

We strive to not overload this book with excessively large assets, to that end we ask that all contributors before committing to this repo any assets:

  • Review image file size & compress minimal possible looking OK-ish full screen, or use smaller alternatives. Example:
    # Compress with imagemagick
    convert <INPUT_FILE> -quality 20% <OUTPUT_FILE>
  • Scale down all videos to minimal possible looking OK-ish full screen. Example:
    # What is the bitrate?
    ffmpeg -i <INPUT_FILE> 2> >(grep -i bitrate)
    # Reduce bitrate, iterate to find the *good enough* one for minimal size
    ffmpeg -i <INPUT_FILE> -b 400k <OUTPUT_FILE>

Refactoring Considerations

🚧 This workflow is not _normally_ needed by most contributors. Click to view anyway 🚧

We opt out of the handy helper to create missing files if linked in, as this indicates something is likely amis in our translation of slides -> stub pages mapping correctly.

This is useful to turn back on when radically updating the slides path structure and/or file names as changes must be manually applied otherwise to link to the correct new location in /slides/.../*-slides.html

You can opt in by editing book.toml:

- create-missing = false # do not create missing pages
+ create-missing = true # create missing pages

Tips on the Embedded Slides

All modules are of the structure described in the Content Organization section.

All files are the source of the associated slide content for that the files that embed them in the book itself. The files are typically just stubs, but do the option to add more details, instructions, etc. They typically are identical to:


<!-- markdown-link-check-disable -->

<iframe style="width: 90%; aspect-ratio: 1400/900; margin: 0 0; border: none;" src="slides.html"></iframe>
<br />
<a target="_blank" href="../../contribute/how-to/"><i class="fa fa-pencil-square"></i> How to use the slides</a> -
<a target="_blank" href="slides.html"><i class="fa fa-share-square"></i> Full screen (new tab)</a>
<br /><br />
<div ><i class="fa fa-chevron-circle-down"></i> Raw Slides Markdown</div>
<br />
{ {#include} } <!-- 👈 REMOVE the spaces in curly brackets ( {{include things}} ) when in use -- mdBook gives a build error without mangling the syntax here in the example 😜 -->
<a href="#top" style="position: fixed; right: 11%; bottom: 3%;"><i style="font-size: 1.3em;" class="fa fa-arrow-up"></i></a>

<!-- markdown-link-check-disable -->
  • find . -name '' -exec bash -c 'cat ../tmp >> "{}"' \; to apply the page stuff to embed slides

⏰ Critical Considerations

Conventions and Helpers

This book, and all content within have style and typographic conventions that, where practical, have tooling to help everyone conform to them.

# This will install the tooling needed for formatting, linting, checkers, etc.
makers install-dev


All Markdown, TOML, JSON, Typescript, and Javascript files in this repository are formatter with dprint. The setting for this formatter are found in .dprint.json. We use cargo make to run this:

# This will format all files SUPER FAST after the first run is cached
makers f

If (and only if) formatting breaks Markdown from rendering correctly, you may use <!-- prettier-ignore --> preceding a block in markdown to skip formatting like this:

<!-- prettier-ignore -->
    ### What's up, yo?

  - Yo
- Yo
- Yo


<!-- prettier-ignore-start -->

Some    text

* other    text
*           testing

<!-- prettier-ignore-end -->

See the docs on Markdown for dprint for more.

To ensure all *.md and .html files contain no broken links within them, we use a the mlc link checker. Run with:

# Link check all content files
makers l

# Link check a single file:
makers links-for <relative-link-to/the-top-working-dir/>
# Link check a directory, recursively
makers links-for <./content/some-dir/inner-dir>

The checker configuration is set ine task to see settings. The .mlc.toml config file is used to globally ignore specific common URLs that throw errors, in error 😛... at least it should, but is not working at this time. Notice that ignored links must be check from time to time manually! Thus don't use this unless explicitly needed, rather use a know good URL if at all possible, perhaps from the The same tool is also run by our CI on all files for all pushes to all branches. See the .github/workflows/link-check.yml file in this repo for details.

You can ignore the link check for a regex compliant entry in:

  1. .mlc.toml
  2. .github/workflows/check.yml

Eventually just .mlc.toml will do.

Checking Images

In order to ensure that there are no issues with images in this book, we check for:

  1. Broken links to images that will not be found in the build.
  2. Orphaned image files - not linked to at all from the book.
# Link check all `<img ...>` tags
makers img

Please delete any assets you do not need, we can always git recover at a latter time to bring them back in 💽.


  1. .github/workflows/pages.yml - On any merge with main, the CI is tasked with building the book and deploying a hosted version of it.
  2. .github/workflows/check.yml - On any merge with main, the CI is tasked with checking book for any issues with format, links, and images.

See .github/workflows/ in this repository for more details. Other tasks mostly stand alone from the cargo make tooling suggested in development workflows at this time, but some require the bun tooling to properly build and test things.