LaTeX Template ✨

A clean and convenient LaTeX template powered by GitHub Actions for automated builds and Nix for dependency management.

Showcase 📸

You can see the compiled versions of the PDFs in the artifacts branch:

Light Version	Dark Version

Usage 📝

You can simply fork this repository and start writing. If you're a student like me and write your assignments in $\LaTeX$, you can create a folder in the project root (e.g., ./MyClass), copy the template:

cp ./Template/template.tex ./MyClass/MyAssignment.tex

Then start writing! Once you commit and push your changes, GitHub Actions will automatically build your project. When the build finishes, you’ll find the generated PDFs either as downloadable artifacts or directly in the artifacts branch.

Why Automated Builds? ⚙️

I often revisit my assignments or notes from my phone or another device. With this setup, every change triggers a GitHub Actions workflow that compiles my LaTeX files and pushes the results to the artifacts branch. This means I always have an up-to-date PDF available---anywhere, anytime.

Why Nix? ❄️

As a NixOS user, I rely heavily on the Nix package manager, and it handles LaTeX dependencies beautifully. It also gives me full control over which packages my project uses, making debugging or extending my setup much easier.

Themes 🎨

This template supports custom themes! Check out ./Modules/theme.tex. You can define your own color scheme there.

In ./Modules/preamble.tex, LaTeX checks the TBOX_THEME environment variable or any theme you manually override in your document via:

\newcommand{\theme}{DarkTheme}

(See Example Dark Version.tex for a usage example.)

Build commands:

nix build .#dark-theme-documents
nix build .#light-theme-documents
nix build .     # builds default (LightTheme)

Note

Changing the default theme: Edit your flake.nix and update: tbox_theme = "LightTheme"; to tbox_theme = "DarkTheme";

Adding New Fonts 🔤

To include additional fonts, open your flake.nix and locate:

os_font_dir = with pkgs; "";

Suppose you want to use Fira Code. Find it on NixOS Search. Its package is fira-code, and its fonts live under $out/share/fonts/truetype. Update the line to:

os_font_dir = with pkgs; "${fira-code}/share/fonts/truetype";

Then, in ./Modules/fonts.tex, declare it via fontspec:

\newfontfamily{\firacode}{FiraCode-VF}[
    Extension=.ttf,
    Ligatures=TeX,
    Scale=0.9
]

Now you can use it like:

\begin{myenvironment}
{
    \firacode
    This is my code with Fira Code!
}
\end{myenvironment}

Local fonts also work---just ensure they’re included in your $OSFONTDIR and loaded with fontspec.

Adding New Packages 📦

If a package exists in TeXLive, simply find it on NixOS Search and add it to your flake:

tex = pkgs.texlive.combine {
  inherit (pkgs.texlive) scheme-medium latexmk ... my-awesome-package;
};

What If a Package Isn’t in TeXLive? 🤔

Use the ./packages folder (feel free to rename it, e.g., ./styles) and drop any .sty files there.

If you have additional directories elsewhere, you can manually extend $TEXINPUTS (see flake.nix). By default:

TEXINPUTS=./packages

So anything in that folder will be picked up automatically.

How I Use It 🚀

Check out an example note in ./Example/Example.tex and its compiled version here.

My LaTeX workflow:

• IDE/PDE: Neovim
• PDF Viewer: Zathura
• LSP: TexLab
• Main LaTeX Plugin: VimTex
• Snippets: LuaSnip

My dotfiles are private (they... need work :D), but these folks have excellent setups and guides:

• ejmastnak
• seniormars

In particular, A guide to supercharged mathematical typesetting is outstanding.

Building Files Locally 🔄

Just run:

nix build

Your PDFs will appear in ./result/out (which is .gitignored).

Development Environment 🛠️

Start a development shell with:

nix develop

If you use direnv:

direnv allow

You’ll then automatically enter the devshell whenever you cd into this project.

Quick Note on Formatting ✍️

The root folder includes an indentconfig.yaml for latexindent. Use it like:

latexindent --local ./indentconfig.yaml -wd ./Template/template.tex -c /tmp

If you use TexLab, you can configure it to use this file:

require('lspconfig').texlab.setup {
    on_attach = on_attach,
    capabilities = capabilities,
    filetypes = { "tex", "plaintex", "bib" },
    cmd = { "texlab", "-vvvv" },
    settings = {
        texlab = {
            latexindent = {
                ['local'] = vim.fn.getcwd() .. '/indentconfig.yaml',
            }
        }
    }
}

You can customize your indentconfig.yaml that fits your needs the best. Check out their documentation. It is very detailed.

Features 🔥

• Dependency management using Nix
• Automated builds using GitHub Actions
  • Automatically generated table of contents as your README in artifacts branch (see artifacts branch as an example).
  • Downloadable artifacts
• Caching for faster builds using Cachix

References 🔗

• GitHub Actions
  • git-publish-subdir-action
  • install-nix-action
• Nix
• Nixpkgs
• Cachix
• ejmastnak
• seniormars
• latexindent.pl

Reading List 📚

• Exploring Nix Flakes: Build LaTeX Documents Reproducibly
• A guide to supercharged mathematical typesetting