This article explains, and demonstrates, the xr package which enables access to, and use of, cross-referencing labels present in external, standalone, LaTeX files. Here, we define a standalone LaTeX file as one which can be compiled because it contains a \documentclass{...} statement and the \begin{document}...\end{document} construct.

LaTeX files specifically written/structured to be included within a “container” document are not standalone because they cannot be compiled without being incorporated into another, suitable, file.

When should I use the xr package?

The following notes explain the types of projects that do, and do not, need to use the xr package.

Projects where the xr package is not required

Large LaTeX projects, such as books or long reports, are often split into a series of smaller .tex files; for example, one .tex file per book chapter. Typically, such book chapters are not standalone: you cannot compile individual chapters because they do not contain a \documentclass{...} statement or the \begin{document}...\end{document} construct. Those chapters are destined for inclusion into a “container” document which can be compiled. In those circumstances, cross-referencing to document elements—within any individual chapter file—can proceed as normal: you do not need to use the xr package.

To explore an example of a large project you can  open this example in Overleaf.

Cross-referencing 101

To cross-reference an item in a LaTeX document you need to:

1. give it a unique identifier, some_string, using the \label command:

\label{some_string}

2. then, at the location where you want to reference that element, you need to write

\ref{some_string}

To be very brief, LaTeX manages cross-referencing by writing data to a file called filename.aux where filename is the name of the main .tex file being compiled.

For the process to work, the LaTeX document has to be compiled at least twice: the first compilation generates the reference data—writing it to filename.aux. During the second compilation, LaTeX reads filename.aux to resolve the references, providing data to replace instances of \ref{some_string}.

• For more detail on cross-referencing see the Overleaf article Cross referencing sections, equations and floats.

Projects where the xr package is required

Suppose you have a set of fully-formed, standalone, LaTeX documents such as a collection of N articles: article1.tex, article2.tex ... articleN.tex. Each article can be compiled separately and it is likely they were written using a variety of document classes, packages etc.

Now imagine there’s a need to write another article, summary.tex, say, which has to reference sections, figures, tables etc contained within those individual, standalone, articles. The xr package let’s you do that: it enables summary.tex to reference labels generated by any of the standalone article*.tex papers.

A note on .aux files

• Note, here we are using an asterisk (*) as a placeholder for any number from 1 to N.

Compiling any of the standalone files article1.tex, article2.tex ... articleN.tex causes LaTeX to generate a corresponding article*.aux (auxillary) file which, among other items, contains label data required to generate cross-references.

If any of the article*.tex files are edited, including changing, adding or removing labels (\label{..}), the corresponding article*.tex file(s) need to be recompiled, particularly if updated article*.aux file(s) are required.

Detecting changes to article*.tex, and subsequently recompiling them, can be automated on Overleaf by using a suitable latexmkrc file.

How to use xr on Overleaf

We will follow our multiple article-file example to demonstrate using the xr package on Overleaf; in particular, we show how to automate the compilation process via a latexmkrc file. Our example is based on code contained in an answer on tex.stackexchange, written by a user called cyberSingularity, but uses a latexmkrc file supplied to Overleaf by John Collins (maintainer of latexmk).

The files used in our example

To streamline the example, our project contains just the following files:

• article1.tex: a single article which, internally, uses cross-references. We want to use those same references within the summary, summary.tex, which requires accessing reference data in the article1.aux file.
• summary.tex: the document that needs to reference document elements, such as figures and sections, contained in article1.tex.
• latexmkrc: contains code (Perl) to automate recompilation of article1.tex due to any changes made to it.

Process outline

• In our example, the file article1.tex is untouched, it is used as written or provided by the original author.
• summary.tex loads the xr package and has some some additional LaTeX code which
  • enables it to access reference data contained in article1.aux;
  • enables latexmkrc to automatically recompile article1.tex, if required—e.g., if article1.tex is edited requiring an updated article1.aux file.
• a latexmkrc file is written.

Loading the xr package

The first step is to load the xr package in the main file you are working on. In this case, this simply means we include

\usepackage{xr}

in the preamble of summary.tex.

