Introduction to Multi-File Projects

When you first start with LaTeX, it is natural to keep everything in a single .tex file. However, as your projects grow—such as a thesis, a book, or a lengthy technical report—a single file can quickly become thousands of lines long. This makes it difficult to navigate, hard to debug, and cumbersome when collaborating with others.

Multi-file projects allow you to break your document into smaller, manageable chunks (like individual chapters or sections). This modular approach offers several advantages:

Organization: Keep your preamble, chapters, and bibliography separate.
Clarity: Focus on writing one section at a time without scrolling through 50 pages of code.
Efficiency: Use "selective compilation" to compile only the chapter you are currently working on, saving time.
Collaboration: Different authors can work on different files simultaneously without causing merge conflicts in a single file.

The Main File: Your Project's Control Center

In a multi-file project, there is always one "Master" or "Main" file. This file acts as the skeleton of your document. It contains the \documentclass declaration, the preamble (where you load packages and define settings), and the document environment.

Instead of writing the actual content inside the document environment, you use special commands to "pull in" content from other files.

Example of a Main File (`main.tex`)

\documentclass[12pt]{report}

% --- Preamble ---
\usepackage[utf8]{inputenc}
\usepackage{graphicx}
\usepackage{hyperref}

\title{My Comprehensive LaTeX Project}
\author{Jane Doe}
\date{\today}

% --- Document Body ---
\begin{document}

\maketitle
\tableofcontents

% We will pull in chapters here
\include{chapters/introduction}
\include{chapters/literature-review}
\include{chapters/methodology}

\end{document}

Note: When you compile your project, you must always run the LaTeX compiler on this Main file, not the individual chapter files.

Using the `\input` Command

The simplest way to merge files is the \input{filename} command. When LaTeX encounters \input, it effectively "copy-pastes" the entire content of the specified file into the main document at that exact spot.

Characteristics of `\input`:

Literal Insertion: It does not start a new page or add any special formatting.
Nesting: You can use \input inside a file that was itself included via \input.
Versatility: It can be used anywhere: in the preamble (to load a separate file containing your custom macros) or in the document body.

Example Usage:

If you have a file named intro.tex containing:

\section{Introduction}
Welcome to my project. This text is stored in a separate file!

You would include it in your main file like this:

\input{intro}

Using the `\include` and `\includeonly` Commands

While \input is simple, \include is more powerful and is the preferred method for large documents like books and theses.

How `\include` Works

The \include{filename} command does two main things differently than \input:

Forced Page Break: It automatically starts a new page before and after the included content. This makes it ideal for chapters.
Auxiliary Files: It creates separate .aux files for each included file, which stores cross-referencing information.

Selective Compilation with `\includeonly`

The biggest benefit of \include is the ability to use \includeonly in your preamble. This tells LaTeX to only process specific files while still maintaining correct page numbers and cross-references from the rest of the document.

Example of Selective Compilation:

\documentclass{book}

% Only compile the methodology chapter to save time
\includeonly{chapters/methodology}

\begin{document}
    \include{chapters/introduction}
    \include{chapters/methodology} % This will be compiled
    \include{chapters/conclusion}
\end{document}

In this example, LaTeX will only render the Methodology chapter, but it will know that the Introduction preceded it, ensuring that the Methodology page numbers and section numbers (e.g., Chapter 2) remain correct.

Organizing Your Project Directory

As your project grows, your folder can become cluttered with .tex, .jpg, .pdf, and .bib files. A professional LaTeX project should follow a clean directory structure.

Recommended Folder Structure:

Project-Root/
├── main.tex             (The master file)
├── main.pdf             (The output)
├── references.bib       (Your bibliography)
├── preamble.sty         (Optional: custom settings)
├── chapters/            (Folder for content)
│   ├── introduction.tex
│   ├── methodology.tex
│   └── conclusion.tex
└── figures/             (Folder for images)
    ├── chart.png
    └── diagram.pdf

Dealing with Paths

When your files are in subfolders, you must tell LaTeX where to find them. You can use relative paths:

\include{chapters/introduction}
To handle images in a subfolder, add this to your preamble:
```
\graphicspath{{figures/}}
```
This allows you to simply use \includegraphics{chart.png} without typing the folder name every time.

Best Practices and Common Pitfalls

To ensure your multi-file project runs smoothly, keep these tips in mind:

1. Don't Nest `\include`

You cannot use \include inside a file that has already been included via \include. If you need to break a chapter down into smaller sub-sections, use \input inside the chapter file.

2. File Extensions are Optional

In commands like \input{chapter1.tex} or \include{chapter1}, the .tex extension is optional. Omitting it makes your code slightly cleaner.

3. Keep the Preamble Clean

If your preamble becomes very long (loading 20+ packages), move it to a separate file (e.g., settings.tex) and use \input{settings} at the very top of your main file.

4. Watch Out for White Space

The \include command forces a clear page. If you want to include a small snippet of text in the middle of a page, always use \input.

5. Use "Magic Comments" for Editors

Most LaTeX editors (like Typevia, TeXstudio, or VS Code) allow you to add a "magic comment" at the top of your sub-files. This tells the editor which file is the "Main" file, so you can press "Compile" while looking at a chapter file and it will automatically run the main file.

Add this to the very top of introduction.tex:

% !TeX root = ../main.tex

Warning: Avoid using spaces in your filenames (e.g., use chapter_one.tex instead of chapter one.tex). Many LaTeX compilers struggle with spaces in file paths and may throw obscure errors.

Introduction to Multi-File Projects

On this page