Background

Years ago, my mom compiled a collection of poems written by her grandmother into a hard bound book.

I wanted to make these poems more accessible to our extended family and share them with others in the future who might be interested. To that end, I decided to scan the poems, convert them to raw text, and publish them as a pdf and/or epub. The important thing was to get the poems into a general purpose text format so that I can convert them to other formats as needed.

Of course, some level of styling needs to be applied to the raw text to make it more appealing. I considered using markdown (as I do for blogging and other projects), but found its formatting abilities a bit too limited for this purpose.

What is LaTeX?

Enter The LaTeX Project. LaTeX is a free and open source typesetting system (whatever that means) that has been around since the 80's. I like to think of LaTeX as an extensible set of domain-specific tags for producing printed content. Because the LaTeX toolchain is extensible, there are commands (think "tags") for any kind of printed text imaginable and it can output published content in a variety of formats---pdf and epub are the ones I'm targeting.

For instance, a poem can be marked up using the following commands:

\documentclass{article}
\usepackage{fancyhdr} % required by poemscol
\usepackage{poemscol} % required to typeset poems
\begin{document}
\begin{poem}
\poemtitle{The Road Not Taken}
\begin{stanza}
Two roads diverged in a yellow wood, \verseline
And sorry I could not travel both \verseline
And be one traveler, long I stood \verseline
And looked down one as far as I could \end{stanza}
\end{poem}
\end{document}

As you can see, writing LaTeX is more like writing HTML or Markdown than using a WYSIWYG tool like Microsoft Word or Apple Pages. LaTeX is therefore a bit out of reach for the average person. Although a number of LaTeX content creation apps are available, they don't seem to provide a great user experience. Honestly, I'd rather just write the commands in a simple text editor.

Getting started with LaTeX and VS Code

I tried installing different LaTeX "distributions" on my local machine (MikTex, TexLive) but there was a bit of friction in getting the configuration just right. Also, I really wanted to edit my documents in a text editor; Visual Studio Code, specifically.

Fortunately, there is a great plugin for VS Code called TeX Workshop. I started down the path of using TeX Workshop in conjuction with a locally installed version of the LaTeX toolchain. After several attempts to get this work, I found it too much of a hassle and was worried about having LaTeX artifacts strewn about my heretofore clean install of MacOS Big Sur.

Using a LaTeX Docker container with VS Code

I came across several posts that mentioned running LaTeX in a Docker container. Cool!

This would allow me to keep the LaTeX bits isolated from my local machine. Another benefit is that I can use a Docker image that is known to be configured and working out-of-the-box.

So here's how it works. VS Code has the ability to interact with or hand off work raw LaTeX text files to a Docker container that is running the LaTeX compiler. I am using the LaTeX Docker container to compile my source files into a target format---in this case, pdf.

The workflow is like this:

1. Open a plain text file in VS Code and start writing content decorated with LaTeX commands
2. Run the LaTeX compiler to compile your LaTeX file into another format (e.g. pdf)
3. Open the pdf file to ensure it is formatted as expected

Steps 1 and 3 are simple enough. But compiling the LaTeX file is where LaTeX Workshop comes in. Once it is pointed to the Docker container, you simply run the commands provided by LaTex Workshop and it handles the rest. The result is a pdf file generated from the source LaTeX file.