Getting started with LaTex as a Dev

About LaTeX

LaTeX is a typesetting system that allows the user to write plain text, while the formatting is provided via markup tags, similar to HTML. It differs from WYSIWYG (What You See Is What You Get) applications like Word in that the final document must first be generated by a compiler. While the output of a LaTeX document is reproducible, minimal and just beautiful, it can be a challenge to get started for beginners. To get started users need to choose one of the multiple existing LaTeX distributions, choose an editor and setup a script to automatically build the document and preview it.

This article will automate and abstract most of the pain points and will let you focus on the content - like it is supposed by LaTeX.

Functions

The setup provided by this article you will have the following features:

• A quick, clean, working LaTeX environment setup based on TeXLive
• Pandoc - To convert your projects between different formats
• Have LaTeX Workshop an LaTeX Utilities preinstalled
• GUI for math symbols and some TiKz
• BibTeX support
• Spell checking
• Markdown support
• Git support
• Scientific project template
• Have our environment on a remote computer
• A platform independent setup that can be used on any OS (Win/Unix/macOS)
• Have a setup that is faster than MiKTeX on Windows
• Support for x86/arm/arm64 architectures
• Persistent bash_history

Pre-Requirements

This is a getting-started guide focused on developers. Therefore, it will use tools common in the software developing world. Nevertheless, everyone can follow this guide to create a quick latex environment.

The following tools are needed for this guide:

VSCodoe

VSCode is a cross-platform text editor designed for fast coding developed by Microsoft. It is heavily extendable with various extensions provided by a large community. It can be downloaded here

Docker

Docker is a universal container runtime that allows users to run various software in a predefined environment isolated from the actual host system. Depending on your system you need one of the following:

Note: Docker builds upon functions provided by the Linux kernel. Windows and macOS need to virtualize the kernel. Therefore, the best performance is achievable on Linux.

Getting started

To get started you have two options: Having the source files locally on host drive or in a persistent volume managed by Docker.
If you pan to modify and access your project files with other tools as well I would suggest using the local setup. For slightly better disk performance or if you just want to use VSCode to edit your document you can also use a persistent volume managed by Docker.

Local setup

The TeX source is on your host OS and gets mounted as volume

# Open a terminal an type:
git clone https://github.com/hegerdes/VSCode-LaTeX-Container
code VSCode-LaTeX-Container
# In VSCode hit F1
> Remote-Containers: Reopen in Container
# Wait for the initial pull and build
# Note: You need to have Docker and VSCode remote extentions installed
# Search for "ms-vscode-remote.vscode-remote-extensionpack"

In a container

The entire project is within the container

# Open VSCode
# In VSCode hit F1
> Remote-Containers: Clone Repository in Container Volume
> https://github.com/hegerdes/VSCode-LaTeX-Container
# Wait for the initial pull and build
# Note: You need to have Docker and VSCode remote extentions installed
# Search for "ms-vscode-remote.vscode-remote-extensionpack"

👉 Start typing you next big article!

Some background:

The LaTeX template

The included template was build up over the time and is designed for scientific projects. But I didn't start from scratch either. Credit goes to:

% Original author:
% WikiBooks (LaTeX - Title Creation) with modifications by:
% Vel ([email protected])
% hegerdes ([email protected])

About the Docker image

There are multiple base images debian-[bullseye|buster (deprecated)] and ubuntu-[focal|bionic (deprecated)]. All these images have texlive, texlive-latex-extra texlive-lang-english, texlive-luatex, texlive-xetex, texlive-pstricks, texlive-science, latexmk, cm-super, chktex with additional tools like git, zsh and pandoc(not in alpine) installed. Every image is available on x86/arm/arm64 architectures.

The slim images only contain texlive, texlive-latex-extra, texlive-lang-english, latexmk, cm-super, chktex If you want a minimal image use these, but this might lack common tools/packages.

There are two full images that contain everything in the LaTeX world except for docs. These are BIG and generally not recommended for fast startups.

There are a bunch of language specific images that are build up on the bullseye-base and focal-base images. Languages are: all, arabic, chinese, cjk, cyrillic, czechslovak, english, european, french, german, greek, italian, japanese, korean, other, polish, portuguese, spanish.

Use one of these if your work on a none English project! Simply change the VARIANT arg in the devcontainer.json to bullseye-lang-<YOUR_LANGUAGE> or ubuntu-lang-<YOUR_LANGUAGE>.

I plan on updating these images every second month.

VSCode workspace

I added a VSCode workspace file with sensible setting. It includes some settings for Docker and the LaTeX extensions. Feel free to customize it after your own taste.

If you want to see what I did with the template look over to henrikgerdes.me/papers

Why all this

I always liked the concept of LaTeX and its focus on content instead of the formatting. But getting started was hard and I wanted to contribute to make it a little more accessible. I first used MiKTeX and TeXworks, but I found the usage of shortcuts hard and didn't like the PDF viewer. I switched to Notepad++, SumataPDF (both great tools) and a handy script. It was great until my projects got bigger. So I used VSCode and LaTeX Workshop and I loved it. All my shortcuts and tools I used before now applied to LaTeX. I was satisfied until I realized how slow MiKTeX on Windows is compared to Linux.

I love Linux, but some things are more convenient on Windows. I started my Bachelor theses about development environments and the usage of container tools. So I have further developed my setup to bring everything together.

I found that the tianon/latex and other image were outdated and did not meet my expectations. I rather created my own image. It is own the large side, but I rather have all my tools there at any time instead of being slowed down by missing them or have to install packages manually. I hope some of you find some interesting tips and tricks in my setup.

If you find any issues let me know

See you!