• Note: If you’re using the hyperref package in your main file (summary.tex), then load xr-hyper instead of xr in summary.tex before hyperref. You’ll also need to load the hyperref package in the external document (i.e., article1.tex).

The \externaldocument command

The xr package provides the \externaldocument command which has the general form

\externaldocument[prefix]{external_file}

where the optional [prefix] is used to prevent duplicate labels. By way of example, if your main .tex file, e.g. summary.tex, and the external file, article1.tex, both contain \label{eq:1} you can avoid a name clash by writing

\externaldocument[art1-]{article1}

in which case all references from article1.tex are prefixed by art1-. Now you can access \label{eq:1}, contained in article1.tex, by writing \ref{art1-eq:1} in summary.tex.

The initial files: starting points

We will use a very short article1.tex file which contains several cross-references—we want to use some of those references in summary.tex.

Note the following: compiling article1.tex will use a file called article1.aux to write and read its cross-reference data, but compiling summary.tex uses summary.aux for the same purposes. Our goal is to enable summary.tex to read cross-reference data from one or more external .aux files; here, one called article1.aux.

article1.tex

The following code can be opened in Overleaf using the link below the listing.

\documentclass{article}
\title{This is \texttt{article1.tex}}
\begin{document}
\section{Introduction}
\label{introduction}

This is a standalone \LaTeX{} document with
references we want to use in \texttt{summary.tex}.

\subsection{Math references}
\label{mathrefs}
As mentioned in section \ref{introduction}, 
different elements can be referenced within
a document.

\subsection{Powers series}
\label{powers}

\begin{equation}
\label{eq:1}
\sum_{i=0}^{\infty} a_i x^i
\end{equation}

Equation \ref{eq:1} is a typical power series.
\end{document}

 Open article1.tex in Overleaf

Compiling article1.tex produces the following output:

summary.tex

Here is our initial, minimal, summary.tex file prior to adding the code required to access external cross-references created in article1.tex.

Note that summary.tex does not contain any \label{some_string} commands that correspond to each \ref{some_string}. If we compile this version of summary.tex it will attempt to read reference data from summary.aux but, of course the required data is contained in the external article1.aux file which cannot, yet, be accessed.

Observe that the xr package is loaded but that alone is not enough to resolve the cross-references: additional code is required to access the external article1.aux file.

\documentclass{article}
\usepackage{xr}
\title{This is \texttt{summary.tex}}
\begin{document}

In the file \texttt{article1.tex}, the introduction is section \ref{introduction}.  In that file, there are two subsections: \ref{mathrefs} and \ref{powers}. In subsection \ref{powers}, equation \ref{eq:1} demonstrates a power series.
\end{document}

 Open this incomplete summary.tex in Overleaf

Compiling this incomplete summary.tex file produces the following output, with double question marks showing undefined references:

Overleaf reports the undefined references:

Extra code for summary.tex: accessing external references

The following code creates the \myexternaldocument{...} which allows you to specify the external document whose labels you would like to reference from within summary.tex.

