VS code LaTeX template project

$Docker Image CI$

This repo is meant to be used with VSCode to provide a quick and functional full fleece LeTeX Environment. It can be run as a DevContainer or on the web an ANY device using Codespaces or GitPods.

Functions

With this image you can:

Have a quick, clean, working LaTeX environment setup based on TeXLive
Use Pandoc - To convert your projects between different formats
Use any host OS
Run it on x86/arm/arm64 architectures or the web
Have our environment on a remote computer
If you use Codespaces or GitPod you can even edit your papers on every browser.
Have a setup that is faster than MiKTeX on Windows
Have LaTeX Workshop an LaTeX Utilities preinstalled (VSCode only)
Markdown support (VSCode only)
Spell checking (VSCode only)
Persistent bash_history (VSCode only)
Git support
Customize your image with own users or more tools
Scientific project template (VSCode only)

Getting started

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"

On the web

The entire project is within your Codespace or GitPod:
Click Use this template and then open in Codespace
Alternatively click clone and head over to the Codespace tab.

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"

About the Docker image

Container images are available on DockerHub.

All images are updated every month to the latest package version via CI.
If you need reproducable enviorments use a fixed container image hash as tag.

There are multiple base images debian-[bullseye|bookworm] and ubuntu-[focal|jammy]. 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 bookworm-base and jammy-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 bookworm-lang-<YOUR_LANGUAGE> or jammy-lang-<YOUR_LANGUAGE>.

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 (vel@latextemplates.com)
% hegerdes (hegerdes@outlook.de)

Other nice Tools:

LaTeX-OCR
Detexify
WolframAlpha
ChatGPT - super nice for TIKZ
Inkscape - super for figures

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.

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 software 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

Tips & Tricks

If you use git. Checkout everything with lf line endings

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

On Windows use the WSL2 backend
You can customize your environment by changing the image in the .devcontainer folder
You can add own users by changing the USERNAME and remoteUser in the devcontainer.json
Check out the template with:

# In VSCode hit F1
> Remote-Containers: Clone Repository in Container Volume
> https://github.com/hegerdes/VSCode-LaTeX-Container

Support me

If you like this or other projects may consider supporting me.