A book is a folder · Make an Interactive Book: In One Afternoon

In this chapter, we will learn what an interactive book on this shelf is made of. We will create a new book with one command and open it in a browser. You need a text editor and Python 3. You do not need a framework, a package manager or a database.

What is in the folder

A book is a folder with one settings file, a folder of chapters and a folder of interactives.

books/
  my-book/
    book.json                     the cover: title, subtitle, accent colour, which scripts to load
    chapters/
      01-the-first-idea.html      one chapter = one file; the number in the name is the order
      02-the-second-idea.html
    assets/
      widgets-my-book.js          your interactives (optional)
engine/                           the binder: you never edit it to write a book
  build.py                        folders in, static site out
  assets/book.css  book.js  widgets-core.js

Make your first book

One command creates a book with two starter chapters and one working interactive.

python3 engine/new_book.py gardening "Gardening: Seed to Harvest"
python3 engine/build.py --check
python3 -m http.server 8000 -d dist

Open http://localhost:8000. Your book is on the shelf. Edit a chapter, build again, reload the page.

The cover: book.json

book.json tells the engine how to present the book. Only title is required.

{
  "title": "Gardening: Seed to Harvest",
  "short": "Gardening",
  "eyebrow": "An interactive book",
  "subtitle": "One sentence that tells a stranger why to read this.",
  "order": 5,
  "hue": 130,
  "scripts": ["widgets-gardening.js"],
  "links": [{"label": "Planting calendar", "chapter": "07-the-calendar"}],
  "how": ["<b>In order.</b> Each chapter uses only what came before."],
  "parts": {"Part I · Soil": "A line shown under the part's name on the cover."}
}

Key	What it does
`title`	Text before a colon is the first line of the cover. Text after it is the second, coloured line.
`short`	The name shown in the top bar next to the shelf's name.
`order`, `hue`	Position on the shelf, and the colour of the spine (0 to 360).
`scripts`	Files in `assets/` to load, in order. Data files first, widgets after.
`links`	Up to two chapters pinned in the top bar. The first also becomes a button on the cover.
`accent`	The book's own accent colour, for light and dark mode. This guide is blue, the memory book is orange.
`replace`	Words to swap in prose only, never in code. Useful when a product is renamed.
`hidden`	`true` keeps a draft off the shelf. It is still built and reachable by its address.

Try it yourself

Here is a working interactive from this guide's own assets folder. You will write one like it in Chapter 3. Before you move anything, guess: what do two cups a day cost over ten years?

Common questions

Do I need to know JavaScript?

Not to write a book. Chapters are HTML, and a book with no interactives at all is fine. You need a little JavaScript to make your own sliders, and Chapter 3 gives you a pattern of about 25 lines to copy.

Can I write in Markdown?

The engine reads HTML fragments, because interactives, notes and folded answers need real tags. If you draft in Markdown, convert it once and then edit the HTML.

Where does the reader's progress live?

In the reader's own browser. Nothing is sent to a server. Each book has its own list of chapters read.

Carry this

A book is a folder: book.json, chapters/, assets/.
The file name sets the order: 01-, 02-, and so on.
python3 engine/build.py --check builds every book and tells you what is broken.

Check yourself

1. You want a new chapter between chapters 2 and 3. What do you do?

Answer

Rename the files from 03 onwards to 04 onwards and name the new file 03-.... The order comes from the file names. Links to the renamed chapters must be updated, and the check tells you which ones are dead.