Start here · Your first lesson

Your first lesson

This page is both a lesson and a live demonstration: every content idiom the platform styles for you appears below, doing its job. Read it once as a student, then once as an author — when you write your real first lesson, replace the words and keep the shapes.

☺ Explain it like I’m 10

A course page is like a LEGO kit: the platform gives you a small box of proven bricks — plain paragraphs, friendly “explain it simply” boxes, code you can copy with one click, and little diagrams with captions. You never invent new bricks; you tell your story by snapping the same ones together in a new order.

The anatomy of a page

Every page opens the same way: an eyebrow naming the group and topic, one h1, and a lead paragraph that makes the page’s promise. Right after the lead comes the ELI-10 callout — one everyday analogy for the whole page, like the LEGO kit above. From there it’s h2 sections of body copy. Headings get slugified ids automatically, and once a page has four or more h2s (like this one), an “On this page” table of contents appears on its own — no markup needed.

◆ Key idea

Pages ship content only. The sidebar, pager, footer, reading time, and progress bar are all built at load time by shared/js/site.js from manifest.js — so an author never copies chrome, only bricks like this callout.

Code blocks with a copy button

Wrap code in <div class="code" data-lang="…"><pre><code> and the platform adds the language label and a one-click copy button. Here is the exact brick you’ll use most — the manifest row that registers a new page:

// manifest.js — one row per page, in reading order.
// ORDER IS MEANING: the topics array is the sidebar and the prev/next pager.
{ slug: "lesson-02", title: "Your second lesson", group: "Start here", num: "0.3", tags: [] }

The slug must match the filename (lesson-02.html) and the page’s <body data-page="lesson-02"> — that triple is how the chrome knows which sidebar entry to mark as the current page.

Schematics that explain themselves

For diagrams, use an inline SVG inside <div class="schematic" data-cap="…"> — the data-cap text becomes a visible caption, and the SVG needs a role="img" with an aria-label so the picture reads aloud too. This one shows the machinery you just learned:

lesson-01.html just the content manifest.js window.COURSE — the map shared/js/site.js builds the chrome sidebar prev / next pager on-page TOC footer + meta

Keep schematics honest: draw the actual mechanism, label the arrows’ direction of flow, and let the caption state the takeaway in one sentence.

Wire it into the course

A new page joins the course in three moves: copy templates/page.html in beside this file, fill in its placeholders (title, description, data-page, eyebrow, lead), and add its topics row to manifest.js. Then run node scripts/build.js from the repo root — it verifies every topics row has a file and every file has a row, so a typo shows up as a red build instead of a silently missing sidebar entry.

✓ Checkpoint

1. Which single file decides the sidebar and pager order? 2. What three things must agree for a page to be recognized as “current”? 3. Where does a diagram’s caption text live? 4. What command proves the course is still consistent after an edit?

Check your answers
  1. manifest.js — the order of its topics array.
  2. The filename (lesson-02.html), the manifest row’s slug, and the page’s <body data-page="…">.
  3. In the wrapper’s data-cap attribute on <div class="schematic">.
  4. node scripts/build.js from the repo root.