Template repository for a LaTeX writing project

This repo contains a LaTeX writing project. Documents are automatically compiled upon each new commit and PDFs are served via a GitHub Pages site. After setting up GitHub Pages (see below), your documents will be built and served at https://<user/org>.github.io/<repo>/.

Contents

Writing

• TeX source: main.tex
• Bibtex references: references.bib
• Figure directory: figures/

Note

There's no need to commit compiled PDF files from your local build. PDF files in the root directory are ignored by git.

Configuration

• _config.yml: optionally specify which documents to serve on GitHub Pages. By default, all .tex files in the repository root will be compiled and linked on the index page. Override this like so (note: no .pdf or .tex extension):

  document_links:
    - main
    - supplementary

• latexmkrc: optional customization of TeX build directives (see latexmk docs).

Enable GitHub Pages

To enable GitHub Pages for a new repository using this template:

1. Go to the repository settings
2. Navigate to "Pages"
3. Select "GitHub Actions" as the source
4. Back on the main repository page, click the gear icon ⚙️ on the right to edit the "About" section and check the box for "Use your GitHub Pages website".

Dependencies

• TeX Live

Local PDF compilation with latexmk

Build

Build with

latexmk -pdf

Clean

Auxiliary build files will be ignored by git, but you can clean them locally with

latexmk -pdf -c

Helpful writing conventions

Semantic line breaks

While writing TeX source files, add a line break after each sentence (or clause). This makes editing and collaborating on the text much easier, and it makes git diffs much more readable. For more on this, see https://sembr.org.

Initialed source comments

A low-key way to add comments or questions on the text is to put comments in the TeX source with your initials. This doesn't clutter up the compiled PDF. For example:

% WSD: I don't understand the sentence below
A confusing sentence