Writing a chapter

In this chapter, we will learn every building block a chapter can use. Each one is shown twice: first as the reader sees it, then as the HTML you write. There are twelve blocks. A good chapter needs about eight of them.

The first line

Every chapter file begins with one comment that holds its title and summary. The engine adds the heading, the chapter number, the reading time and the links to the next chapter. You never write an h1.

<!--meta {"title": "Writing a chapter", "part": "The guide", "minutes": 9,
"summary": "One line that sells the chapter."} -->

Text

The opening

In this chapter, we will learn one thing, and here is why it matters to you.

<p class="lede">In this chapter, we will learn ...</p>

A definition

A definition is one bold sentence that a reader could repeat to a friend. The explanation follows in ordinary sentences.

<h2>Section title</h2>
<p><strong>A definition is one bold sentence.</strong> The explanation follows.</p>

Notes

<aside class="note analogy"><h4>The analogy: title</h4><p>...</p></aside>
<aside class="note tip"> ...   <aside class="note warn"> ...   <aside class="note lab"> ...

Blocks of fixed text

Maya:       Suggest a snack for my kids' school trip.
Assistant:  Try cheese sticks and fruit slices.

sessions per year     2 x 365     =   730
tokens per year       730 x 1,500 = 1,095,000

question  -->  search  -->  top 3  -->  answer

prompt tokens: 74

total = sum(prices)   # code gets a copy button

<pre class="chat">     a conversation
<pre class="calc">     arithmetic, one step per line
<pre class="diagram">  boxes and arrows drawn with characters
<pre class="out">      what a real program printed
<pre><code class="language-python">   code (also bash, json, sql)

Tables

<div class="table-wrap"><table>
<thead><tr><th>Design</th><th>...</th></tr></thead>
<tbody><tr><td>Overwrite</td><td>...</td></tr></tbody>
</table></div>

The wrapper lets a wide table scroll sideways on a phone while the page itself stays still.

An interactive

One line places an interactive in the text. The name must match a widget in one of the book's scripts. Introduce it with a sentence that says what to move and what to watch.

<p>Move the years to 30 and watch the gap between the two lines.</p>
<div class="widget" data-widget="savings-curve"></div>

Move the years to 30 and watch the gap between the two lines.

The four closing sections

Every chapter ends the same way: try, questions, carry, check. They are the sections below this paragraph. Look at them on screen, then at their source.

<section class="try"><h2>Try it yourself</h2> ... </section>

<section class="faq"><h2>Common questions</h2>
  <details><summary>The question?</summary><p>The answer.</p></details>
</section>

<section class="carry"><h2>Carry this</h2><ul><li>...</li></ul></section>

<section class="check"><h2>Check yourself</h2>
  <div class="q"><p><strong>1.</strong> Question</p>
  <details><summary>Answer</summary><p>...</p></details></div>
</section>

Links

Link to another chapter of the same book by its file name. The engine adds the book's address in front.

<a href="/make/03-making-an-interactive/">Chapter 3</a>

Try it yourself

Open books/make/chapters/02-writing-a-chapter.html in your editor, next to this page. Change the text of one note, run python3 engine/build.py and reload.

Common questions

Can I use my own CSS classes?

You can, but then your book stops looking like the others, and dark mode and phones become your job. Try to say it with the twelve bricks first.

How long should a chapter be?

Between 1,400 and 2,400 words, which is 8 to 12 minutes. A chapter that needs more is usually two ideas. Split it.

Can I add images?

Yes. Put the file in your book's assets folder and use an ordinary img tag with the address /your-book/assets/picture.svg. Always write the alt text.

Carry this

• First line: the meta comment. No h1.
• Twelve bricks: lede, definition, four notes, five fixed blocks, table, widget.
• Every chapter ends with try, questions, carry, check.

Check yourself

1. Your calculation block shows a blank where a < b should be. Why?

Answer

The browser read < b as the start of a tag. Write a < b.