Overleaf integration
Contents
Overleaf integration#
Warning
Overleaf integration is still an experimental feature. The user interface may change in future releases. If you run into problems or have any suggestions to improve this functionality, please open an issue on GitHub.
Overview#
showyourwork! now allows users to integrate their projects with Overleaf, which can greatly facilitate collaborative article writing in LaTeX. While Overleaf supports integration with git and GitHub in a few different ways, none of these are quite right for an Overleaf-showyourwork! bridge (you can read all about why here).
Instead, whenever showyourwork
is executed (either locally or on GitHub Actions),
a specific set of files is synced between the git repository and the Overleaf project.
The user can choose which files get synced, but the default is to push figure output
to Overleaf and pull TeX files from Overleaf.
In order to prevent merge conflicts and data loss, syncing only happens in one direction:
by default,
figures only ever get pushed to Overleaf, while TeX files only ever get pulled from
Overleaf to the git repository.
This means that if users wish to integrate their project with Overleaf, they must only
make changes to the TeX file(s) on Overleaf. Similarly, users should not manually change/edit/upload
figures to Overleaf, and instead let showyourwork! do the grunt work.
In the event of a merge conflict—for example, if the user edited ms.tex
locally—the
showyourwork! build will acknowledge that and fail, refusing to overwrite
the local changes. See Managing conflicts below for details.
Below, we’ll discuss how to set up the integration with Overleaf and take a look at how to configure the syncing.
Setup#
Let’s set up Overleaf integration for a new repository. It is much, much, much easier to set up Overleaf integration for new projects, so here we’ll create both a new GitHub repository and a new Overleaf project for our article. If you want to set up Overleaf integration for an existing project, see Integrating existing projects.
To start, create a new repository on GitHub by visiting github.com/new.
For definiteness,
in the example below we’ll create the repository article
under my user
name (rodluger
).
Next, create a new project on Overleaf from the Blank Project template. You’ll be directed to the new project, whose URL will look something like
https://www.overleaf.com/project/6272c02ffe09ce2c9a5f0ff6
That last bit of the URL (6272c02ffe09ce2c9a5f0ff6
) is the 24-character
project ID, which uniquely identifies your project; we’ll use that in just
a moment. On your project page, you should see a single file called main.tex
containing some minimal TeX stuff. Don’t edit anything in it, as it will get
overwritten momentarily by showyourwork!.
Next, on your machine, define the environment variables $OVERLEAF_EMAIL
and $OVERLEAF_PASSWORD
with your Overleaf credentials. Unfortunately,
Overleaf does not yet support token-based authentication, so the only way
to grant showyourwork! access to your project is by providing the email
and password for your Overleaf account. As with the other credentials required
by showyourwork!, you’ll also need to create corresponding
GitHub Actions secrets at the following URL
https://github.com/rodluger/article/settings/secrets/actions/new
where you should replace rodluger/article
with your GitHub username
and the name of the repository.
Warning
Never commit your Overleaf credentials (or any credentials) directly to your repository!
Finally, on your local machine, set up a new showyourwork! repository by running
showyourwork setup rodluger/article --overleaf=6272c02ffe09ce2c9a5f0ff6
where, again, you should replace rodluger/article
with your repository slug
and 6272c02ffe09ce2c9a5f0ff6
with your Overleaf project ID. You should see
a couple messages saying the Overleaf repository is being set up. Once that’s
done, if you navigate to your Overleaf project in the browser, you’ll see that
the single TeX file main.tex
is gone and has been replaced by the following
files:
- figures
- .gitignore
- .gitignore
- bib.bib
- ms.tex
- showyourwork.sty
These, in fact, are the same files as in the src/tex
folder of your repository
(see Repository layout); showyourwork! will keep your Overleaf project up to date
with the contents of that folder (more on this below).
Note that the TeX manuscript is now called
ms.tex
(the default name in showyourwork!).
Returning to our local showyourwork! repository, if you open the config file
showyourwork.yml
, you’ll see that the setup
command populated the
overleaf
field with some stuff:
overleaf:
id: 6272c02ffe09ce2c9a5f0ff6
push:
- src/tex/figures
pull:
- src/tex/ms.tex
- src/tex/bib.bib
In addition to your Overleaf project ID, it has also defined some files and folders
in the push
and pull
fields. To understand what these mean, read on!
Pushing and pulling#
Coming soon! Only enabled for the main
branch.
Managing conflicts#
Coming soon!
Integrating existing projects#
Coming soon!