\makeatletter
\newcommand*{\addFileDependency}[1]{% argument=file name and extension
\typeout{(#1)}% latexmk will find this if $recorder=0
% however, in that case, it will ignore #1 if it is a .aux or 
% .pdf file etc and it exists! If it doesn't exist, it will appear 
% in the list of dependents regardless)
%
% Write the following if you want it to appear in \listfiles 
% --- although not really necessary and latexmk doesn't use this
%
\@addtofilelist{#1}
%
% latexmk will find this message if #1 doesn't exist (yet)
\IfFileExists{#1}{}{\typeout{No file #1.}}
}\makeatother

\newcommand*{\myexternaldocument}[1]{%
\externaldocument{#1}%
\addFileDependency{#1.tex}%
\addFileDependency{#1.aux}%
}

Specifying the external document

Once the helper code (above) is added to summary.tex, the next step is to specify the external document whose labels you would like to reference. This is the only part of the code you will have to change yourself depending on the name of the file.

\myexternaldocument{article1}

Here, article1 can be replaced by any file whose labels you want to access—you can use multiple \myexternaldocument commands to access additional external files.

Creating the latexmkrc file

The next step is to create a latexmkrc file as shown below:

• In your project editor window, select the New File icon at the top-left of the project window.
• Select New File from within the Add Files pop-up dialog box and name the file latexmkrc—note there is no file extension:

• Make sure that the latexmkrc file created and saved in the top (root) level of the project’s files area. That is, not inside any folders in the file tree.

Code for latexmkrc

Overleaf are grateful to John Collins, maintainer of latexmk, for contacting us to supply the following latexmkrc file, which we are delighted to publish in full—including the extremely helpful inline comments.

# This shows how to use the xr package with latexmk.
# John Collins 2023-03-29
#
# The xr package ("a system for eXternal References") is used by a document
# to make references to sections, equations, etc in other external
# documents. 
# The definitions in this file enable latexmk to apply latexmk to
# automatically update an external document whenever its .tex file changes,
# so that the references in the main document stay up to date.

# Notes:
#    1. This version is defined to put the files from the compilations of
#       the external documents into a defined subdirectory, to segregate
#       potentially many generated files from the main document
#       directories. 
#    2. But for latexmk's custom dependency mechanism to be used, as here,
#       the aux file from compilation of a subdocument must be generated in
#       the same directory as the corresponding source .tex file.  So the
#       .aux file is copied.
#    3. It is assumed that the external documents are to be compiled by
#       pdflatex.  This can be changed, of course, by changing the '-pdf'
#       option given to the invoked latexmk to whatever is needed.
#    4. An ideal implementation would also ensure that recompilation of an
#       external document also happens whenever any of its other source
#       files changes.  But this is not done in the present version, and
#       would probably entail either the use of internal latexmk variables
#       or extra enhancements to latexmk.
#    5. The code uses subroutines copy and fileparse that are loaded by
#       latexmk from the Perl packages File::Copy and File::Basename.
#    6. It also uses some not-yet-documented features of latexmk: an array
#       variable @file_not_found and subroutines popd, pushd, and
#       rdb_add_generated. 


#--------------------
# Configurable choices for compilation of external documents

# Subdirectory for output files from compilation of external documents:
$sub_doc_output = 'output-subdoc';

# Options to supply to latexmk for compilation of external documents:
@sub_doc_options = ();

push @sub_doc_options, '-pdf'; # Use pdflatex for compilation of external documents.
# Replace '-pdf' by '-pdfdvi', 'pdfxe', or 'pdflua' if needed.

#--------------------

# Add a pattern for xr's log-file message about missing files to latexmk's
# list.  Latexmk's variable @file_not_found is not yet documented.
# This line isn't necessary for v. 4.80 or later of latexmk.
push @file_not_found, '^No file\\s*(.+)\s*$';

add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' );
sub makeexternaldocument {
    if ( $root_filename ne $_[0] )  {
        my ($base_name, $path) = fileparse( $_[0] );
        pushd $path;
        my $return = system "latexmk",
                            @sub_doc_options,
                            "-aux-directory=$sub_doc_output",
                            "-output-directory=$sub_doc_output",
                            $base_name;
        if ( ($sub_doc_output ne ' ') && ($sub_doc_output ne '.') ) {
               # In this case, .aux file generated by pdflatex isn't in same
               # directory as the .tex file.
               # Therefore:
               # 1. Actual generated aux file must be listed as produced by this
               #    rule, so that latexmk deals with dependencies correctly.
               #    (Problem to overcome: If $sub_dir_output is same as $aux_dir
               #    for the main document, xr may read the .aux file in the
               #    aux_dir rather than the one the cus dep is assumed by latexmk
               #    to produce, which is in the same directory as the .tex source
               #    file for this custom dependency.)
               #    Use not-yet-documented latexmk subroutine rdb_add_generated
               #    to do this:
               # 2. A copy of the .aux file must be in same directory as .tex file
               #    to satisfy latexmk's definition of a custom dependency.
             rdb_add_generated( "$sub_doc_output/$base_name.aux" );
             copy "$sub_doc_output/$base_name.aux", ".";
        }
        popd;
        return $return;
   }
}

The final Overleaf project files

The following three-file project can now be opened in Overleaf using the links provided above and below the file listings. Note that the latexmkrc file contains the code supplied by John Collins but, for brevity, most of the comments have been removed.

 Open this three-file example in Overleaf.

summary.tex

This is our summary file. From within this file we want to use cross-references created in external files. Here, we want to use labels generated in article1.tex.

% This code is derived from an answer on tex.stackexchange 
% (by cyberSingularity at http://tex.stackexchange.com/a/69832/226)

\documentclass[12pt]{article}

\title{Using the xr package on Overleaf}

%----Helper code for dealing with external references----
% (by cyberSingularity at http://tex.stackexchange.com/a/69832/226)

\usepackage{xr}
\makeatletter

\newcommand*{\addFileDependency}[1]{% argument=file name and extension
\typeout{(#1)}% latexmk will find this if $recorder=0
% however, in that case, it will ignore #1 if it is a .aux or 
% .pdf file etc and it exists! If it doesn't exist, it will appear 
% in the list of dependents regardless)
%
% Write the following if you want it to appear in \listfiles 
% --- although not really necessary and latexmk doesn't use this
%
\@addtofilelist{#1}
%
% latexmk will find this message if #1 doesn't exist (yet)
\IfFileExists{#1}{}{\typeout{No file #1.}}
}\makeatother

\newcommand*{\myexternaldocument}[1]{%
\externaldocument{#1}%
\addFileDependency{#1.tex}%
\addFileDependency{#1.aux}%
}
%------------End of helper code--------------

% put all the external documents here!
\myexternaldocument{article1}

\begin{document}

In the file \texttt{article1.tex}, the introduction is section \ref{introduction}.  In that file, there are two subsections: \ref{mathrefs} and \ref{powers}. In subsection \ref{powers}, equation \ref{eq:1} demonstrates a power series.

\end{document}

article1.tex

This file is one of our articles. Note how it contains various \label commands to create labels that, thanks to the xr package, we can use in the file summary.tex.

\documentclass{article}
\title{This is \texttt{article1.tex}}
\begin{document}
\section{Introduction}
\label{introduction}

This is a standalone \LaTeX{} document with
references we want to use in \texttt{summary.tex}.

\subsection{Math references}
\label{mathrefs}
As mentioned in section \ref{introduction}, 
different elements can be referenced within
a document.

\subsection{Powers series}
\label{powers}

\begin{equation}
\label{eq:1}
\sum_{i=0}^{\infty} a_i x^i
\end{equation}

Equation \ref{eq:1} is a typical power series.
\end{document}

latexmkrc

This latexmkrc file contains code to ensure the external files are compiled.

$sub_doc_output = 'output-subdoc';

@sub_doc_options = ();

push @sub_doc_options, '-pdf'; # Use pdflatex for compilation of external documents.
# Replace '-pdf' by '-pdfdvi', 'pdfxe', or 'pdflua' if needed.

push @file_not_found, '^No file\\s*(.+)\s*$';

add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' );
sub makeexternaldocument {
    if ( $root_filename ne $_[0] )  {
        my ($base_name, $path) = fileparse( $_[0] );
        pushd $path;
        my $return = system "latexmk",
                            @sub_doc_options,
                            "-aux-directory=$sub_doc_output",
                            "-output-directory=$sub_doc_output",
                            $base_name;
        if ( ($sub_doc_output ne ' ') && ($sub_doc_output ne '.') ) {

             rdb_add_generated( "$sub_doc_output/$base_name.aux" );
             copy "$sub_doc_output/$base_name.aux", ".";
        }
        popd;
        return $return;
   }
}

 Open this three-file example in Overleaf.

The following graphic is an annotated version of the output from typesetting summary.tex, showing the cross-references and the corresponding labels from the external file article1.tex.

A note about syntax errors

For your main project file, you can use Overleaf’s Stop on First Error compilation mode to ensure compilation terminates immediately upon detection of the first error. This can help isolate and identify errors in your code, rather than allowing errors to cascade, making it far more difficult to find and debug problems.

The external documents are compiled automatically via the latexmkrc file; consequently, any LaTeX syntax errors within them won’t show in the Overleaf interface—unless you recompile them in Overleaf too. Errors in those external files could prevent cross-references from appearing correctly in the typeset PDF file, so we strongly recommend checking and correcting any such errors as soon as they occur.