Guide to Auto-Update PDF Using latexmk and VSCode

Photo created by creativeart — www.freepik.com

Table of Contents

Introduction
Installing LaTeX
Creating PDF from a terminal using latexmk
Installing LaTeX Workshop Extension to VS Code
Create your own snippets
Testing the snippet
LaTeX Workshop error
Automatically update PDF when you save
Conclusion
Reference

Introduction

I am an occasional LaTeX user. I use Typora for writing articles, reports, notes, and more. But I don’t have full control over the layout with markdown. So I restarted using LaTeX. I’d like to share what learned. This article shows how to set up LaTeX and VS Code so that it will auto-update a PDF when you save a tex file.

Installing LaTeX

This time I installed mactex-no-gui .

Mac:

# macOS MacTex Install
$ brew cask install mactex-no-gui
# Updating the packages
$ sudo tlmgr update --self && sudo tlmgr update --all

Installation was reasonably fast but it took a long time to update.
You may need to restart the terminal and check if works:

$ latex --version
$ latexmk --version
$ platex --version

If it doesn’t work, then you need to add a PATH to your ~/.zshrc or ~/.bash_profile:

export PATH="/Library/TeX/texbin/:$PATH"

Check it again:

$ latex --version
pdfTeX 3.14159265-2.6-1.40.21 (TeX Live 2020)
kpathsea version 6.3.2
...
$ latexmk --version
Latexmk, John Collins, 29 September 2020. Version 4.70b
...
$ platex --version
e-pTeX 3.14159265-p3.8.3-191112-2.6 (utf8.euc) (TeX Live 2020)
kpathsea version 6.3.2
...

Linux installation:

# Arch Linux Family
sudo pacman -S texlive-most
# For Ubuntu, you might need a ppa:
sudo add-apt-repository ppa:jonathonf/texlive
sudo apt update && sudo apt install texlive-full
# Fedora
sudo dnf install texlive-scheme-full

For Windows and other Linux OS please see this page.

Creating PDF from a terminal using latexmk

You often have to run LaTeX more than once. latexmk helps you to avoid this hassle.
Latexmk is a Perl script which you just have to run once and it does everything else for you.

This is how to use latexmk:

$ latexmk -silent text.tex

It will automatically update the PDF file when you save a tex file. We can improve it by modifying the .latexmkrc file in your home directory.

$ touch ~/.latexmkrc

And add the following.

#!/usr/bin/env perl
# LaTeX
$latex = 'latex -synctex=1 -halt-on-error -file-line-error %O %S';
$max_repeat = 5;
# BibTeX
$bibtex = 'pbibtex %O %S';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';
# index
$makeindex = 'mendex %O -o %D %S';
# DVI / PDF
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;
# preview
$pvc_view_file_via_temporary = 0;
if ($^O eq 'linux') {
$dvi_previewer = "xdg-open %S";
$pdf_previewer = "xdg-open %S";
} elsif ($^O eq 'darwin') {
$dvi_previewer = "open %S";
$pdf_previewer = "open %S";
} else {
$dvi_previewer = "start %S";
$pdf_previewer = "start %S";
}
# clean up
$clean_full_ext = "%R.synctex.gz"
  • We use platex and dvipdfmx to convert a tex file to PDF.
  • latexmk -pv text.tex will display a PDF after the build.
  • latexmk -pvc text.tex will update the PDF file when you save the tex file. (You need to click the PDF file to see the update.)
  • You can stop watching for updated files by ctrl+C.

Installing LaTeX Workshop Extension to VS Code

Now let’s move on to VS Code. We can use VS Code for LaTeX editor.

LaTeX Workshop extension for VS Code
VSCode extension LaTeX Workshop. Image by Author

After installing LaTeX Workshop, you will see the TEX icon at the end of the left sidebar.

The LaTeX Workshop extension creates a PDF on saving and you can view PDF in VS Code or a browser. It has formatting, intellisense completions, syntax-highlight, snippets and shortcuts features, and more.

LaTeX Workshop menu items. Image by Author

You can preview PDF by clicking View LaTeX PDF.

Open the settings.json by CMD/CTRL+SHIFT+P.

VS Code CMD/CTRL+SHIFT+P. Image by Author

In the settings.json add the followings:

