How a book is structured

Most works on LibreTimes are one text: a lecture note, a problem sheet, an essay. A book is different. It is a tree of divisions, such as volumes, parts and chapters, and it is read one chapter at a time. This page explains that model, why it is built that way, and what follows for the Markdown you write inside it. The steps are in Write a book.

A tree, not one long text

A five-hundred-page textbook as one Markdown document would be one enormous page: slow to open, impossible to navigate except by scrolling, and with a table of contents that has to be inferred from headings. A book here is instead a tree whose nodes are divisions:

Analysis
├── Preface                       front matter, has text   → a page
├── Part I. Limits                part, no text            → navigation
│   ├── 1. Sequences              chapter, has text        → a page
│   └── 2. Series                 chapter, has text        → a page
└── Part II. Derivatives          part, no text            → navigation
    └── 3. The derivative         chapter, has text        → a page

A division with text is a page. A reader opens it, reads it, and moves to the next with the page's own controls; the contents rail beside it shows where they are in the book.

A division without text is navigation. A part or a volume usually has no text of its own: it is a heading in the contents that groups the chapters under it. If a part does have an introduction, give it text and it becomes a page too.

The contents are the tree itself, not something read off the headings, so they are exact, and they work the same for a novel with numbered chapters and for a treatise with volumes, parts and sections.

What a division has

Each division carries a few fields, and they are deliberately separate:

Field	What it is	Example
Kind	What the division is: a chapter, a part, a volume, a poem, a scene, front or back matter…	Chapter
Label	The words the book itself uses for it, printed as written	`1`, `II`, `Book the Second`
Title	The division's own title, when it has one	Sequences
Address	An optional name for citing it, in the book's own scheme	`I.1`
Text	The chapter, in LibreTimes Markdown

The kind is a fixed set, so the site knows what each division is and can lay out the contents and the reader accordingly. The label is free, because books number their parts in every possible way, and the printed words are part of the edition. Most chapters in most books have a label and no title, and that is fine: neither field is invented when it is missing.

One kind is grouped differently. An article is a short numbered unit inside a chapter or a part, such as a numbered paragraph of a treatise. Consecutive articles are read together on one page, so a reader is not sent to a new page every few lines, while each article keeps its own address.

Addresses that never move

Every page of a book has an address, …/read/<n>, where n counts the pages in reading order. While the book is a draft, n follows the order you are building and may change with every edit, because nobody can have cited a draft yet.

From the moment the book is first published, the numbers are settled:

a chapter keeps its address when you move it;
a new chapter takes the next free number, wherever it sits in the book;
a deleted chapter's address is retired and never given to another chapter.

So a link to a chapter, in a syllabus or in a citation, keeps pointing at that chapter. That stability matters more than having n match the reading order forever, which is what the optional Address field is for: a name like I.1 or Prop. 12 that says where the chapter is in the book's own numbering.

Markdown inside a chapter

A chapter's text is LibreTimes Markdown like any other work's. Three things follow from it being a page of a book:

The chapter's label and title are the page's heading. The text starts its sections at ##, as in any work, and a chapter rarely needs any: the structure of a book is its tree, not its headings. Headings inside a chapter are for a textbook chapter's numbered sections.
Footnotes belong to the chapter. Each chapter is its own page, so its notes are numbered from 1 and gathered at the end of that chapter.
The book constructs are at home here. Verse with its line breaks and indents, epigraphs, dedications, letters, small capitals and the page numbers of a printed edition all work in any work, but books are where they come from. See Verse, epigraphs and letters.

How paragraphs are set is a property of the whole book, never marked on a paragraph: a novel can be read with first-line indents and a centred asterism for a scene break, the way print sets it, while your source stays plain paragraphs and --- lines. Marking it per paragraph would put one typographic decision into a thousand places where it could be forgotten in three of them.

A book or a course

Both are long and both have parts, so the choice is worth making on purpose.

A book is one work with one byline, one citation and one licence. Its chapters are not published separately and do not appear on their own in search or on your profile. Choose it for a continuous text: a textbook, a monograph, lecture notes rewritten as one text.
A course is a collection of works, each published, found and cited on its own: one lecture note per lecture, a problem sheet per week. Choose it when each piece stands on its own. See Collections.

Translations of a book

A translation of a book is a tree of its own: it starts as a copy of the original's contents, with the same kinds, labels, addresses and order, but without titles or text, and you fill it in chapter by chapter. It stays visible only to the book's editors until you publish it. Because the tree is copied, each chapter has the same Address in both, and a reader can move from a chapter to the same chapter in the other language.