| TODO: This page presents a current LMTX model for organising a book. Please test the representative files with a recent ConTeXt LMTX installation and improve or correct the page where useful. (See: To-Do List) |
Current LMTX sample — organising a book as a project
This page presents a compact model for organising a book with current ConTeXt LMTX. It is intended as a modern companion to the historical Theory book style example.
A short document can perfectly well be written in a single ConTeXt source file. For a substantial book, however, it is usually clearer to separate the publication into a project, one or more products, reusable environments, and individual components.
project
│
├── environment(s)
│ └── shared setup and document design
│
└── product(s)
└── publication assembled from components
│
├── front matter
├── chapters
├── appendices
└── back matter
This page therefore does not try to print the source of an entire real book with many fully developed chapters. Instead, it combines directory-tree diagrams with short representative files so that the architecture remains visible.
A very small bibliography may occasionally be shown in a ConTeXt
buffer on this page. This is only a wiki demonstration device: it
keeps a bibliographic example self-contained and avoids requiring an
additional file merely to test a few lines of code. In a real book
project, the bibliography would normally live in a separate
.bib file, as shown in the project tree below.
Use this example with current ConTeXt LMTX
The examples on this page use native UTF-8 input, OpenType fonts, the
current btx bibliography mechanism, and the current
project/product/component interfaces.
They are not intended as compatibility examples for MkII or for older
ConTeXt installations. In particular, a new LMTX project normally does
not need older input-encoding commands such as
\enableregime or \setupencoding, and it
should not be based on the former bib module.
For a project-sized example, local compilation is more useful than the compact wiki renderer because file relationships, section blocks, references, bookmarks, bibliography data, and the index all depend on document-wide state.
Contents
- 1 1. What the example demonstrates
- 2 2. A possible project structure
- 3 3. Project, product, environment, and component
- 4 4. The project file
- 5 5. The environment file
- 6 6. The product file
- 7 7. A chapter component
- 8 8. Front matter and appendices
- 9 9. Bibliography data: real project and wiki buffer
- 10 10. The index
- 11 11. Draft and production settings
- 12 12. How the whole project fits together
- 13 13. Turning the model into a local project
- 14 14. Why this differs from the historical example
- 15 15. Where to go next
1. What the example demonstrates
The model brings together:
- a project, a product, an environment, and components;
- native UTF-8 input and a current OpenType font setup;
- a simple double-sided book layout;
- front matter, body matter, appendices, and back matter;
- chapters and sections;
- a table of contents;
- running chapter titles and page numbers;
- cross-references;
-
a current
btxbibliography; - an index;
- a simple draft mode for inspecting the page layout.
This is a model of organisation, not a universal book template
The project/product/component model is useful for substantial documents because it separates responsibilities. It is not mandatory for every book, and the exact directory layout is not prescribed by ConTeXt.
Real publications may use more environments, several products, custom fonts, specialised front matter, multiple bibliographies or registers, graphics directories, language-specific components, or publisher-specific production settings.
The purpose here is to show a clean starting architecture before those additional layers are introduced.
2. A possible project structure
A small but realistic book project could be organised like this:
modern-book/
│
├── project-modern-book.tex
├── environment-modern-book.tex
├── product-modern-book.tex
│
├── frontmatter/
│ ├── titlepage.tex
│ └── preface.tex
│
├── chapters/
│ ├── chapter-01.tex
│ └── chapter-02.tex
│
├── appendices/
│ └── appendix-a.tex
│
├── backmatter/
│ ├── references.tex
│ └── index.tex
│
└── bibliography/
└── references.bib
The directories are only an organisational choice. The important distinction is the role of the files:
project-modern-book.tex
│
├── loads shared environment(s)
│
└── identifies product(s)
│
▼
product-modern-book.tex
│
└── assembles components in publication order
│
┌─────────┼───────────────┐
▼ ▼ ▼
front matter body matter appendices
│ │ │
└─────────┴───────┬───────┘
▼
back matter
│
▼
final publication
environment-modern-book.tex
│
├── language and fonts
├── paper and layout
├── section heads
├── headers and footers
├── bibliography setup
├── registers
└── draft/production settings
The same architecture can support a very small book or a much larger one. Adding twenty more chapter components does not require the basic design to be rewritten.
3. Project, product, environment, and component
A useful working distinction is:
PROJECT
│
└── defines the publication family
│
├── ENVIRONMENT
│ shared configuration
│
└── PRODUCT
one publication
│
└── COMPONENTS
individual content units
The boundaries are organisational rather than typographical. A component may contain a chapter, an appendix, a preface, or another coherent unit of content. The structural commands inside the component still determine what that material is in the document hierarchy.
Source organisation is not document structure
A file called chapter-01.tex is not a chapter merely because
of its filename or because it is a component.
It becomes a chapter when its content uses a structural command such as
\startchapter ... \stopchapter.
Keep these two questions separate:
How is the source organised? project / product / component How is the document structured? chapter / section / subsection / ...
4. The project file
The project is the top-level description of the publication family. A minimal project file may load one shared environment and identify one product.
% project-modern-book.tex \startproject project-modern-book \environment environment-modern-book \product product-modern-book \stopproject
A larger project may have several environments or products. For example, the same project could eventually produce a print edition, a teaching edition, or different language products while sharing part of the same configuration.
5. The environment file
The environment collects settings that should be reusable throughout the book.
% environment-modern-book.tex \startenvironment environment-modern-book %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % LANGUAGE AND FONT %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \mainlanguage[en] \setupbodyfont [libertinus,10pt] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % PAPER AND LAYOUT %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \setuppapersize[A5] \setuplayout [backspace=18mm, topspace=15mm, header=8mm, headerdistance=4mm, footer=8mm, footerdistance=4mm, width=middle, height=middle] \setuppagenumbering [alternative=doublesided, location=] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % PDF INTERACTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \setupinteraction [state=start, title={A Modern LMTX Book}, author={Example Author}] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % HEADERS AND FOOTERS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \setupheadertexts [\getmarking[chapter]] \setupfootertexts [\pagenumber] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % SECTION HEADS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \setuphead [chapter] [page=yes, header=empty, style=\tfc, align=middle, before={\blank[2*big]}, after={\blank[3*big]}] \setuphead [section] [style=\tfa, before={\blank[big]}, after={\blank[medium]}] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % TABLE OF CONTENTS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \setupcombinedlist [content] [list={chapter,section}] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % BIBLIOGRAPHY %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \usebtxdefinitions [apa] \definebtxdataset [main] \usebtxdataset [main] [bibliography/references.bib] \definebtxrendering [main] [dataset=main, criterium=text, specification=apa] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % OPTIONAL DRAFT MODE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Enable from the command line or temporarily uncomment: % \enablemode[draft] \startmode[draft] \showframe \stopmode \stopenvironment
This file contains no chapter text. Its job is to describe the common typesetting environment in which the components will be processed.
6. The product file
The product assembles the content in publication order.
% product-modern-book.tex \startproduct product-modern-book \project project-modern-book \startdocument [title={A Modern LMTX Book}, author={Example Author}] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % FRONT MATTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startfrontmatter \component frontmatter/titlepage \component frontmatter/preface \stopfrontmatter %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % BODY MATTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startbodymatter \component chapters/chapter-01 \component chapters/chapter-02 \stopbodymatter %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % APPENDICES %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startappendices \component appendices/appendix-a \stopappendices %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % BACK MATTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startbackmatter \component backmatter/references \component backmatter/index \stopbackmatter \stopdocument \stopproduct
The product file contains very little prose. Its main job is to state the sequence in which the publication is assembled.
The distinction can be visualised as:
PRODUCT FILE COMPONENT FILES
\startfrontmatter ───────────► titlepage.tex
└───────────► preface.tex
\startbodymatter ───────────► chapter-01.tex
└───────────► chapter-02.tex
\startappendices ───────────► appendix-a.tex
\startbackmatter ───────────► references.tex
└───────────► index.tex
7. A chapter component
A component contains an actual unit of content. For example:
% chapters/chapter-01.tex \startcomponent chapter-01 \project project-modern-book \startchapter [title={Structure before appearance}, marking={Structure}, reference=ch:structure] A book is easier to maintain when its logical structure is expressed explicitly. This paragraph also creates an index entry for document structure.\index{document structure} \startsection [title={A structural section}, reference=sec:structure] This is a numbered section inside a numbered chapter. Its identity as a section is independent of the way its head is typeset. \stopsection \startsection [title={Presentation can change}] The appearance of chapter and section heads is controlled separately with \type{\setuphead}. Changing their font, spacing, or alignment does not redefine the document hierarchy.\index{section heads} \stopsection \stopchapter \stopcomponent
A second chapter could refer back to the structural reference:
section \in[sec:structure]
The reference belongs to the document structure, even though the source and target live in different component files.
8. Front matter and appendices
The same component mechanism can be used for other parts of the book.
A preface component might contain:
% frontmatter/preface.tex \startcomponent preface \project project-modern-book \startchapter [title={Preface}] This book is organised as a ConTeXt project. \stopchapter \stopcomponent
Because this component is included between
\startfrontmatter and \stopfrontmatter in the
product, the section block supplies the front-matter context.
Likewise, an appendix component can contain an ordinary chapter structure:
% appendices/appendix-a.tex \startcomponent appendix-a \project project-modern-book \startchapter [title={A small appendix}, reference=app:sample] This remains a chapter structurally, but it occurs in the appendices. \stopchapter \stopcomponent
With the standard section-block setup, the appendix context can change the representation of chapter numbering without changing the structural level of the chapter.
9. Bibliography data: real project and wiki buffer
In the project tree, bibliographic data lives in:
bibliography/ └── references.bib
A minimal file could contain:
@book{beiser1987, author = {Beiser, Frederick C.}, title = {The Fate of Reason}, subtitle = {German Philosophy from Kant to Fichte}, year = {1987}, publisher = {Harvard University Press}, address = {Cambridge, MA}, }
The environment loads that dataset with:
\usebtxdataset [main] [bibliography/references.bib]
A chapter can then cite it:
\cite[authoryears][main::beiser1987]
and the back-matter component can place the bibliography:
% backmatter/references.tex \startcomponent references \project project-modern-book \startchapter [title={References}] \placebtxrendering [main] \stopchapter \stopcomponent
Why a buffer may appear in a wiki example
A tiny bibliography can instead be embedded temporarily in a buffer:
\startbuffer[references] @book{example, author = {Author, Example}, title = {An Example Book}, year = {2026}, publisher = {Example Press}, } \stopbuffer \usebtxdataset [main] [references.buffer]
This is convenient for a self-contained Garden demonstration because the
reader can copy one block of source without first creating a separate
.bib file.
It should not be confused with the project architecture described on this
page. In a real book project, keeping bibliographic data in a separate
.bib file is normally clearer and easier to maintain.
10. The index
Index entries may be placed in any component:
\index{document structure} \index{section heads} \index{bibliography}
The back matter can then contain a small index component:
% backmatter/index.tex \startcomponent index \project project-modern-book \completeindex \stopcomponent
The index therefore belongs to the publication as a whole even though its entries originate in many different component files.
11. Draft and production settings
Project organisation also makes it easier to keep temporary production settings out of chapter content.
The environment above contains:
\startmode[draft] \showframe \stopmode
A draft can therefore be produced without editing every component.
For a temporary local test, one may uncomment:
\enablemode[draft]
in the environment. For an established project, modes can instead be enabled from the compilation workflow.
Keep production aids out of content files
Frames, debugging aids, temporary line numbering, alternate layouts, and similar production settings normally belong in an environment or a mode, not scattered through chapter components.
This keeps the textual components focused on document content and structure.
12. How the whole project fits together
The complete flow can now be represented as:
PROJECT
│
┌────────────┴────────────┐
│ │
▼ ▼
ENVIRONMENT PRODUCT
│ │
common configuration │
│ │
│ ┌──────────┼───────────┐
│ │ │ │
│ ▼ ▼ ▼
│ FRONT MATTER BODY MATTER APPENDICES
│ │ │ │
│ ▼ ▼ ▼
│ components components components
│ │ │ │
│ └──────────┼───────────┘
│ │
│ ▼
│ BACK MATTER
│ │
│ bibliography
│ + index
│ │
└──────────────┬──────────┘
▼
FINAL PUBLICATION
Another way to read the same architecture is:
configuration ───────────────► environment
publication order ───────────► product
content units ───────────────► components
bibliographic data ──────────► .bib dataset
structural hierarchy ────────► chapter / section / ...
large document regions ──────► frontmatter / bodymatter /
appendices / backmatter
These layers interact, but they solve different problems.
13. Turning the model into a local project
The source fragments on this page are deliberately representative rather than a complete book download. The directory tree contains more component files than are printed in full here, because repeating nearly identical chapter files would hide the architecture the page is intended to explain.
To make a local test project, create the tree shown above, copy the
representative files, and add small placeholder components for any files
that are present in the product but not reproduced in full on this page.
For example, chapters/chapter-02.tex can initially contain a
single short chapter.
Once all referenced components exist, compile the product from the project directory:
context product-modern-book.tex
When testing a component on its own, keep its
\project project-modern-book line so that it can inherit the
shared project environment.
If a representative file does not compile
First check that the complete directory tree has been created and that file names and relative paths match the examples.
Also check that you are using a recent ConTeXt LMTX installation.
This page is intended to document current practice. If an example requires correction for a current LMTX release, please correct the example rather than adding obsolete compatibility code to it.
14. Why this differs from the historical example
The historical Theory book style page is valuable because it preserves a real production environment from an earlier generation of ConTeXt.
The present page has a different purpose:
HISTORICAL EXAMPLE CURRENT LMTX MODEL
real 2006–2007 environment pedagogical 2026 architecture
│ │
older encoding model native UTF-8
older font setup OpenType fonts
former bib system current btx system
large single environment project organisation
project-specific dependencies minimal representative files
│ │
preserve as documentation use as a starting model
The editorial problems are recognisably similar: page design, section heads, references, bibliography, indexes, and production settings still have to cooperate. What has changed is the appropriate technical organisation and the interfaces used to solve them.
15. Where to go next
For the concepts behind chapters, sections, section blocks, lists, markings, and reference targets, see Understanding document structure and section heads.
For practical customisation, see:
- Headlines formatting
- Section numbering
- Table of contents
- Bibliography and citations
- Registers and index
To develop the project structure introduced on this page, continue with Project and file management. That page explains how projects, products, environments, and components fit together and how they can be organised in a larger source tree.
For larger projects, the important next step is not to add more code to a single file, but to decide:
shared configuration ───► environment publication assembly ───► product content units ───► components overall organisation ───► project
This makes it possible to extend the small sample shown here into a real book project without changing its basic architecture.