Overridding Build Settings

Many of the build settings in the settings page of the latex package can be overridden on a per file basis. One way to override specific build settings is to use "magic" TeX comments in the form of % !TEX <name> = <value>. Another way to override build settings is to use a YAML formatted file with the same name as your root LaTeX file, but with an extension of .yaml. The settings and values that can overridden via either method are listed in the table below. If multiple setting names are listed then the first is preferred and following names are available for compatibility.

Name	Value	Use
cleanPatterns	comma separated patterns, e.g. **/*.blg, foo	Specify patterns to use for latex:clean
enableSynctex	yes, no, true or false	Override SyncTeX setting
enableExtendedBuildMode	yes, no, true or false	Override extended build mode setting
enableShellEscape	yes, no, true or false	Override shell escape setting
engine or program	pdflatex, lualatex, etc.	Override the LaTeX engine to use for build.
moveResultToSourceDirectory	yes, no, true or false	Override move result to source directory setting
outputFormat or format	dvi, ps or pdf	Override the output format
jobNames, jobnames or jobname	comma separated names, e.g. foo, bar	Control the number and names of build jobs. Only a single name can be used for jobname.
outputDirectory or output_directory	directory path, e.g. build	Specify the output directory that should be used.
producer	dvipdf, dvipdfmx, xdvipdfmx or ps2pdf	Override the PDF producer
root	file path, e.g. ../file.tex	Specify the root file that should be built. Only available via "magic" TeX comments.

Examples of TeX Magic Comments

All TeX magic comments should occur before \documentclass and may start with either % !TEX or % !TeX. There should be no space after the exclamation point but the space before the exclamation point is optional.

TeX magic comments are only loaded from the root document with the exception of the root setting. For example, if the following is the contents of bar.tex then only the root setting will be used and the engine setting will be ignored.

% !TEX root = ../foo.tex
% !TEX engine = xelatex
\begin{enum}
  \item wibble
  \item quux
\end{enum}

If the following is the contents of foo.tex then the actual LaTeX engine used will be uplatex and the outputDirectory will be build. The setting outputFormat will be ignored since it occurs after \documentclass. Because of the jobNames setting the build will be run twice with a job name of quux the first time and a job name of name with spaces the second time.

% !TEX engine = uplatex
% !TEX outputDirectory = build
% !TEX jobNames = quux, name with spaces
\documentclass{article}
% !TEX outputFormat = dvi

\begin{document}
\input{wibble/bar.tex}
\end{document}

Examples of YAML Build Settings

In order to accomplish the same overridden settings using a YAML settings file the contents of bar.tex should be the following since the root setting is still needed to identify the root document.

% !TEX root = ../foo.tex
\begin{enum}
  \item wibble
  \item quux
\end{enum}

All magic comments in foo.tex can be removed and instead a file foo.yaml is created with the contents below.

engine: uplatex
outputDirectory: build
jobNames:
- quux
- name with spaces

If TeX magic comments are left in foo.tex then they will be processed before the YAML file is read and processed. In other words, the YAML build settings will take precedence over the TeX magic comments.