ferrix/slides/README.md

# Slides

A reveal.js deck structured like Matt Godbolt's newer talks
([what-happens-beneath-accu-2026](https://github.com/mattgodbolt/what-happens-beneath-accu-2026)):
no stock theme but a custom dark one, every slide on a rounded panel, IBM Plex
Sans and Mono, monokai code with glowing stepped lines, 16:9 with fade
transitions, and the content in one Markdown file per section.

What is ours: the palette, and the corner motif. His ring-and-thread became a
chain of nodes and links, an AS path.

## The talk

| Section | File |
|---|---|
| About the speaker | `sections/00-intro.md` |
| Internet numbering resources: addresses, prefixes, registries, AS numbers | `sections/01-resources.md` |
| BGP and the bytes of an UPDATE | `sections/03-bgp-update.md` |
| IP transit and Internet exchanges | `sections/04-transit-and-ix.md` |
| The lab: the lab speaker, pr01.rue and its exchanges | `sections/05-lab.md` |

The UPDATE in section 3 is `2a0d:d740::/48` as AS210036 announces it to the
SwissIX route servers: next hop `2001:7f8:24::c9` (pr01's port on the peering
LAN), MED 0 and the `210036:10:2` tag, which is what pr01's export filter puts
on routes to peers. It was produced with the lab daemon's own encoder and parsed back
to the same message, not captured off the wire; a capture from pr01 may differ
in detail (BIRD can append a link-local next hop). The byte slides step through
it one part at a time (press down), and every number on them was checked
against the bytes when the slides were generated. To change the example,
regenerate rather than edit the hex by hand.

The deck deliberately has no fragments or stepped code: a slide shows
everything at once. Two code blocks keep a static highlight on one line.

| File | Holds |
|---|---|
| `theme.css` | the look: palette, type, panels, motif, title slide |
| `style.css` | components used by slides: columns, boxes, bytes, notes |
| `index.html` | section list, reveal.js loader and options, `bird` highlighter |
| `sections/*.md` | the slides |

## Make it yours

Everything brand-like is a variable at the top of `theme.css`. To compare
accents without editing, open `?accent=green`, `?accent=amber` or
`?accent=magenta` (blue is the default); copy the one you like into `:root`.
The wordmark bottom-left is the `<div class="wordmark">` in `index.html`.
For a full-bleed title image, empty the title `<section>` and give it
`data-background="images/title.png"`.

## Show it

The sections are loaded over HTTP, so open the deck through a server, not by
double-clicking `index.html`. Opened from disk, browsers block reveal.js and
the section files, and you would see a title and empty panels; the page now
says so instead:

    python3 slides/serve.py 8000

(`python3 -m http.server` works too, but it lets the browser cache the
section files and the stylesheet, so edits may not show until a hard reload,
Cmd+Shift+R. `serve.py` is the same server with caching turned off.)

Then <http://localhost:8000>. Keys: arrows to move, `S` speaker view with
notes and a timer, `O` overview, `F` fullscreen, `B` blank the screen.

## Offline

    slides/vendor-reveal.sh

copies reveal.js into `slides/reveal.js/` (ignored by git). The deck uses that
copy when present and the CDN otherwise. Do this before presenting anywhere
with uncertain Wi-Fi. IBM Plex still comes from Google Fonts; without a
network the deck falls back to Helvetica/Arial and the system monospace, so
install IBM Plex on the presenting machine if that matters.

## Write slides

Edit the files in `sections/`; add a section by adding a file and a
`<section data-markdown=...>` line in `index.html`.

    -----        next slide
    ---          next vertical slide (detail you can skip)
    Notes:       speaker notes from here to the end of the slide

Apply a class to the element above with `<!-- .element: class="..." -->`.

| Class | Effect |
|---|---|
| `big` | one large statement on the slide |
| `note` | quiet italic aside |
| `attribution` | small credit under an image or quote |
| `borders` | table with visible borders |
| `r-stretch` | image or iframe fills the remaining height |
| `blur-edges` | soft edge for photos |

Blocks: `<div class="cols">` two columns, `<div class="boxes">` labelled cards
(`us`, `ok`, `bad`), `<pre class="bytes">` BGP bytes in the colours of the lab
page (add `focus`, and `on` to the spans to keep lit, to dim the rest),
`<table class="decode">` for the explanation under them,
`<svg class="diagram">` for diagrams drawn in the theme's colours (`hot`,
`fabric`, `link`, `bgp`, `traffic`). Code fences take a language and optional line steps, e.g.
` ```bird [1-3|5-9] `; `bird` is a small highlighter defined in `index.html`.

`<!-- .slide: class="bare" -->` drops the panel, the motif and the wordmark
for one slide, e.g. a full-bleed image. The title slide does so by itself.

## Publish as one file

    slides/vendor-reveal.sh      # once, if slides/reveal.js is missing
    python3 slides/build.py      # writes slides/dist/hands-on-bgp.html

`build.py` inlines everything the page would otherwise fetch: reveal.js and
its plugins, the stylesheets, the favicon, our scripts and the Markdown
sections. The one file (about 1.3 MB) can be uploaded anywhere and also
opens straight from disk. It still uses the network for two things: the IBM
Plex fonts from Google Fonts (without them the browser's fallback fonts are
used) and the live DNS and RIPE lookups in section 1. Speaker view (`S`)
works from the bundle too. `slides/dist/` is not committed; rebuild after
editing.

## PDF

Open <http://localhost:8000/?print-pdf> in Chrome and print to PDF with
background graphics on.