Input and compilation/Project and file management
🚧 This page is currently being revised and reconstructed.
Its structure, examples, and explanations are being updated for current ConTeXt and LuaMetaTeX. Please feel free to edit, correct, or improve this page while the revision is in progress.
Input and compilation · Overview · Project and file management · Sample documents
Contents
- 1 Project and file management
- 1.1 1. Choosing the simplest structure
- 1.2 2. The four building blocks
- 1.3 3. Defining a file and loading a file are different operations
- 1.4 4. A minimal multifile book
- 1.5 5. Adding a project
- 1.6 6. Compiling components independently
- 1.7 7. Environments and loading behaviour
- 1.8 8. File names and extensions
- 1.9 9. Directories and file lookup
- 1.10 10. Debugging file lookup
- 1.11 11. Naming conventions
- 1.12 12. Project management is not the only solution
- 1.13 13. Common mistakes
- 1.14 14. Current LMTX behaviour checked for this page
- 1.15 15. Command overview
- 1.16 16. Mental map
- 1.17 17. Further reading
- 1.18 18. See also
Project and file management
ConTeXt does not use document classes in the same way as LaTeX. The layout, typography, structure, and behaviour of a document can be configured directly, and those settings can be collected in reusable files.
For a small document, no project structure is required at all.
For larger work, ConTeXt provides four related mechanisms:
- environment — reusable setup and definitions;
- component — a reusable part of a document;
- product — a document or output assembled from content and components;
- project — a coordination layer for several related products.
These mechanisms are particularly useful for books, theses, manuals, journals, documentation sets, or collections in which the same setup or the same content must be reused.
The important principle
Do not introduce a project merely because a document contains several files.
Use the simplest structure that matches the job.
1. Choosing the simplest structure
A useful way to think about ConTeXt document organization is:
single document
|
+-- environment
| shared setup becomes useful
|
+-- product + components
| one output is split into reusable parts
|
+-- project
several related products must be coordinated
1.1 A single document
For many documents, the ordinary form is sufficient:
\starttext \startchapter[title={Introduction}] Some text. \stopchapter \stoptext
If everything belongs to one file and no setup needs to be reused, there is no reason to add a product or project layer.
1.2 A document plus an environment
If the document setup becomes substantial, move it into an environment:
environment.tex document.tex
The environment can contain, for example:
- fonts;
- page layout;
- heading setup;
- colours;
- language settings;
- macros;
- interaction settings;
- bibliography setup;
- modes;
- other reusable definitions.
The document then remains mostly concerned with content.
1.3 One product with several components
If one document is becoming large, split its content into components:
environment.tex book.tex chapter-01.tex chapter-02.tex chapter-03.tex
Here the product represents the book and the components represent its chapters or other reusable parts.
Add a project when several products belong together:
project
|
+-- environment
|
+-- product A
| |
| +-- component
| +-- component
|
+-- product B
|
+-- component
+-- component
For example:
| Kind of work | Project | Product | Component |
|---|---|---|---|
| Magazine | the magazine | one issue | one article |
| Book series | the series | one book | one chapter |
| Documentation | the documentation set | one manual | one section or chapter |
2. The four building blocks
2.1 Environment
An environment contains reusable setup rather than document content.
A minimal environment may look like this:
\startenvironment env_book \setuppapersize[A5] \setupbodyfont [modern,11pt] \setuphead [chapter] [style=\bfc] \stopenvironment
It is loaded with:
\environment env_book
An environment is not limited to page layout. It can contain almost any setup or definition that should be shared by documents.
Useful property
An environment is loaded only once during a run, even if the same
\environment command is encountered more than once.
This makes it practical for both a product and its individual components to request the same environment.
2.2 Component
A component is a document part that can be included in a product and, when designed appropriately, processed independently.
For example:
\startcomponent chapter-01 \environment env_book \startchapter [title={The first chapter}] This is the first chapter. \stopchapter \stopcomponent
A component is loaded with:
\component chapter-01
Unlike an environment, a component is loaded at every mention. Therefore:
\component chapter-01 \component chapter-01
typesets the component twice.
This distinction is fundamental:
\environment same-file
\environment same-file
|
+--> loaded once
\component same-file
\component same-file
|
+--> loaded twice
2.3 Product
A product represents a document or output assembled from components and possibly from content written directly in the product file.
For example:
\startproduct book \environment env_book \component chapter-01 \component chapter-02 \stopproduct
A product can be processed directly:
context book.tex
A separate \starttext ... \stoptext pair is not normally needed
inside a product: \startproduct ... \stopproduct already defines
a document-level unit.
A product also does not have to contain components exclusively. Direct content and structural commands can be placed in it when that is useful.
2.4 Project
A project coordinates related products and their shared setup.
For example:
\startproject project_series \environment env_series \product book-one \product book-two \stopproject
The corresponding product can refer back to the project:
\startproduct book-one \project project_series \component chapter-01 \component chapter-02 \stopproduct
The project file is normally a coordination file, not an output unit. In ordinary use, compile a product or a component rather than the project itself.
Do not think of these commands as aliases for \input.
Commands such as \project, \product,
\component, and \environment are aware of the
current project structure.
For example, a product may load a project that itself declares that product without recursively loading the product again.
3. Defining a file and loading a file are different operations
There are two related families of commands.
The \start... ... \stop... commands describe the role of the
current file:
| Current file is a... | Delimiting commands |
|---|---|
| environment | \startenvironment ... \stopenvironment
|
| component | \startcomponent ... \stopcomponent
|
| product | \startproduct ... \stopproduct
|
| project | \startproject ... \stopproject
|
The corresponding loading commands refer to another file:
| Load | Command |
|---|---|
| an environment | \environment |
| a component | \component |
| a product | \product |
| a project | \project |
Conceptually:
\startcomponent chapter-01
|
+--> says: "this file is a component"
\component chapter-01
|
+--> says: "load that component here"
Keeping these two roles separate makes project files much easier to understand.
4. A minimal multifile book
For one book, a full project layer is often unnecessary.
A compact and robust structure is:
book/ | +-- env_book.tex +-- book.tex +-- chapter-01.tex +-- chapter-02.tex
4.1 Environment
% env_book.tex \startenvironment env_book \setuppapersize[A5] \setupbodyfont [modern,11pt] \setuphead [chapter] [style=\bfc] \stopenvironment
4.2 Product
% book.tex \startproduct book \environment env_book \component chapter-01 \component chapter-02 \stopproduct
4.3 First component
% chapter-01.tex \startcomponent chapter-01 \environment env_book \startchapter [title={First chapter}] This is the first chapter. \stopchapter \stopcomponent
4.4 Second component
% chapter-02.tex \startcomponent chapter-02 \environment env_book \startchapter [title={Second chapter}] This is the second chapter. \stopchapter \stopcomponent
4.5 Compiling
Compile the complete book with:
context book.tex
During editing, compile one chapter independently with:
context chapter-01.tex
Because the component requests the same environment as the product, it retains the common setup when processed on its own.
When the complete product is processed, the repeated request for
env_book does not reload the environment.
5. Adding a project
Suppose there are now two related books:
series/
|
+-- env_series.tex
+-- project_series.tex
|
+-- book-one/
| +-- book-one.tex
| +-- chapter-01.tex
| +-- chapter-02.tex
|
+-- book-two/
+-- book-two.tex
+-- chapter-01.tex
+-- chapter-02.tex
The project can coordinate them:
% project_series.tex \startproject project_series \environment env_series \product book-one \product book-two \stopproject
A product refers to the project:
% book-one.tex \startproduct book-one \project project_series \component chapter-01 \component chapter-02 \stopproduct
The normal compilation target remains the product:
context book-one.tex
The project establishes relationships between products; it is not intended to replace the product as the normal output file.
6. Compiling components independently
One of the practical advantages of components is that a large document does not need to be processed in full after every small edit.
A chapter can normally be compiled directly:
context chapter-07.tex
This is useful for:
- writing and proofreading;
- testing figures;
- testing notes;
- adjusting local typography;
- checking references and structure;
- reducing compilation time during development.
However, independent compilation must still provide whatever setup the component requires.
Typical solutions are:
- load the common environment directly in the component;
- let the component link to a product or project that supplies the required
setup;
- organize the environment so that it can safely be requested from more than
one level.
A component is reusable only if its dependencies are reusable.
A component that assumes fonts, macros, paths, bibliography datasets, or other definitions that exist only in one particular product may not compile correctly by itself.
Keep shared setup in environments whenever practical.
7. Environments and loading behaviour
Project-aware loading commands have their own semantics.
The most important distinction is:
| File type | Repeated request for the same file | Typical purpose |
|---|---|---|
| environment | loaded once | reusable setup |
| component | loaded at every mention | reusable content |
This is intentional.
Setup should normally not be executed repeatedly, while content may legitimately be inserted more than once.
7.1 Environments may be layered
A large project does not need one enormous environment file.
For example:
\environment env-fonts \environment env-colors \environment env-layout \environment env-bibliography
This makes the setup easier to maintain and allows some layers to be reused by other products.
7.2 Environments and modes
An environment is also a natural place for modes.
For example, one project may provide:
- a print layout;
- a screen layout;
- a correction version;
- a final version.
The content files can remain unchanged while the environment adapts the output.
8. File names and extensions
User project files normally use the ordinary .tex extension:
env_book.tex book.tex chapter-01.tex project_series.tex
The extension can normally be omitted from project-management commands:
\environment env_book \component chapter-01
Files do not need to be renamed to .mkxl merely because the
document is processed with LuaMetaTeX/LMTX.
ConTeXt supports version-specific suffixes, but .tex remains a
normal choice for user documents and project files.
9. Directories and file lookup
Keeping every file in one directory quickly becomes inconvenient.
A project might instead use:
project_series.tex
env_series.tex
book-one/
book-one.tex
chapters/
introduction.tex
chapter-01.tex
chapter-02.tex
images/
book-two/
book-two.tex
chapters/
introduction.tex
chapter-01.tex
images/
shared-images/
logo.pdf
ConTeXt's project-aware file lookup is more flexible than a simple
\input. In particular, environment and project files can be
found in parent directories in common project layouts.
For explicit control, use \usepath.
9.1 Using \usepath
For example:
\usepath [environments,chapters]
or:
\usepath [../environments,../chapters]
Several calls can also be combined:
\usepath[environments] \usepath[chapters] \usepath[../shared]
Note
\usepath is not a MetaPost-specific command. It can be used to
extend the lookup paths for ordinary ConTeXt project files.
9.2 Images use their own directory setup
Image lookup can be configured separately:
\setupexternalfigures [directory={images,../shared-images}]
Keeping source-file lookup and image lookup conceptually separate usually makes complex projects easier to maintain.
10. Debugging file lookup
When ConTeXt does not find an environment, component, or other source file, first check:
- the file name and capitalization;
- the current directory;
- parent directories;
- paths added with
\usepath; - whether the file is being compiled independently or through its product;
- whether image paths are being confused with source-file paths.
Resolver tracing can help show where ConTeXt is looking.
For example:
\enabletrackers[resolvers.locating] \environment does-not-exist \disabletrackers[resolvers.locating]
Then inspect the log.
This is usually more informative than repeatedly changing relative paths by trial and error.
11. Naming conventions
ConTeXt imposes no requirement that project files use prefixes such as
env_, prd_, or c_.
They can nevertheless be useful when many files share one directory.
A traditional convention is:
project_mymag.tex env_mymag.tex prd_issue-01.tex c_editorial.tex c_article-01.tex
With a directory structure, shorter names may be clearer:
magazine/
environment.tex
project.tex
2026-01/
product.tex
editorial.tex
article-01.tex
Choose a scheme that makes the role of each file obvious to the people who maintain the project.
Hraban maintains a helper script, contextproject.py, which can be used to create project files from templates. This is an external convenience tool, not a requirement of ConTeXt.
12. Project management is not the only solution
The project/product/component model is powerful, but it is not mandatory.
If there is only one output document, a simpler structure may be preferable.
For example:
\environment myenvironment \startdocument ... \stopdocument
or simply:
\environment myenvironment \starttext ... \stoptext
Modules loaded with \usemodule, environments, ordinary input files, and components can all be combined without introducing a full project.
Rule of thumb
Use:
environment
when setup should be reused
component
when content should be reusable or independently processable
product
when several pieces form one document or output
project
when several related products need coordination
13. Common mistakes
13.1 Starting with a project too early
A document split into several files does not automatically need a project.
For one book, an environment plus a product and components is often enough.
13.2 Treating \component like \input
A component is structure-aware and is loaded at every mention.
If the same component is mentioned twice, its content appears twice.
13.3 Expecting an environment to reload
The same environment is loaded only once.
Do not rely on repeatedly calling \environment to re-execute
setup code.
13.4 Putting content into the project file
Keep a normal project file primarily declarative:
- shared environments;
- product declarations;
- project-level coordination.
The normal typesetting targets are products and components.
13.5 Forgetting standalone component dependencies
A component may compile perfectly as part of a product but fail on its own if it does not have access to:
- the environment;
- fonts;
- macros;
- bibliography data;
- figures;
- path settings.
Design the dependency chain deliberately.
13.6 Hard-coding fragile relative paths
For a substantial project, prefer a clear directory organization together
with \usepath and appropriate figure directories rather than
scattering long relative paths throughout the content.
14. Current LMTX behaviour checked for this page
The following behaviours have been checked with a current LuaMetaTeX/LMTX installation while revising this documentation:
| Test | Observed behaviour |
|---|---|
| standalone product | a product can be processed directly |
| standalone component | a component can be processed directly |
| product linked to a project | the product loads the project without recursively reloading itself |
| product loading an environment | the environment is loaded and its setup is available to the product |
| same environment requested twice | the environment file is loaded once |
| same component requested twice | the component file is loaded twice |
These observations are more useful than treating
\project, \product,
\component, and \environment
as ordinary file-input commands: their behaviour depends on their role in
the document structure.
15. Command overview
| Purpose | Define the current file | Load or refer to another file |
|---|---|---|
| Environment | \startenvironment ... \stopenvironment
|
\environment |
| Component | \startcomponent ... \stopcomponent
|
\component |
| Product | \startproduct ... \stopproduct
|
\product |
| Project | \startproject ... \stopproject
|
\project |
Other useful commands include:
- \usepath — extend source-file lookup paths;
- \usemodule — load a module;
- \startdocument — another document-level structure;
\setupexternalfigures[directory=...]— configure image lookup.
16. Mental map
reusable setup
|
+------v------+
| environment |
+------+------+
|
+-----------------+-----------------+
| |
v v
+-----------+ +-----------+
| product A | | product B |
+-----+-----+ +-----+-----+
| |
+-----+-----+ +-----+-----+
| | | |
v v v v
component component component component
\_____________________________________/
|
v
project
coordinates related products
Or, when only one output is needed:
environment
|
v
product
|
+---+---+
| |
v v
component component
The second structure is often all that a book or thesis needs.
17. Further reading
- Hans Hagen (2011),
Project Structure, ConTeXt Magazine 1101.
- March 2026 mailing-list discussion:
Questions about \start-ing things with \environment and \project.
- March 2026 mailing-list discussion:
Where does \environment look?.
18. See also
- Input and compilation
- Conditional processing with Modes
- Sample documents
- Document layout tutorials
- \environment
- \component
- \product
- \project
- \usepath
Input and compilation · Overview · Project and file management · Sample documents
