Docs

Write a book

Start a book, build its contents from parts and chapters, write each chapter in Markdown, and publish it, on the site or from a folder of files with lt.

On this page

A book is one work read a chapter at a time: a textbook, a monograph, lecture notes rewritten as a continuous text. This guide builds one on the site, then shows the same book written as files and published with lt, the LibreTimes command-line client. Why a book is a tree of chapters, and why its addresses never move once published, is explained in How a book is structured.

Start the book

  1. Go to /new, which New publication on your home page opens, and choose Book.
  2. Choose the language the book is written in, then Start the book.

The editor opens with the contents on the left and the open chapter beside them. The book's title, description, categories and co-authors are set in the same editor. The book stays a private draft until you publish it.

Build the contents

  1. Choose Add chapter. A new division appears in the contents.
  2. Set its Kind: chapter, part, volume, section, front matter and so on.
  3. Set its Label, the number or word the book prints for it, such as 1, II or Appendix A, and its Title if it has one.
  4. Optionally, give it an Address, a short name for citing it in the book's own numbering, such as I.1. It must be unique within the book.
  5. To put a chapter inside a part, select the chapter and choose Nest under the one above. Move out one level, Move up and Move down rearrange the tree.

A part with no text of its own is shown in the contents as a heading that groups its chapters; readers do not open it. Give it text, such as an introduction to the part, and it becomes a page too.

Write a chapter

  1. Select the chapter in the contents and click its Text to edit it.
  2. Write the chapter in LibreTimes Markdown, exactly as in any other work.

The chapter's label and title are the page's heading, so the text does not repeat them, and any sections inside it start at ##. Footnotes are numbered per chapter. Everything in the dialect works here, and the constructs that come from books are at home:

Result

Happy families are all alike; every unhappy family is unhappy in its own way.

— Leo Tolstoy, Anna Karenina

The house had been quiet since morning.

By evening the letter had arrived:

Dear Anna,

I shall be at the station at nine.

Yours,
S.

Markdown
:::epigraph
Happy families are all alike; every unhappy family is unhappy in its own way.
 
--- Leo Tolstoy, *Anna Karenina*
:::
 
The house had been quiet since morning.
 
---
 
By evening the letter had arrived:
 
:::letter
Dear Anna,
 
I shall be at the station at nine.
 
Yours,\
S.
:::

A --- line on its own is a scene break, which a book can show as a centred asterism. See Verse, epigraphs and letters for verse, small capitals and the page numbers of a printed edition.

Publish the book

  1. Check that at least one chapter has text: a book with none cannot be published.
  2. Add the categories and tags that will help readers find it.
  3. Choose Create Publication, with the visibility you want beside it.

From that moment, every chapter's address, …/read/<n>, is fixed. Moving a chapter keeps its address; a new chapter takes the next free number; a deleted chapter's address is retired rather than given to another chapter. So links to chapters in a syllabus or a citation keep working.

Or write it as files and publish with lt

If you keep the book in files, under version control or alongside LaTeX sources, lt publishes it from a folder: one Markdown file per chapter, and one manifest that gives the book's details and its contents in order.

  1. Put each chapter's text in its own .md file.

  2. Write the manifest, book.md, with type: book and the contents tree:

    ---
import_key: ivanov/analysis-book
type: book
title: Analysis
language: en
license: cc_by_sa
contents:
  - file: preface.md
    kind: front_matter
    label: Preface
  - label: Part I
    title: Limits
    children:
      - file: 01-sequences.md
        label: "1"
        title: Sequences
        ref: I.1
      - file: 02-series.md
        label: "2"
        title: Series
        ref: I.2
---

  3. Check what would happen, then publish:

    lt work publish my-book/book.md --dry-run
    lt work publish my-book/book.md --yes

An entry with children and no file is a part, shown as a heading in the contents. ref is the chapter's Address. Give every chapter one: on a re-run, lt matches chapters to the site by it, so reordering the manifest moves chapters with their text. import_key is what makes the next run update this book instead of creating a second one. The full set of keys is in the lt README.

The result

The published book has a contents rail listing its parts and chapters, and each chapter with text is a page of its own, with a link to the next. Its address, …/read/<n>, stays the same for as long as the chapter exists.