{
// your other settings
// ...
// ...
// ---------- Language ----------
"[tex]": {
// Enable intellisence/quick suggestions
"editor.suggest.snippetsPreventQuickSuggestions": false,
// Indentation size
"editor.tabSize": 2
},
"[latex]": {
// Enable intellisence/quick suggestions
"editor.suggest.snippetsPreventQuickSuggestions": false,
// Indentation size
"editor.tabSize": 2
},
"[bibtex]": {
// Indentation size
"editor.tabSize": 2
},
// ---------- LaTeX Workshop ----------
// Enable command and environment completion for used package
"latex-workshop.intellisense.package.enabled": true,
// target file when deleting generated file
// Add "* .synctex.gz" to default value
"latex-workshop.latex.clean.fileTypes": [
"*.aux",
"*.bbl",
"*.blg",
"*.idx",
"*.ind",
"*.lof",
"*.lot",
"*.out",
"*.toc",
"*.acn",
"*.acr",
"*.alg",
"*.glg",
"*.glo",
"*.gls",
"*.ist",
"*.fls",
"*.log",
"*.fdb_latexmk",
"*.snm",
"*.nav",
"*.dvi",
"*.synctex.gz"
],
// dump generated files to "out" directory
"latex-workshop.latex.outDir": "out",
// Build recipe
"latex-workshop.latex.recipes": [
{
"name": "latexmk",
"tools": [
"latexmk"
]
},
],
// Parts used in the build recipe
"latex-workshop.latex.tools": [
{
"name": "latexmk",
"command": "latexmk",
"args": [
"-silent",
"-outdir=%OUTDIR%",
"%DOC%"
],
},
],
}

By default, intellisence/quick suggestions will not be triggered inside of a snippet. To enable them set:

"editor.suggest.snippetsPreventQuickSuggestions": false,

Create your own snippets

LaTeX Workshop provides many snippets and shortcuts. You can add your own snippets as well. Click the cog at the left bottom in the VS Code toolbar and select User Snippets.

User Snippets. Image by Author

And select latex.json (LaTeX) from the menu.

Select latex.json. Image by Author

Let’s creates a basic template. This is a sample snippet you can add:

{
"report": {
"prefix": "report",
"body": [
"\\documentclass[${1:a4paper,11pt}]{${2:jsarticle}}",
"",
"",
"% Math",
"\\usepackage{amsmath,amsfonts}",
"\\usepackage{bm}",
"% image",
"\\usepackage[dvipdfmx]{graphicx}",
"\\usepackage[english]{babel}",
"$3",
"",
"\\begin{document}",
"",
"\\title{$4}",
"\\author{$5}",
"\\date{${6:\\today}}",
"\\maketitle",
"",
"",
"$0",
"",
"",
"\\end{document}"
],
"description": "LaTeX Sample Template"
}
}

You can add more than one snippet:

{
"report": {
"prefix": "report",
"body": [
...
"description": "LaTeX Sample Template"
},
"note": {
"prefix": "note",
"body": [
...
"description": "Note format"
},
"exam": {
"prefix": "exam",
"body": [
...
"description": "Exam format"
}
}

Testing the snippet

I found that VScode’s tabstop won’t work with Vim/vscodevim, so if you are using it you need to disable it.

A snippet in action. Image by Author

LaTeX Workshop error

When you save a tex document and if you have the following error you need to install some Perl packages.

LaTeX Workshop error. Image by Author

First install the latest Perl:

# For Mac
$ perl -v
This is perl 5, version 18, subversion 2 (v5.18.2) built for darwin-thread-multi-2level
(with 2 registered patches, see perl -V for more detail)
Copyright 1987-2013, Larry Wall
...
$ brew install perl

Open a new tab or restart your terminal and check the version installed:

$ perl -v
This is perl 5, version 32, subversion 0 (v5.32.0) built for darwin-thread-multi-2level
Copyright 1987-2020, Larry Wall

You have to install the following Perl packages:

$ cpan
cpan[1]>install Log::Log4perl
Running install for module 'Log::Log4perl'
...
cpan[2]>install Log::Dispatch::File
Running install for module 'Log::Dispatch::File'
...
cpan[3]>install YAML::Tiny
Running install for module 'YAML::Tiny'
...
cpan[4]>install File::HomeDir
Running install for module 'File::HomeDir'
...
cpan[5]>install Unicode::GCString
Running install for module 'Unicode::GCString'
...

Automatically update PDF when you save

You can view your PDF by clicking either View in VSCode tab or View in web browser in the LaTeX Workshop menu.

When you update and save the tex file, it will update the PDF file automatically.

LaTeX menu. Image by Author.
PDF will be updated when you save a tex file. Image by Author.

Conclusion

MacTeX is a huge file, but using mactex-no-gui and VS Code allows us to update on saving a tex file.

Now you know how to create a PDF from your terminal using the latexmk. If you prefer GUI to convert LaTeX to PDF, the LaTeX Workshop is a great tool. You can create your own LaTeX snippet in the VSCode.

I hope you found this useful and hopefully this will help your productivity when writing LaTeX documents.

Reference


How to Auto-Update PDF When Working on Latex was originally published in Towards Data Science on Medium, where people are continuing the conversation by highlighting and responding to this story.