Carebun Interactive/Make a book

The guide

Chapter 5

Check and publish

Two commands that catch what you cannot see, and how a finished book reaches the shelf.

5 min read

On this page
  1. Check 1: the files
  2. Check 2: the pages
  3. Publish
  4. Common questions
  5. Carry this
  6. Check yourself

In this chapter, we will learn how to check a book before anyone reads it, and how it gets onto the shelf. There are two checks. The first reads your files. The second opens every page in a real browser and uses it.

Check 1: the files

python3 engine/build.py --check
It reportsUsual cause
meta is not valid JSONA missing quote or a comma after the last entry
unknown widgetA typing mistake in data-widget, or the script is not listed in book.json
dead linkA chapter was renamed
a tag opened 3 times, closed 2A missing </details> or </section>

Check 2: the pages

node tools/smoke.mjs            # every page, every control
node tools/smoke.mjs --shots    # and a picture of every page, wide and phone-sized

The smoke test opens each page in Chrome without a window and behaves like a careless reader. It drags every slider to both ends, presses every button twice and types into every text field. It fails if the browser reports an error, if an interactive did not start, if "NaN" appears on screen, or if the page scrolls sideways at the width of a phone.

Then look at the pictures yourself. A machine can tell that nothing is broken. Only a person can tell that a label sits on top of a line.

Publish

The whole shelf is one folder of static files. Any web server can host it.

./deploy.sh --preview     # build, check, test, then serve on http://localhost:8000
./deploy.sh               # build, check, test, then deploy the container

To offer a book for this shelf, send the book's folder. Nothing outside books/your-book/ needs to change, so a new book cannot break an existing one.

Common questions

My book is not finished. Can I still publish?

Set "hidden": true in book.json. The book is built and you can share its address, but it does not appear on the shelf.

Can I host my book somewhere else?

Yes. Copy the engine folder and your book's folder, build, and upload dist to any static host.

Carry this

  • build.py --check reads the files. smoke.mjs uses the pages.
  • Look at the pictures. Machines find errors, people find ugliness.
  • A book lives in its own folder, so it cannot break another book.

Check yourself

1. The file check passes and the smoke test fails with "scrolls sideways by 140px". Where do you look first?

Answer

For a table without its table-wrap, or a long line in a block of fixed text. Those are the two things that are wider than a phone.