Overleaf: Difference between revisions

From Stat DS Computing Wiki
Newer edit →
VisualWikitext
Created page with "<!-- TODO: set the category (and sort key) to match where this article lives in the wiki --> XX If your experiment code lives in a GitHub repository and your paper lives on Overleaf, you have probably done '''the upload dance''': rerun an experiment, hunt down the regenerated figure on disk, open Overleaf, delete the old file, upload the new one, and repeat for every figure and table that changed. It is slow, it is easy to le..."
 
No edit summary
Line 2: Line 2:
[[Category:Beginner's_Guide_Implementation|XX]]
[[Category:Beginner's_Guide_Implementation|XX]]


If your experiment code lives in a GitHub repository and your paper lives on Overleaf, you have probably done '''the upload dance''': rerun an experiment, hunt down the regenerated figure on disk, open Overleaf, delete the old file, upload the new one, and repeat for every figure and table that changed. It is slow, it is easy to leave a stale figure behind, and it leaves no record of which version of your code produced which figure in the paper.
'''[https://www.overleaf.com Overleaf]''' is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.


Overleaf Premium's '''GitHub Synchronization''' feature removes most of this busywork. This article describes one particular way to use it: cloning the paper's repository '''inside''' your experiment repository, in a directory that the experiment repository ignores. Your analysis scripts then write figures and tables straight into the paper, and a single push sends them to Overleaf.
If you already know LaTeX, there is very little to learn: you write the same <code>.tex</code> and <code>.bib</code> files you would write locally, and Overleaf runs the compiler for you. What Overleaf adds is everything ''around'' the LaTeX: shared editing, comments, change tracking, version history, and a single place where every co-author sees the same compiled PDF.


<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Important: Overleaf Premium is required'''<br>
'''New to Overleaf?'''<br>
GitHub Synchronization is a paid Overleaf feature. Check whether you already have access through an institutional license before paying for it yourself. If you don't use Git yet, read up on the basics first, since this workflow assumes you are comfortable with <code>clone</code>, <code>commit</code>, <code>push</code>, and <code>pull</code>.
The quickest way in is the [https://www.youtube.com/watch?v=xcTN4F3l9Ds video introduction to Overleaf], which walks through the editor, compiling, and sharing in a few minutes. For anything this article doesn't cover, the [https://www.overleaf.com/learn Overleaf help site] has documentation on the editor as well as a large collection of general LaTeX guides.
</div>
</div>


== How It Works ==
== How It Works ==
There are several ways to connect a code repository to an Overleaf project. In this one, the two repositories stay '''completely independent'''. The paper repository is cloned into a subdirectory (here called <code>paper/</code>), and that subdirectory is listed in the experiment repository's <code>.gitignore</code>. The experiment repository never records anything about the paper, and the paper repository never sees your experimental code. Your scripts simply write files into a folder that happens to be a different Git repository.
An Overleaf '''project''' is a folder of files (your <code>.tex</code> sources, bibliography, figures, style files) stored on Overleaf's servers. When you click '''Recompile''', Overleaf runs the project through <code>latexmk</code> on its own TeX Live installation and shows you the resulting PDF next to the source. Everyone who has access to the project edits the same files at the same time, and changes appear for everyone as they are typed.
 
The final layout looks like this:
 
<pre>
my-experiments/                ← experiment repo (github.com/you/my-experiments)
├── .gitignore                  ← contains "paper/"
├── src/
├── scripts/
│  └── make_figures.py        ← writes into paper/figures and paper/tables
├── Makefile
└── paper/                      ← SEPARATE git repo, ignored by the outer repo
    ├── .git/                  ← points to github.com/you/my-paper
    ├── main.tex
    ├── refs.bib
    ├── figures/                ← written by code
    │  └── coverage.pdf
    └── tables/                ← written by code
        └── results.tex
</pre>
 
Generated figures and tables flow from your code to Overleaf, and prose written on Overleaf flows back to your local copy:
 
<pre>
scripts/make_figures.py ──writes──▶ paper/figures, paper/tables
paper/  ──git push──▶  GitHub (my-paper)  ──"Pull GitHub changes"──▶  Overleaf
Overleaf ──"Push Overleaf changes"──▶  GitHub (my-paper)  ──git pull──▶  paper/
</pre>


{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
Line 47: Line 20:
|- style="vertical-align: top; background-color: #f8f9fa;"
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
| style="padding: 15px; border-right: 2px solid white;" |
* '''No More Uploading:''' Regenerated figures and tables reach the paper with one commit and one push, no manual file shuffling required.
* '''Nothing to Install:''' A complete, maintained TeX Live distribution is available from any browser, so "it compiles on my machine" stops being a problem.
* '''Clean Histories:''' Paper edits never clutter your code history, and code changes never clutter your paper history.
* '''Real-Time Collaboration:''' Co-authors edit the same document simultaneously, with comments and tracked changes built in.
* '''No Coupled Tracking:''' Unlike git submodules, you never need an extra "update the paper pointer" commit in your experiment repository every time the paper changes.
* '''One Source of Truth:''' There is exactly one copy of the paper, and everyone sees the same compiled PDF.
* '''Collaborator Friendly:''' Co-authors can keep writing on Overleaf as usual. Nothing about their workflow changes.
* '''Built-In History:''' Overleaf records who changed what, and you can restore earlier versions.
* '''Templates:''' Thousands of journal and conference templates are a click away in the template gallery.
| style="padding: 15px;" |
| style="padding: 15px;" |
* '''Sync Is Manual:''' Overleaf does not watch GitHub. Someone has to click a button in Overleaf to pull new changes in (and to push Overleaf edits out).
* '''Compile Limits:''' Large documents, heavy TikZ/pgfplots figures, or slow packages can hit the compile timeout, especially on the free plan.
* '''Provenance Is Up to You:''' Because the repositories are not linked, the only record of which code produced a figure is whatever you write in the paper's commit messages. A small script (below) handles this for you.
* '''Online by Default:''' You need an internet connection to work comfortably, and the browser editor is not your local editor of choice.
* '''One More Thing to Clone:''' Anyone who wants to regenerate the paper's figures needs to clone the paper repository separately.
* '''Premium Paywall:''' Many useful features (Git/GitHub sync, more collaborators, longer history, reference manager integration) require a paid plan.
* '''Not a Code Repository:''' Overleaf is not a good place for the code and data that produce your figures.
|-
|-
| colspan="2" style="background-color: #e9ecef; text-align: center; padding: 10px;" | 🔗 '''[https://www.overleaf.com/learn/how-to/GitHub_Synchronization Overleaf Documentation: GitHub Synchronization]'''
| colspan="2" style="background-color: #e9ecef; text-align: center; padding: 10px;" | 🔗 '''[https://www.overleaf.com/learn Overleaf Help and Documentation]'''
|}
|}


== Setting It Up ==
== Getting Started ==
 
=== Step 1: Link Overleaf to GitHub ===
In Overleaf, open '''Account Settings''' and find the GitHub entry under the project synchronization section. Click '''Link''' and authorize Overleaf in the GitHub dialog that pops up.
 
<!-- SCREENSHOT: Overleaf Account Settings page with the GitHub "Link" button visible. -->
[[File:Overleaf-account-settings-github-link.png|thumb|center|600px|Linking a GitHub account from Overleaf's account settings.]]
 
=== Step 2: Create a GitHub repository from your Overleaf project ===
Open your paper in Overleaf, click '''Menu''' in the top left, and choose '''GitHub''' under the ''Sync'' section. Select '''Create a GitHub repository''', give it a name (e.g. <code>my-paper</code>), and make it private. Overleaf then pushes the current contents of your project to the new repository.


<!-- SCREENSHOT: Overleaf project Menu, with the "Sync → GitHub" entry highlighted. -->
=== Step 1: Create an account ===
[[File:Overleaf-menu-sync-github.png|thumb|center|300px|The GitHub entry in the Overleaf project menu.]]
Go to [https://www.overleaf.com overleaf.com] and sign up. If you have a university email address, sign up with it (or add it to an existing account under '''Account Settings'''), since that is how Overleaf recognizes institutional licenses.
 
<!-- SCREENSHOT: The "Create a GitHub repository" dialog filled in with name and private visibility. -->
[[File:Overleaf-create-github-repo.png|thumb|center|500px|Creating the paper repository from Overleaf.]]


<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Tip: Already have the paper on GitHub?'''<br>
'''Important: Check for an institutional license'''<br>
You can go the other direction instead. In Overleaf, choose '''New Project → Import from GitHub''' and select your existing repository.
Many universities pay for Overleaf Premium (often called Overleaf Commons) for their students and staff. Before paying for a plan yourself, check whether your institution provides one; linking your institutional email is usually all it takes to unlock Premium features.
</div>
</div>


=== Step 3: Clone the paper inside your experiment repository ===
<!-- SCREENSHOT: Overleaf Account Settings showing the "Emails and affiliations" section with an institutional address added. -->
From the root of your experiment repository, tell Git to ignore the <code>paper/</code> directory '''before''' you clone into it:
[[File:Overleaf-account-affiliation.png|thumb|center|600px|Adding an institutional email address to unlock an institutional license.]]
 
<syntaxhighlight lang="bash">
cd my-experiments
echo "paper/" >> .gitignore
git add .gitignore
git commit -m "Ignore nested paper clone"


git clone git@github.com:you/my-paper.git paper
=== Step 2: Create or import a project ===
</syntaxhighlight>
From the project dashboard, click '''New Project'''. You can start from:


Then check that the two repositories don't see each other:
* '''Blank Project''' or '''Example Project''' for a minimal starting point.
* '''Upload Project''' to upload a <code>.zip</code> of an existing local LaTeX project.
* '''Templates''' to start from a journal or conference template (many venues publish an official one in the gallery).
* '''Import from GitHub''' (Premium) to start from an existing repository.


<syntaxhighlight lang="bash">
<!-- SCREENSHOT: The Overleaf dashboard with the "New Project" dropdown open. -->
git status          # should NOT list paper/
[[File:Overleaf-new-project-menu.png|thumb|center|400px|Options for creating a new project.]]
git -C paper status # shows the paper repo, on its own branch
</syntaxhighlight>


<!-- SCREENSHOT: Terminal showing both `git status` outputs (outer repo clean, inner repo on its own branch). -->
=== Step 3: Get to know the editor ===
[[File:Nested-clone-git-status.png|thumb|center|600px|The outer repository ignores <code>paper/</code>; the inner repository is independent.]]
The editor has three main panes: the '''file tree''' on the left, the '''source editor''' in the middle, and the '''PDF preview''' on the right. A few things worth knowing right away:


<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
* '''Recompile''' (or <code>Ctrl/Cmd + Enter</code>) builds the PDF. Auto-compile can be toggled from the dropdown next to the button.
'''Warning: Don't skip the <code>.gitignore</code> entry'''<br>
* '''Double-clicking in the PDF''' jumps to the corresponding line of source, and the arrow buttons between the panes jump the other way (SyncTeX).
Without it, a careless <code>git add .</code> in the experiment repository will register <code>paper/</code> as an "embedded repository," which confuses collaborators and anything else that clones your code. If this happens, <code>git rm --cached paper</code> undoes it.
* The '''Code Editor / Visual Editor''' toggle at the top switches between raw LaTeX and a rich-text-like view. Experienced LaTeX users usually stay in the Code Editor, but co-authors less comfortable with LaTeX may prefer the Visual Editor.
</div>
* The '''Logs and output files''' button next to Recompile shows errors and warnings, each with a link to the offending line.


=== Step 4: Point your code at the paper directory ===
<!-- SCREENSHOT: The full Overleaf editor with file tree, source, and PDF preview visible, ideally with the Recompile button and logs icon annotated. -->
Rather than hard-coding paths in every script, define the paper location once. Using an environment variable with a sensible default means the code still runs for people who haven't cloned the paper (their figures just land in an ignored folder).
[[File:Overleaf-editor-overview.png|thumb|center|700px|The Overleaf editor: file tree, source, and compiled PDF.]]


<syntaxhighlight lang="python">
=== Step 4: Check the project settings ===
# src/paths.py
Open '''Menu''' (top left) to set the project-wide compile options:
import os
from pathlib import Path


REPO_ROOT = Path(__file__).resolve().parents[1]
* '''Compiler:''' pdfLaTeX by default; switch to XeLaTeX or LuaLaTeX if you need system fonts or Unicode-heavy input.
PAPER_DIR = Path(os.environ.get("PAPER_DIR", REPO_ROOT / "paper"))
* '''TeX Live version:''' new projects use a recent release. Leave older projects on their original version unless you have a reason to upgrade, since package updates can occasionally break a working document.
FIG_DIR = PAPER_DIR / "figures"
* '''Main document:''' if your project has several <code>.tex</code> files, make sure the one with <code>\documentclass</code> is selected here. Compiling the wrong file is a common source of confusing errors.
TAB_DIR = PAPER_DIR / "tables"


FIG_DIR.mkdir(parents=True, exist_ok=True)
<!-- SCREENSHOT: The Overleaf project Menu with the Compiler, TeX Live version, and Main document settings highlighted. -->
TAB_DIR.mkdir(parents=True, exist_ok=True)
[[File:Overleaf-menu-settings.png|thumb|center|300px|Compiler and main-document settings in the project menu.]]
</syntaxhighlight>


For '''figures''', save vector PDFs directly into the paper. Removing the creation timestamp means a figure that didn't actually change produces an identical file, so Git won't report a pointless change:
== Working With Co-Authors ==


<syntaxhighlight lang="python">
=== Sharing a project ===
import matplotlib.pyplot as plt
Click '''Share''' in the top right to invite collaborators by email, as either '''editors''' or '''viewers'''. You can also turn on link sharing, which gives anyone with the link view or edit access; be careful with edit links, since they work for anyone who receives them.
from src.paths import FIG_DIR


fig, ax = plt.subplots(figsize=(3.25, 2.4))  # match your template's column width
<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
...
'''Warning: Collaborator limits'''<br>
fig.savefig(FIG_DIR / "coverage.pdf", bbox_inches="tight",
The free plan only allows a small number of collaborators per project. The limit is set by the '''project owner's''' plan, so if your co-authors can't be added, the easiest fix is usually to have someone with Premium (or an institutional license) own the project.
            metadata={"CreationDate": None})
</syntaxhighlight>
 
For '''tables''', write a LaTeX fragment rather than a full document:
 
<syntaxhighlight lang="python">
from src.paths import TAB_DIR
 
tex = df.to_latex(index=False, escape=True, float_format="%.3f")
(TAB_DIR / "results.tex").write_text(tex)
</syntaxhighlight>
 
and pull both into the paper as usual:
 
<syntaxhighlight lang="latex">
\includegraphics[width=\linewidth]{figures/coverage}
...
\input{tables/results}
</syntaxhighlight>
 
For '''numbers quoted in the text''', the same idea works. Have your code write LaTeX macros so the prose never goes stale:
 
<syntaxhighlight lang="python">
(TAB_DIR / "numbers.tex").write_text(
    f"\\newcommand{{\\coverageNinetyFive}}{{{cov95:.1f}\\%}}\n"
)
</syntaxhighlight>
 
<syntaxhighlight lang="latex">
% preamble
\input{tables/numbers}
% body
Our intervals achieve \coverageNinetyFive{} empirical coverage.
</syntaxhighlight>
 
== Day-to-Day Workflow ==
 
=== Sending new results to the paper ===
After rerunning your experiments, commit and push from inside <code>paper/</code>:
 
<syntaxhighlight lang="bash">
python scripts/make_figures.py
 
cd paper
git pull                        # pick up any text edits pushed from Overleaf first
git add figures tables
git commit -m "Regenerate figures from my-experiments@$(git -C .. rev-parse --short HEAD)"
git push
</syntaxhighlight>
 
Then, in Overleaf, open '''Menu → GitHub''' and click '''Pull GitHub changes into Overleaf'''.
 
<!-- SCREENSHOT: Overleaf GitHub sync dialog showing the "Pull GitHub changes into Overleaf" button, ideally with a pending commit listed. -->
[[File:Overleaf-pull-github-changes.png|thumb|center|500px|Bringing the regenerated figures into Overleaf.]]
 
<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Important: Overleaf does not sync automatically'''<br>
Overleaf only picks up changes from GitHub when someone clicks the pull button, and only sends its own changes to GitHub when someone clicks the push button. Forgetting the pull is by far the most common reason the paper still shows old figures.
</div>
</div>


The commit message above includes the short hash of your experiment repository. Since the two repositories aren't linked, this message is your record of which code produced which figure. Running <code>git log -- figures/coverage.pdf</code> inside <code>paper/</code> will answer "where did this figure come from?" months later.
=== Comments and tracked changes ===
Highlight any text and click the comment button to start a discussion thread in the margin, much like comments in Word or Google Docs. Threads can be replied to and resolved.


=== Automating it with a Makefile ===
Switching the editor from '''Editing''' to '''Reviewing''' mode turns on '''track changes''': every insertion and deletion is recorded and shown in the margin, where co-authors can accept or reject it. This is the most polite way to edit someone else's section.
Once the steps above feel familiar, wrap them in a single command:


<syntaxhighlight lang="make">
<!-- SCREENSHOT: The review panel showing a comment thread and a tracked change with accept/reject buttons. -->
PAPER := paper
[[File:Overleaf-review-panel.png|thumb|center|600px|Comments and tracked changes in the review panel.]]
SHA  := $(shell git rev-parse --short HEAD)$(shell git diff --quiet || echo -dirty)


.PHONY: figures paper-sync
=== History and versions ===
Click '''History''' to see a timeline of changes, who made them, and a diff of each. You can '''label''' a version (e.g. "Submitted to AISTATS") so it is easy to find later, and restore files from earlier points. The free plan only keeps a limited window of history, so label important milestones and don't rely on Overleaf as your only backup.


figures:
<!-- SCREENSHOT: The History view with a labeled version and a diff visible. -->
python scripts/make_figures.py
[[File:Overleaf-history-view.png|thumb|center|600px|Browsing project history and labeling a version.]]


paper-sync: figures
== Getting Files In and Out ==
git -C $(PAPER) pull --rebase
Overleaf is easy to use on its own, but you will often want to move files between it and your computer.
git -C $(PAPER) add figures tables
git -C $(PAPER) diff --cached --quiet || \
  git -C $(PAPER) commit -m "Regenerate figures from my-experiments@$(SHA)"
git -C $(PAPER) push
@echo "Now click 'Pull GitHub changes into Overleaf' in the Overleaf GitHub menu."
</syntaxhighlight>
 
Now <code>make paper-sync</code> regenerates everything, skips the commit if nothing actually changed, marks the commit <code>-dirty</code> if your experiment code had uncommitted changes, and reminds you to pull in Overleaf.
 
=== When co-authors edit on Overleaf ===
Before regenerating figures locally, push any Overleaf edits out to GitHub ('''Menu → GitHub → Push Overleaf changes to GitHub''') so that the <code>git pull</code> in <code>paper/</code> picks them up.
 
<!-- SCREENSHOT: The same GitHub sync dialog, this time highlighting the "Push Overleaf changes to GitHub" button. -->
[[File:Overleaf-push-to-github.png|thumb|center|500px|Sending Overleaf edits back to GitHub.]]
 
=== Avoiding conflicts ===
Conflicts are rare if every file has exactly one "owner":


<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''<code>figures/</code> and <code>tables/</code> belong to your code.''' Never edit them by hand on Overleaf; the next regeneration will silently overwrite your changes. Change the formatting in the code that generates them instead.
'''Manual upload and download (free):''' The '''Upload''' button in the file tree accepts individual files or a whole folder. '''Menu → Download → Source''' gives you a <code>.zip</code> of the project, and the download button above the PDF gives you the compiled paper. This is fine for occasional use, but tedious if your figures change often.
</div>
</div>


<div style="background-color: #f8f9fa; border-left: 4px solid #228B22; padding: 15px; margin-bottom: 10px;">
<div style="background-color: #f8f9fa; border-left: 4px solid #228B22; padding: 15px; margin-bottom: 10px;">
'''<code>.tex</code> and <code>.bib</code> files belong to people.''' Write them on Overleaf (or locally, then push), and always pull before you push figures.
'''Git and GitHub sync (Premium):''' Every Premium project can be cloned directly with Git, and can also be synchronized with a GitHub repository. This lets you edit locally in your own editor, and lets your analysis code write figures and tables straight into the paper. See [[Overleaf_GitHub_Sync|Syncing Experiment Code with Overleaf via GitHub]] for a complete workflow. <!-- TODO: fix this link to match the actual title of the GitHub sync article -->
</div>
</div>


== Why Not a Git Submodule? ==
<div style="background-color: #f8f9fa; border-left: 4px solid #FFD43B; padding: 15px; margin-bottom: 10px;">
Git submodules are the "official" way to put one repository inside another, so it is natural to ask why this workflow avoids them.
'''Reference managers and Dropbox (Premium):''' Overleaf can import a <code>.bib</code> file from Zotero or Mendeley and refresh it on demand, and can keep a project synced with a Dropbox folder.
 
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="background-color: #e9ecef; padding: 10px; text-align: left;" |
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Gitignored Clone
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Git Submodule
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Git Subtree
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Experiment repo records the paper version''' || style="padding: 10px;" | No || style="padding: 10px;" | Yes (a pointer) || style="padding: 10px;" | Yes (full history)
|-
| style="padding: 10px;" | '''Extra commit in experiment repo per paper change''' || style="padding: 10px;" | No || style="padding: 10px;" | Yes || style="padding: 10px;" | Yes
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Paper history mixed into code history''' || style="padding: 10px;" | No || style="padding: 10px;" | No || style="padding: 10px;" | Yes
|-
| style="padding: 10px;" | '''Special clone instructions for collaborators''' || style="padding: 10px;" | No || style="padding: 10px;" | <code>--recurse-submodules</code> || style="padding: 10px;" | No
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Link between figure and code version''' || style="padding: 10px;" | Commit message || style="padding: 10px;" | Automatic || style="padding: 10px;" | Automatic
|}
 
A submodule gives you exact, automatic provenance, but at a price: every change to the paper, including every typo fix a co-author pushes from Overleaf, needs a matching "bump the submodule" commit in your experiment repository. For a paper that is edited daily, that noise usually isn't worth it. The gitignored clone trades automatic provenance for a scripted commit message, which is plenty in practice.
 
== Variations ==
 
<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Skip GitHub with Overleaf's Git integration:''' Overleaf Premium also lets you clone a project directly (<code>git clone https://git.overleaf.com/<project-id></code>, using a Git token generated in Account Settings). Clone that into the gitignored directory instead, and a <code>git push</code> lands in Overleaf immediately with no pull button. The catch is that you no longer get a GitHub copy of the paper for issues, reviews, or backups.
</div>
</div>


<div style="background-color: #f8f9fa; border-left: 4px solid #FFD43B; padding: 15px; margin-bottom: 10px;">
== Tips for Experienced LaTeX Users ==
'''Generating figures on a cluster:''' Clone the paper repository on the cluster as well and run <code>make paper-sync</code> there. Alternatively, point <code>PAPER_DIR</code> at a scratch directory on the cluster, copy the outputs back to your laptop, and push from there.
* '''You can configure <code>latexmk</code>:''' Overleaf builds with <code>latexmk</code>, and you can add a file named <code>latexmkrc</code> to the project root to customize the build (for example, to run extra tools or set environment variables).
</div>
* '''Clear the cache when things get weird:''' If errors persist after you've fixed the source, open the logs pane and choose '''Clear cached files''', then recompile. Stale auxiliary files cause most "impossible" errors.
* '''Turn off "Stop on first error" carefully:''' The recompile dropdown lets you compile through errors, as <code>-interaction=nonstopmode</code> would. This is handy for seeing the whole document, but don't let errors accumulate.
* '''Draft mode for speed:''' The recompile dropdown has a '''Fast [draft]''' option that skips images, which helps a lot with figure-heavy documents.
* '''Precompile heavy figures:''' Complex TikZ or pgfplots figures are the most common cause of compile timeouts. Compile them separately (or generate them in your analysis code) and include the resulting PDF with <code>\includegraphics</code>.
* '''Use the help site for LaTeX questions too:''' The [https://www.overleaf.com/learn Overleaf help site] doubles as one of the better general-purpose LaTeX references on the web.


== Common Pitfalls ==
== Common Pitfalls ==
Line 275: Line 132:
|- style="vertical-align: top; background-color: #f8f9fa;"
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px;" |
| style="padding: 15px;" |
* '''Forgetting the Overleaf pull:''' Your figures are on GitHub, but Overleaf still shows the old ones. The reminder in the Makefile helps.
* '''Compile timeouts:''' Large documents and heavy figures can exceed the compile time limit, which is shorter on the free plan. Precompile figures, use draft mode, or move to a Premium or institutional plan.
* '''Pushing from both sides at once:''' If Overleaf has unpushed edits and GitHub has new figures, Overleaf has to merge them. Push from Overleaf first, pull locally, then push your figures.
* '''Wrong main document:''' If you upload a project with several <code>.tex</code> files, Overleaf may guess the wrong one. Set it explicitly under '''Menu → Main document'''.
* '''Bloating the paper repository:''' PNGs and timestamped PDFs change on every run. Prefer vector PDFs with the timestamp removed, and only commit figures that actually changed.
* '''Editing the same paragraph at once:''' Simultaneous editing works, but two people rewriting the same sentence will step on each other. Split up sections, or use comments to coordinate.
* '''Overleaf project limits:''' Overleaf limits project size and file counts. Keep raw outputs, checkpoints, and intermediate data in the experiment repository (or out of Git entirely); only put paper-ready figures and tables in <code>paper/</code>.
* '''Ignoring warnings:''' Overleaf will happily show a PDF with undefined references and overfull boxes. Check the logs pane before you submit.
* '''Working on branches:''' Overleaf only syncs one branch. Stick to the default branch inside <code>paper/</code>; anything on another branch won't show up in Overleaf.
* '''Treating Overleaf as your only backup:''' Download the source periodically, or use Git sync, especially before deadlines.
* '''Oversized uploads:''' Projects have size and file-count limits. Keep raw data, high-resolution PNGs, and intermediate outputs out of the project; only include paper-ready figures.
|}
|}


<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
'''Note:''' This is just one of several ways to connect your code and your paper. If the manual pull button bothers you, try the Git integration variation above; if you want airtight provenance, a submodule may be worth the extra commits.
'''Note:''' Overleaf is a writing tool, not a research workflow by itself. Once you're comfortable with the basics, see [[Overleaf_GitHub_Sync|Syncing Experiment Code with Overleaf via GitHub]] for a way to keep your figures and tables in sync with your code. <!-- TODO: fix this link to match the actual title of the GitHub sync article -->
</div>
</div>

Revision as of 23:00, 18 October 2026


Overleaf is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.

If you already know LaTeX, there is very little to learn: you write the same .tex and .bib files you would write locally, and Overleaf runs the compiler for you. What Overleaf adds is everything around the LaTeX: shared editing, comments, change tracking, version history, and a single place where every co-author sees the same compiled PDF.

New to Overleaf?
The quickest way in is the video introduction to Overleaf, which walks through the editor, compiling, and sharing in a few minutes. For anything this article doesn't cover, the Overleaf help site has documentation on the editor as well as a large collection of general LaTeX guides.

How It Works

An Overleaf project is a folder of files (your .tex sources, bibliography, figures, style files) stored on Overleaf's servers. When you click Recompile, Overleaf runs the project through latexmk on its own TeX Live installation and shows you the resulting PDF next to the source. Everyone who has access to the project edits the same files at the same time, and changes appear for everyone as they are typed.

Strengths Weaknesses
  • Nothing to Install: A complete, maintained TeX Live distribution is available from any browser, so "it compiles on my machine" stops being a problem.
  • Real-Time Collaboration: Co-authors edit the same document simultaneously, with comments and tracked changes built in.
  • One Source of Truth: There is exactly one copy of the paper, and everyone sees the same compiled PDF.
  • Built-In History: Overleaf records who changed what, and you can restore earlier versions.
  • Templates: Thousands of journal and conference templates are a click away in the template gallery.
  • Compile Limits: Large documents, heavy TikZ/pgfplots figures, or slow packages can hit the compile timeout, especially on the free plan.
  • Online by Default: You need an internet connection to work comfortably, and the browser editor is not your local editor of choice.
  • Premium Paywall: Many useful features (Git/GitHub sync, more collaborators, longer history, reference manager integration) require a paid plan.
  • Not a Code Repository: Overleaf is not a good place for the code and data that produce your figures.
🔗 Overleaf Help and Documentation

Getting Started

Step 1: Create an account

Go to overleaf.com and sign up. If you have a university email address, sign up with it (or add it to an existing account under Account Settings), since that is how Overleaf recognizes institutional licenses.

Important: Check for an institutional license
Many universities pay for Overleaf Premium (often called Overleaf Commons) for their students and staff. Before paying for a plan yourself, check whether your institution provides one; linking your institutional email is usually all it takes to unlock Premium features.

File:Overleaf-account-affiliation.png
Adding an institutional email address to unlock an institutional license.

Step 2: Create or import a project

From the project dashboard, click New Project. You can start from:

  • Blank Project or Example Project for a minimal starting point.
  • Upload Project to upload a .zip of an existing local LaTeX project.
  • Templates to start from a journal or conference template (many venues publish an official one in the gallery).
  • Import from GitHub (Premium) to start from an existing repository.
Options for creating a new project.

Step 3: Get to know the editor

The editor has three main panes: the file tree on the left, the source editor in the middle, and the PDF preview on the right. A few things worth knowing right away:

  • Recompile (or Ctrl/Cmd + Enter) builds the PDF. Auto-compile can be toggled from the dropdown next to the button.
  • Double-clicking in the PDF jumps to the corresponding line of source, and the arrow buttons between the panes jump the other way (SyncTeX).
  • The Code Editor / Visual Editor toggle at the top switches between raw LaTeX and a rich-text-like view. Experienced LaTeX users usually stay in the Code Editor, but co-authors less comfortable with LaTeX may prefer the Visual Editor.
  • The Logs and output files button next to Recompile shows errors and warnings, each with a link to the offending line.
The Overleaf editor: file tree, source, and compiled PDF.

Step 4: Check the project settings

Open Menu (top left) to set the project-wide compile options:

  • Compiler: pdfLaTeX by default; switch to XeLaTeX or LuaLaTeX if you need system fonts or Unicode-heavy input.
  • TeX Live version: new projects use a recent release. Leave older projects on their original version unless you have a reason to upgrade, since package updates can occasionally break a working document.
  • Main document: if your project has several .tex files, make sure the one with \documentclass is selected here. Compiling the wrong file is a common source of confusing errors.
Compiler and main-document settings in the project menu.

Working With Co-Authors

Sharing a project

Click Share in the top right to invite collaborators by email, as either editors or viewers. You can also turn on link sharing, which gives anyone with the link view or edit access; be careful with edit links, since they work for anyone who receives them.

Warning: Collaborator limits
The free plan only allows a small number of collaborators per project. The limit is set by the project owner's plan, so if your co-authors can't be added, the easiest fix is usually to have someone with Premium (or an institutional license) own the project.

Comments and tracked changes

Highlight any text and click the comment button to start a discussion thread in the margin, much like comments in Word or Google Docs. Threads can be replied to and resolved.

Switching the editor from Editing to Reviewing mode turns on track changes: every insertion and deletion is recorded and shown in the margin, where co-authors can accept or reject it. This is the most polite way to edit someone else's section.

Comments and tracked changes in the review panel.

History and versions

Click History to see a timeline of changes, who made them, and a diff of each. You can label a version (e.g. "Submitted to AISTATS") so it is easy to find later, and restore files from earlier points. The free plan only keeps a limited window of history, so label important milestones and don't rely on Overleaf as your only backup.

Browsing project history and labeling a version.

Getting Files In and Out

Overleaf is easy to use on its own, but you will often want to move files between it and your computer.

Manual upload and download (free): The Upload button in the file tree accepts individual files or a whole folder. Menu → Download → Source gives you a .zip of the project, and the download button above the PDF gives you the compiled paper. This is fine for occasional use, but tedious if your figures change often.

Git and GitHub sync (Premium): Every Premium project can be cloned directly with Git, and can also be synchronized with a GitHub repository. This lets you edit locally in your own editor, and lets your analysis code write figures and tables straight into the paper. See Syncing Experiment Code with Overleaf via GitHub for a complete workflow.

Reference managers and Dropbox (Premium): Overleaf can import a .bib file from Zotero or Mendeley and refresh it on demand, and can keep a project synced with a Dropbox folder.

Tips for Experienced LaTeX Users

  • You can configure latexmk: Overleaf builds with latexmk, and you can add a file named latexmkrc to the project root to customize the build (for example, to run extra tools or set environment variables).
  • Clear the cache when things get weird: If errors persist after you've fixed the source, open the logs pane and choose Clear cached files, then recompile. Stale auxiliary files cause most "impossible" errors.
  • Turn off "Stop on first error" carefully: The recompile dropdown lets you compile through errors, as -interaction=nonstopmode would. This is handy for seeing the whole document, but don't let errors accumulate.
  • Draft mode for speed: The recompile dropdown has a Fast [draft] option that skips images, which helps a lot with figure-heavy documents.
  • Precompile heavy figures: Complex TikZ or pgfplots figures are the most common cause of compile timeouts. Compile them separately (or generate them in your analysis code) and include the resulting PDF with \includegraphics.
  • Use the help site for LaTeX questions too: The Overleaf help site doubles as one of the better general-purpose LaTeX references on the web.

Common Pitfalls

Things to Watch Out For
  • Compile timeouts: Large documents and heavy figures can exceed the compile time limit, which is shorter on the free plan. Precompile figures, use draft mode, or move to a Premium or institutional plan.
  • Wrong main document: If you upload a project with several .tex files, Overleaf may guess the wrong one. Set it explicitly under Menu → Main document.
  • Editing the same paragraph at once: Simultaneous editing works, but two people rewriting the same sentence will step on each other. Split up sections, or use comments to coordinate.
  • Ignoring warnings: Overleaf will happily show a PDF with undefined references and overfull boxes. Check the logs pane before you submit.
  • Treating Overleaf as your only backup: Download the source periodically, or use Git sync, especially before deadlines.
  • Oversized uploads: Projects have size and file-count limits. Keep raw data, high-resolution PNGs, and intermediate outputs out of the project; only include paper-ready figures.

Note: Overleaf is a writing tool, not a research workflow by itself. Once you're comfortable with the basics, see Syncing Experiment Code with Overleaf via GitHub for a way to keep your figures and tables in sync with your code.

Retrieved from "https://info.stat.cmu.edu/index.php?title=Overleaf&oldid=985"