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.

Installation

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

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

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

Content Design

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

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
├── <module>
├── index.md                  # Student facing module overview
├── faculty-guide.md          # Faculty facing guide on running this module
├── README.md -> index.md     # Soft link `ln -s index.md README.md` - for Github web reading
│  ├── <lesson>               # Lecture related, has slides
│  │  ├── img
│  │  │  ├── <media>          # png, gif, mp4, jpg, etc. used in *this lesson*
│  │  │  ├── ...
│  │  ├── 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 *this lesson*
│  │  │  ├── ...
│  │  ├── <material>.md       # Student facing instructions on some material
.  .  .   ...

• <module>/README.md - required soft link to index.md.
• <module>/index.md - required book page, must be listed in SUMMARY.md.
• <module>/faculty-guide.md - required page not used in the book, must NOT be listed in SUMMARY.md.
• <module>/<lesson>/page.md - required book page, must be listed in SUMMARY.md.
• <module>/<lesson>/slides.md - optional slides, embedded into a page.md, 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
   ├── 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

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

# SOME TITLE HERE

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

<center>
<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/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 -->

⏰ Critical Considerations

• Always use proper MarkDown links! <https://parity.io> is required, raw links will not be rendered in mdBook!
• Never use links that are likely ephemeral and will break. This example is in main, not some PR branch: https://github.com/paritytech/polkadot-sdk/blob/5174b9d/polkadot/roadmap/implementers-guide/src/node/backing/prospective-parachains.md You must be permalinks to a commit hash when using a github link, not main or other branch.
• Reuse images and have no duplication of any images, with close enough ones considered to replace where possible. Relative paths are supported: ../../<other lesson>/img/<existing img>

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

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 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 -->
```html
<pba-cols>
  <pba-col>
    
    ### What's up, yo?

</pba-col>
<pba-col>
  
  - Yo
- Yo
- Yo

</pba-col>
</pba-cols>
```

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

Some    text

* other    text
*           testing

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

See the docs on Markdown for dprint for more.

Checking Links

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/file.md>
# Link check a directory, recursively
makers 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://archive.org/web/ 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. Makefile.rs

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 💽.

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