Writing content

You write your book in standard Markdown. This chapter covers how the content you write turns into a chapter page.

Markdown basics

Write chapters in plain Markdown. Headings, lists, links, emphasis, tables, and fenced code blocks all work out of the box:

## A section heading

A paragraph with **bold**, *italic*, and a [link](https://example.com).

- a list item
- another item

> A blockquote, styled as a callout.

Use ## (H2) for the top-level sections of a chapter and ### (H3) for sub-points. The chapter title comes from front matter, so you do not write an H1 in the body.

Sections and the TOC

The sections list in a chapter’s front matter is the backbone of navigation. Each entry generates three things:

1. An in-page index at the top of the chapter (the list under the title).
2. Sidebar links inside the table of contents.
3. Anchor links of the form /chapter/#section-name.

Your ## (H2) headings must match the sections entries exactly. Keeping them in sync is the single most important habit when writing a chapter — otherwise the navigation links won’t reach the right spot:

sections:
  - "Images and figures"   # must match an `## Images and figures` heading

Images and figures

Put images and other static files anywhere under assets/ and reference them with a root-relative path:

![A short description](/assets/images/diagram.png)

In print, images are automatically centered and capped at 25em tall so they never overflow a page (see the print styles).

Callouts and code

A blockquote (>) is styled as a lightweight callout — useful for notes, warnings, and asides:

Heads up: this renders as a distinct, indented note block.

Fenced code blocks (```) are styled for readability in both light and dark themes. Specify a language for clarity:

```bash
bundle exec jekyll serve
```

Page breaks and print

A few utility classes help control the printed/PDF output. Apply them with kramdown’s inline attribute syntax or raw HTML:

• .page-break forces a page break before an element when printing.
• .hidden-print hides an element in print (used for navigation and buttons).
• .linebreak shows a <br> only on wider screens (handy for controlling where titles wrap).

<div class="page-break"></div>

Printing and publishing are covered in detail in the final chapter.