Contributor Guide

If you want to develop with these slides, these instructions are for you.

Installation

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

With just 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
just --list

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

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

You may opt out of just described, but minimally will need to have:

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 top level dir:

if ! $(echo "type bun" | sh > /dev/null ); then
    echo "🥟 Installing https://bun.sh ..."
    curl -fsSL https://bun.sh/install | bash
fi
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 just here vs. manually running this!

Content Design

I focused on practical application of web3 concepts I cover, more than simply discussing.

Organization

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

content
├── <series>
├── index.md                  # Series overview with many materials associated with it
├── guide.md                  # Presentor/Host facing guide on running these materials
├── README.md -> index.md     # Soft link `ln -s index.md README.md` - for Github web reading
│  ├── <topic>               # Talk related, has slides
│  │  ├── img
│  │  │  ├── <media>          # png, gif, mp4, jpg, etc. used in *these slides/examples*
│  │  │  ├── ...
│  │  ├── page.md             # Typically a stub file for embedding `slides.md`
│  │  └── slides.md           # A `reveal-md` formatted document
│  ├── _materials             # Workshop, Exercise, or Activity related
│  │  ├── img
│  │  │  ├── <media>          # png, gif, mp4, jpg, etc. used in *these slides/examples*
│  │  │  ├── ...
│  │  ├── <material>.md       # Audience facing instructions on some material
.  .  .   ...
  • <series>/README.md - required soft link to index.md.
  • <series>/index.md - required book page, must be listed in SUMMARY.md.
  • <series>/guide.md - optional page not used in the book, must NOT be listed in SUMMARY.md.
  • <series>/<topic>/page.md - required book page, must be listed in SUMMARY.md.
  • <series>/<topic>/slides.md - optional slides, embedded into a page.md, must be embedded into page.mdif slides are used.
  • <series>/<topic>/img - optional directory with media used in slides or pages in this topic.
  • <series>/<topic>/_materials - optional directory with inclusions referenced in slides or pages

Development Workflow

Typically, most work for topics 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 talk materials used to present in class, and those slides must contain Notes: sections with detailed audience 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 audiences 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
just 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:

just 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` ...

just 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!

Topic Template

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

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

The page.md 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 SUMMARY.md, 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:

[build]
- create-missing = false # do not create missing pages
+ create-missing = true # create missing pages

Tips on the Embedded Slides

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

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

# SOME TITLE HERE

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

<center>
<iframe style="width: 90%; aspect-ratio: 1400/900; margin: 0 0;" src="slides.html"></iframe>
<br />
<a target="_blank" href="../../contribute/how-to/page.md#-how-to-use-revealjs-slides"><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 />
</center>
{ {#include slides.md} } <!-- 👈 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 'page.md' -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.
just install-dev

Formatting

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 just to run this:

# This will format all files SUPER FAST after the first run is cached
just 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 -->
```html
<nuke-cols>
  <nuke-col>
    
    ### What's up, yo?

</nuke-col>
<nuke-col>
  
  - Yo
- Yo
- Yo

</nuke-col>
</nuke-cols>
```

<!-- 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
just l

# Link check a single file:
just links-for <relative-link-to/the-top-working-dir/file.md>

# Link check a directory, recursively
just links-for <./content/some-dir/inner-dir>

The checker configuration is set ine Makefile.rs 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 https://web.archive.org/ 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
  3. justfile

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
just img

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

CI

  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 `` tooling suggested in development workflows at this time, but some require the bun tooling to properly build and test things.