General Features
Project Files
Project files are fully supported! You should consult the subsection on project-specific settings for further details.
Multi-file documents
Multi-file documents are supported as follows. If the first line in the current file consists of the text %!TEX root = <master file name>
, then tex & friends are invoked on the specified master file, instead of the current one. Note: the only file that gets saved automatically is the current one. Also, the master file name must have a valid tex extension (i.e., one configured in the tex_file_exts
settings), or it won't be recognized.
As an alternative to using the %!TEX root = <master file name>
syntax, if you use a Sublime project you can set the latextools.tex_root
option (under settings
):
{
... <folder-related settings> ...
"settings": {
"latextools.tex_root": "yourfilename.tex"
}
}
Note that if you specify a relative path as the latextools.tex_root
in the project file, the path is determined relative to the location of the project file itself. It may be less ambiguous to specify an absolute path to the latextools.tex_root
if possible.
Previewing
Preview functions are only available in Sublime Text Build 3118 and newer.
LaTeXTools has the ability to preview images included in the document using a popup or equations as they are typed using phantoms. Both of these functions rely on Ghostscript and ImageMagick being installed and available on your texpath
.
Math-Live preview
While editing equations LaTeXTools will preview the result using phantoms. By default this will only preview the currently edited environment, but you can also preview all math environments by adjusting the appropriate settings. See the documentation on Preview Settings
Preview images
You can preview images included via the \includegraphics
command. By default, when you hover over the name of the image, a popup will appear to show the image. Links are provided to open the image itself or the folder containing the image. It is also possible to show all images at once via phantoms. See the documentation on Preview Settings for details.
Spell-checking
LaTeXTools parses the %!TEX spellcheck
directive to set the language for the spell-checker integrated in Sublime Text. The Dictionaries package is recommended and supported. If you have additional dictionaries, you can add them using the tex_spellcheck_paths
setting, which is a mapping from the locales to the dictionary paths. Each locale must be lowercase and use only a hyphen as a separator. The dictionary paths must be compatible with those used by Sublime Text's spell-checker. For example {"en-us": "Packages/Language - English/en_US.dic"}
would be a valid value. For more on Sublime Text support for spell checking, see the relevant online documentation.
Since the dictionary package is no longer available via Package Control, you can follow these steps to install it:
- Open the command palette (
C-shift-p
) and select the entryPackage Control: Add Repository
- Paste the url:
https://github.com/titoBouzout/Dictionaries
and press enter - Now you can install it as any other package: First select
Package Control: Install Package
in the command panel and afterwards selectDictionaries
to install it
Support for non-.tex
files
LaTeXTools has some degree of support for LaTeX documents that are in files with an extension other than .tex
. In particular, this feature is designed to work well with alternative extensions, such as .ltx
. Other extensions such as .Rnw
and .tikz
are supported, but, for now they will be treated as standard LaTeX documents (patches are always welcome!).
This behaviour is controlled through two settings, tex_file_exts
and latextools_set_syntax
. For more on these settings, see the documentation on General Settings.
Note that while the extension detection is used by features of LaTeXTools, including, other features---especially the completions---depend on the syntax of the file being set to LaTeX
as well.
Package Documentation
You can consult the documentation for any LaTeX package by invoking the View Package Documentation
command via the Command Palette (for now). This relies on your system's texdoc
command.
Support for Editing Bibliographies
LaTeXTools has some enhanced support for editing either BibTeX or BibLaTeX .bib
files. Snippet completions are provided for every entry type supported by either BibTeX or BibLaTeX, as are completions for field names. In addition, LaTeXTools provides smart completions for name fields (such as author
, editor
, etc.) and crossrefs. When auto-completions are triggered in a name field, a list of all entered names in the current file is presented. Similarly, when auto-completions are triggered in a crossref field, a list of all current entry keys will be provided.
This behaviour is controlled by a single setting, use_biblatex
(default: false
), which indicates whether LaTeXTools should use the BibTeX versions of the auto-completions (this is the default behavior) or the BibLaTeX versions of the auto-completions (if use_biblatex
is set to true
).
Caching
LaTeXTools uses a cache to store relevant information about your document and improve the performance of commands. By default, we try to keep them invisible, so they are stored in the Sublime cache path. Settings relevant to the cache can be found in the settings section
Builder Features
Most of the builder features are controlled through the LaTeXTools.sublime-settings
file. See, in particular, the section on builder settings.
Default Builder
The default builder (called the traditional
builder) supports several additional features.
TeX Engine Selection
If the first line of the current file consists of the text %!TEX program = <program>
, where program
is pdflatex
, lualatex
or xelatex
, the corresponding engine is selected. If no such directive is specified, pdflatex
is the default. Multi-file documents are supported: the directive must be in the root (i.e. master) file. Also, for compatibility with TeXshop, you can use TS-program
instead of program
.
Note: for this to work, you must not customize the command
option in LaTeXTools.sublime-settings
. If you do, you will not get this functionality. Finally, if you use project files, the program
builder setting can also be customized there, under settings
.
TeX Options
You can pass command-line options to your engine in two ways (thanks Ian Bacher!). One is to use a %!TEX options = ...
line at the top of your file. The other is to use the options
builder setting in your settings file. This can be useful, for instance, if you need to allow shell escape. Finally, if you use project files, the options
builder setting can also be customized there (again, under settings
).
Output Directory and Auxiliary Directory
The --output-directory
and --aux-directory
flags can be set in several ways:
* Using a TEX directive, such as %!TEX output_directory = <path>
near the top of the file.
* Using the TeX Options feature to set --output-directory
and / or --aux-directory
.
* Using the corresponding output_directory
and aux_directory
settings detailed in the settings section.
There are three special values that can be used, <<temp>>
<<project>>
and <<cache>>
. Their meaning is the same as that found in the settings section and they are described there.
Note: the --aux-directory
flag is only implemented by MiKTeX, so the corresponding settings will only be valid if you are using MiKTeX, as indicated by your distro
setting. To get similar behavior on TeXLive / MacTeX, you can use the copy_output_on_build
setting described in the settings section with any of the output_directory
settings. This will run pdflatex
/ xelatex
/ lualatex
with the --output-directory
flag and then copy the resulting PDF to the same directory as your main TeX document.
Note: These flags can only be set when using latexmk
(i.e., the traditional
builder on OS X and Linux), the basic
builder or the script
builder (see below for documentation on using the script builder). If you are using texify
(i.e. the traditional
builder on MiKTeX) or the simple builder, the output_directory
and aux_directory
settings will be ignored.
Jobname
The --jobname
flag can be set in several ways:
* Using a TEX directive, such as %!TEX jobname = <jobname>
near the top of the file.
* Using the TeX Options feature to set --jobname
* Using the corresponding jobname
setting detailed in the settings section.
Note: Jobname can only be set when using latexmk
(i.e., the traditional
builder on OS X and Linux), the basic
builder or the script
builder (see below for documentation on using the script builder). If you are using texify
(i.e. the traditional
builder on MiKTeX) or the simple builder, the jobname
setting wil be ignored.
Customizing the compilation command
It is possible to customize the command run by setting the command
option under Builder Settings. See the section on Builder Settings for details.
Note: If you customize the command, the TeX engine selection facility may no longer work because it relies on a specific compilation command. However, if you want to customize or replace latexmk
/texify
, you probably know how to select the right TeX engine, so this shouldn't be a concern. Also note that if you are using latexmk
and you set the $pdflatex
variable, the TeX options facility will not function, as latexmk
does not support this.
If you change the compilation command, you are responsible for making it work on your setup. Only customize the compilation command if you know what you're doing.
Other Builders
If the default builder doesn't meet your needs for any reason, please see the page on available builders.
Viewers
By default, LaTeXTools supports the following viewers, depending on platform:
- On OS X, Skim
- On Windows, Sumatra
- On Linux, Evince
However, it is possible to use other programs to view PDF files. Currently, there are viewers available for Preview.app, Okular and Zathura. These viewers can be chosen by changing the "viewer"
setting. See the Viewer Settings section for details. If you are using an alternate viewer, please see the relevant section under Available Viewers for any caveats or other instructions. In addition, there is a viewer, called the Command Viewer which can be used to launch a PDF document using the command line.