Settings
LaTeXTools supports user-defined settings. The settings file is called LaTeXTools.sublime-settings
. A default version resides in the LaTeXTools plugin directory and must not be edited (any edits you make to this file will be overwritten when the package is upgraded). This contains default settings that will work in many cases for standard configurations of TeX distros and PDF viewers.
You can however create another settings file in your User
directory which can override any of the default settings. You can create and edit such a file manually. However, the simplest way to create a settings file is to open the Preferences | Package Settings | LaTeXTools submenu and select the Settings - User option. If you do not currently have a LaTeXTools.sublime-settings
settings file in your User
directory (e.g., if you are installing LaTeXTools for the first time), you will be given the option to create one. The newly created settings file can be an exact copy of the default one, and will open in a tab for you to customize.
If you do already have an existing LaTeXTools.sublime-settings
file in your User
directory, the Settings - User option will open that file in a tab for you to further customize. Similarly, the Settings - Default option will open the default settings file in a tab, in read-only mode. This may be useful for you to copy from, or if you want to see what other options may be available without consulting this README file.
If at any time you wish to erase your customizations and start afresh, you can simply delete the LaTeXTools.sublime-settings
file in your User
directory. (Again, warning: do not touch the settings file in the LaTeXTools plugin directory!) Alternatively, from the Preferences | Package Settings | LaTeXTools submenu, or from the Command Palette, you can choose Reset user settings to default. This will delete any existing settings file in User
and create a copy of the default one. This will remove all your customizations. (Historical note: This is no longer relevant in 2016, but just for the record, if you have a pre-2014, old-style settings file, this option will migrate it).
Warning: in general, tweaking options can cause breakage. For instance, if on Linux you change the default python
setting (empty by default) to a non-existent binary, forward and inverse search will stop working. With great power comes great responsibility! If you think you have found a bug, delete your settings file in the User
directory, or use the Reset user settings to default command before reporting it! Thanks :-)
General Settings
cite_auto_trigger
(true
): iftrue
, typing e.g.\cite{
brings up the citation completion quick panel, without the need to typeC-l,x
. Iffalse
, you must explicitly typeC-l,x
.ref_auto_trigger
(true
): ditto, but for\ref{
and similar reference commandsfill_auto_trigger
(true
): ditto, but for package and file inclusion commands (see Fill Helper feature above)env_auto_trigger
(true
): ditto, but for environment completionsglossary_auto_trigger
(true
): ditto, but for glossary completionstex_directive_auto_trigger
(true
): ditto, but for tex directive completionscwl_autoload
(true
): whether to load cwl completions based on packages (see the LaTeX-cwl feature)cwl_completion
(prefixed
): when to activate the cwl completion poput (see LaTeX-cwl feature above)cwl_list
(["latex-document.cwl", "tex.cwl", "latex-dev", "latex-209.cwl", "latex-l2tabu.cwl", "latex-mathsymbols.cwl"]
): list of cwl files to loadkeep_focus
(true
): iftrue
, after compiling a tex file, ST retains the focus; iffalse
, the PDF viewer gets the focus. Also note that you can temporarily toggle this behavior withC-l,t,f
.This can also be overridden via a key-binding by passing akeep_focus
argument tolatextools_jump_to_pdf
. Note: In general,keep_focus
set totrue
tries to mean "do not change the focus". This isn't always possible, since several of the viewers will steal focus by default. In those circumstances, LaTeXTools tries to actively return the focus to Sublime. To disable this, set thedisable_focus_hack
setting totrue
. Note: If you are on either Windows or Linux you may need to adjust thesublime_executable
setting for this to work properly. See the Platform settings below.forward_sync
(true
): iftrue
, after compiling a tex file, the PDF viewer is asked to sync to the position corresponding to the current cursor location in ST. You can also temporarily toggle this behavior withC-l,t,s
. This can also be overridden via a key-binding by passing aforward_sync
argument tolatextools_jump_to_pdf
.tex_file_exts
(['.tex']
): a list of extensions that should be considered TeX documents. Any extensions in this list will be treated exactly the same as.tex
files. See the section on Support for non-.tex
files.latextools_set_syntax
(true
): iftrue
LaTeXTools will automatically set the syntax toLaTeX
when opening or saving any file with an extension in thetex_file_exts
list.overwrite_goto_overlay
(true
): Set this tofalse
to disable the overwriting of the goto overlay for the hotkeyC-r
andC-shift-r
You can still access the "table of content quickpanel" viaC-l, C-r
and `C-shift-l, C-renable_smart_paste
(true
) if smart paste is enabled LaTeXTools will overwrite the C-v command and analyze the clipboard content to check whether it should execute an action. So you can just paste image urls or paths into Sublime Text and it will automatically download the image and create a figure environment.use_biblatex
: (false
): iftrue
LaTeXTools will use BibLaTeX defaults for editing.bib
files. Iffalse
, LaTeXTools will use BibTeX defaults. See the section on Support for Editing Bibliographies for details.tex_spellcheck_paths
({}
): A mapping from the locales to the paths of the dictionaries. See the section Spell-checking.word_count_sub_level
("none"
): controls the level at which subcounts of words can be generated. Valid values are:"none"
,"part"
,"chapter"
, and"section"
.temp_files_exts
: list of file extensions to be considered temporary, and hence deleted using theC-l, backspace
command.temp_files_ignored_folders
: subdirectories to skip when deleting temp files.
Preview Settings
Math-Live Preview Settings
preview_math_mode
("selected"
): The mode to preview math environments, possible values are:"all"
: to show a phantom for each math environment"selected"
: to show a phantom only for the currently selected math environment"none"
: to disable math live previewpreview_math_latex_compile_program
("pdflatex"
): The program to compile the latex template files, possible values are"pdflatex"
,"xelatex"
,"lualatex"
,"latex"
.preview_math_color
(""
): The color of the text in the preview math phantoms. The format can either be RGB based "#RRGGBB" (e.g."#FFFF00"
) or a color name (e.g."yellow"
) If it is the empty string""
it will be guessed based in the color scheme.preview_math_background_color
(""
): The background color of the preview math phantoms. In contrast to the foreground color you may also edit your colorscheme to change this. The format can either be RGB(A) based"#RRGGBB"
(e.g."#0000FF"
or"#0000FF50"
) or a color name (e.g."blue"
). If it is the empty string""
the default color will be used.preview_math_template_packages
: An array containing the used packages for the template as latex code.preview_math_template_preamble
(""
): An string of the remaining preamble (not packages) for the file, which generates the math live preview. Can also be an array, with an string for each line (as in the packages). This is useful, if you define math commands or operators on your own. You may change this per project basis.preview_math_density
(300
): The density of the preview image. The higher the density the larger the phantom.preview_math_scale_quotient
(2
): If the image is not sharp enough increase this scale to get a better resolution. However also change the density by the same factor to keep the size.
Preview Image Settings
- "preview_image_mode": (
"hover"
), The preview mode for image preview, possible values are: "all"
: to show a phantom for each\includegraphics
command"selected"
: to show a phantom only for the currently selected\includegraphics
command"hover"
: to show a popup if you hover over an\includegraphics
command"none"
: to disable image previewpreview_popup_image_size
(200
) andpreview_phantom_image_size
(150
): The image size in the preview image popup and phantoms. These are the outer dimensions of the maximal size. The image will be scaled down to fit into these dimensions. It can either be an number or an array, which consist of two numbers (x and y), e.g. [200, 150].preview_image_scale_quotient
(1
): Increase this number to get a better resolution on high dpi displays. Control the thumbnail image size, which will be generated to preview images, that are not natively supported (like pdf files). E.g. a image size of 300 with a scale quotient of 2 will create a thumbnail with the size 600, which is scaled down in the popup.
Platform-Specific Settings
This section refers to setting that can be found in a platform-specific block for each platform, i.e., "osx"
, "windows"
, or "linux"
.
All Platforms
texpath
(varies): the path to TeX & friends. Note that this should always include$PATH
to ensure the default path is loaded as well.
Windows
distro
(miktex
): eithermiktex
ortexlive
, depending on your TeX distributionsumatra
(""
): leave blank or omit if the SumatraPDF executable is in yourPATH
and is calledSumatraPDF.exe
, as in a default installation; otherwise, specify the full path and file name of the SumatraPDF executable.sublime_executable
(""
): this is used ifkeep_focus
is set to true and the path to your sublime_text executable cannot be discovered automatically. It should point to the full path to your executablesublime_text.exe
.keep_focus_delay
(0.5
): this is used ifkeep_focus
is set to true. It controls how long (in seconds) the delay is between the completion of thelatextools_jump_to_pdf
command and the attempt to refocus on Sublime Text. This may need to be adjusted depending on your machine or configuration.
Linux
python
(""
, i.e. empty string): name of the Python executable. This is useful if you've installed Python in a non-standard location or want to ensure that LaTeXTools uses a particular Python version. Note that the Python interpreter you select must have the DBus bindings installed.sublime
(sublime-text
): name of the ST executable. Ubuntu supports bothsublime-text
andsubl
; other distros may vary.sync_wait
(1.0): when you ask LaTeXTools to do a forward search, and the PDF file is not yet open (for example, right after compiling a tex file for the first time), LaTeXTools first launches evince, then waits a bit for it to come up, and then it performs the forward search. This parameter controls how long LaTeXTools should wait. If you notice that your machine opens the PDF, then sits there doing nothing, and finally performs the search, you can decrease this value to 1.0 or 0.5; if instead the PDF file comes up but the forward search does not seem to happen, increase it to 2.0.sublime_executable
: this is used ifkeep_focus
is set to true and the path to your sublime_text executable cannot be discovered automatically. It should point to the full path to your executablesublime_text
.keep_focus_delay
: this is used ifkeep_focus
is set to true. It controls how long (in seconds) the delay is between the completion of thelatextools_jump_to_pdf
command and the attempt to refocus on Sublime Text. This may need to be adjusted depending on your machine or configuration.
Output Directory Settings
aux_directory
(""
): specifies the auxiliary directory to store any auxiliary files generated during a LaTeX build. Note that the auxiliary directory option is only useful if you are using MiKTeX. Path can be specified using either an absolute path or a relative path. Ifaux_directory
is set from the project file, a relative path will be interpreted as relative to the project file. If it is set in the settings file, it will be interpreted relative to the main tex file. In addition, the following special values are honored:<<temp>>
: uses a temporary directory in the system temp directory instead of a specified path; this directory will be unique to each main file, but does not persist across restarts.<<cache>>
: uses the ST cache directory (or a suitable directory on ST2) to store the output files; unlike the<<temp>>
option, this directory can persist across restarts.<<project>>
: uses a sub-directory in the same folder as the main tex file with what should be a unique name; note, this is probably not all that useful and you're better off using one of the other two options or a named relative pathoutput_directory
(""
): specifies the output directory to store any file generated during a LaTeX build. Path can be specified using either an absolute path or a relative path. Ifoutput_directory
is set from the project file, a relative path will be interpreted as relative to the project file. If it is set in the settings file, it will be interpreted relative to the main tex file. In addition, output_directory honors the same special values asauxiliary_directory
.jobname
(""
): specifies the jobname to use for the build, corresponding to the pdflatex--jobname
argument.copy_output_on_build
(true
): iftrue
and you are using anoutput_directory
, either set via the setting or the%!TEX
directive, this instructs LaTeXTools to copy to resulting pdf to the same folder as the main tex file. If you are not usingoutput_directory
or it is set tofalse
, it does nothing. If it is a list of extensions, it will copy each file with the same name as your main tex file and the given extension to the same folder as your main tex file. This is useful for copying, e.g., .synctex.gz or .log files.
Builder Settings
Note: Since the build system is meant to be fully customizable, if you use a third-party builder (which hopefully will become available!), you need to refer to its documentation.
builder
("traditional"
): the builder you want to use. Possible values:"default"
or""
or"traditional"
: this is the standard LaTeXTools builder, which builds the document usingtexify
on MiKTeX orlatexmk
on TeXLive or MacTeX. The majority of the documentation is written assuming you are using this builder."basic"
: invokespdflatex
/xelatex
/lualatex
to build the document. If the log indicates it is necessary, it then runsbiber
orbibtex
and then two additional runs ofpdflatex
/xelatex
/lualatex
. Mostly supports the same features as thetraditional
builder."script"
: invokes the set of commands specified in the"script_commands"
setting in the platform-specific part of the"builder_settings"
. See the documentation for details."simple"
: invokespdflatex
1x or 2x as needed, thenbibtex
andpdflatex
again if needed; intended mainly as a simple example for people writing their own build engines.- Other values can be used to indicate the use of a custom build system. Note that custom builder cannot have the same name as a built-in engine. For an overview of how to write a custom builder, see the custom builder section of the documentation
builder_path
(""
): if not empty, specifies a path to a custom builder, relative to the Sublime Packages directory. For instance,User/builders
could be used to indicate that the custom builder is to be found in thebuilder
subdirectory of theUser
package. This is only needed if you are using a third-party or custom builder.builder-settings
: this contains builder-specific settings.display_log
(false
): iftrue
the output of each command will be displayed in the output panel. This can be useful for troubleshooting issues with the build system and is supported by all built-in build systems. *env
(unset): a dictionary of key-values corresponding to environment variables that should be set for the environment the build is run in. Note thatenv
, if it is set, must be set at the platform-specific level, e.g., under theosx
,windows
, orlinux
keys. This is useful for setting, e.g.,TEXINPUTS
. For thedefault
/traditional
builder, the following settings are useful:program
(unset): one ofpdflatex
(the default),xelatex
orlualatex
. This selects the TeX engine.command
(unset): the preciselatexmk
ortexify
command to be invoked. This must be a list of strings. The defaults (hardcoded, not shown in the settings file) are:- (TeXLive):
["latexmk", "-cd", "-e", "-f", "-%E", "-interaction=nonstopmode", "-synctex=1"]
- (MiKTeX):
["texify", "-b", "-p", "--engine=%E", "--tex-option=\"--synctex=1\""]
- (TeXLive):
options
(unset): allows you to specify a TeX option, such as--shell-escape
. This must be a tuple: that is, useoptions: ["--shell-escape"]
Thebasic
builder also supports theprogram
andoptions
options. For the script builder, the following setting is required:script_commands
(unset): a command or list of commands to run. Each command can be either a string or a list, e.g.:- "pdflatex -synctex=1 -interaction=nonstopmode"
- ["pdflatex", "-synctex=1", "-interaction=nonstopmode"] See the the Script Builder documentation for details.
Build Panel Settings
highlight_build_panel
(true
): iftrue
the build panel will have a syntax applied to highlight any errors and warnings. Otherwise, the standard output panel configuration will be used.hide_build_panel
("no_badboxes"
): controls whether or not to hide the build panel after a build is finished. Possible values:"always"
: never show the build panel at all"no_errors"
: only show the build panel if errors occur"no_warnings"
: only hide the panel if no warnings occur"no_badboxes"
: only hide the panel if no warnings or badbox messages occur; this only differs fromno_warnings
ifdisplay_bad_boxes
is set totrue
."never"
: never hide the build panel Any other value will be interpreted as the default.
display_bad_boxes
(false
): iftrue
LaTeXTools will display any bad boxes encountered after a build. Note that this is disabled by default.show_error_phantoms
("warnings"
): ST3 Build 3118 or newer only controls which errors are displayed via phantoms. Possible values:"none"
: never show any phantoms at all"errors"
: only show errors using phantoms"warnings"
: only show warnings or errors using phantoms"badboxes"
: show any warnings, errors, or bad box messages use phantoms
build_finished_message_length
(2.0
): the number of seconds to display the status bar message about the completion of the build
Viewer Settings
viewer
(""
): the viewer you want to use. Leave blank (""
) or set to"default"
for the platform-specific viewer. Can also be set to"preview"
if you want to use Preview on OS X,"okular"
if you want to use Okular on Linux,"zathura"
is you want to use Zathura on Linux, or"command"
to run arbitrary commands. For details on the"command"
option, see the section on the Command Viewer.viewer_settings
: these are viewer-specific settings. Please see the section on Viewers or the documentation on Alternate Viewers for details of what should be set here.open_pdf_on_build
(true
): Controls whether LaTeXTools will automatically open the configured PDF viewer on a successful build. If set tofalse
, the PDF viewer will only be launched if explicitly requested usingC-l,v
orC-l,j
.disable_focus_hack
(false
): iftrue
, the focus hack that LaTeXTools uses to return focus to Sublime in some circumstances will not be run. Note: This does not mean that the viewer won't steal the focus, only that LaTeXTools won't try to steal the focus back.
Included File Settings
"image_types"
(["png", "jpg", "jpeg", "pdf" "eps"]
): image types that you use in LaTeX. These are used for autocompletions and to open included images where no extension is provided. Broadly speaking, this should correspond to any\DeclareGraphicsExtensions{}
commands used in your document, but the default value corresponds to the types of images supported bypdflatex
(they are also supported byxelatex
andlualatex
).
Bibliographic References Settings
bibliography
("traditional"
): specifies the bibliography plugin to use to handle extracting entries from a bibliography. May be specified either as a single plugin or a list of plugins to be executed in order. Possible values:"traditional"
: the default bibliography which is quite fast and works for most situations."new"
: a newer bibliography engine which uses a full Bib(La)TeX parser that supports more complex formatting (multiline entries, values enclosed in double quotes""
, literals and@string
macros) and allows you to access more fields, but can be slower and may not be necessary for most bibliographies.
cite_panel_format
(["{author_short} {year} - {title_short} ({keyword})","{title}"]
): specifies the format for bibliography entries displayed in the quickpanel when typing\cite{
or using one of the keybindings. It may either be a string or a list of two strings. In the latter case, the first string becomes the first line of the text displayed in the quick panel and the second the second.cite_autocomplete_format
("{keyword}: {title}"
): specifies the format for bibliography displayed when using Sublime's autocomplete functionality (ctrl+space
oralt+/
). Must be only a simple string.
Bibliography Format Strings
The two cite_xxx_format
settings take simple format strings to tell LaTeXTools how to display the settings. Fields from the bibliography can be displayed using wildcards wrapped in {}
. For example, using the value: ["{title} ({keyword})", "{author}"]
for cite_panel_format
would produce and entry like this:
Can quantum-mechanical description of physical reality be considered complete? (einstein1935quantum)
Albert Einstein and B Podolsky and N Rosen
Using the traditional
bibliography, the following fields are supported: keyword
, title
, author
, year
, and journal
. In addition, LaTeXTools provides two useful pseudo-fields: title_short
and author_short
, which display shortened versions of the title or author respectively. Using the new
bibliography, any field can be used. title_short
and author_short
are also provided, but title_short
first tries to use the shorttitle
BibLaTeX field, if it is available.
The default cite_panel_format
produces output like the following:
Einstein et al. 1934 - Can quantum-mechanical description of physical reality be co (einstein1935quantum)
Can quantum-mechanical description of physical reality be considered complete?
Other example formats are provided in the settings file.
Cache Settings
hide_local_cache
(true
): Whether the local cache should be hidden in the sublime cache path (true
) or in the same directory as the root file (false
). See the section LaTeXTools Cache.local_cache_life_span
(30 m
): The lifespan of the local cache, specified in the format" d x h X m X s"
whereX
is a natural numbers
stands for seconds,m
for minutes,h
for hours, andd
for days. Missing fields will be treated as 0 and white-spaces are optional. Hence you can write"1 h 30 m"
to refresh the cached data every one and a half hours. If you use"infinite"
the cache will not be invalidated automatically. A lower lifespan will produce results, which are more up to date. However it requires more recalculations and might decrease the performance.
Project-Specific Settings
Any settings can be overridden on a project-specific basis if you are using SublimeText's project system. In addition, you can use the tex_root
setting in the project file only to specify the master tex file instead of using %!TEX root =
magic comments. If specified in the project file, the tex_root
will be resolved relative to the location of your .sublime-project
file. Similarly, if you use output_directory
or aux_directory
in the project file, they will be resolved relative to the location of the project file.
To use project-specific settings, simply create a "settings"
section in your project file. The structure and format is the same as for the LaTeXTools.sublime-settings
file, but the first level settings are prefixed with latextools.
to avoid collisions with other packages. Here is an example:
{
... <folder-related options here> ...
"settings" : {
"latextools.tex_root": "main.tex",
"latextools.tex_file_exts": [".tex", ".tikz"],
"latextools.builder_settings": {
"program": "xelatex",
"options": "--shell-escape"
}
}
}
This sets main.tex
as the master tex file (assuming a multi-file project), and allows .tikz
files to be recognized as tex files. Furthermore (using the default, i.e., traditional builder), it forces the use of xelatex
instead of the default pdflatex
, and also adds the --shell-escape
option. All of these settings will only apply while in the current project.
Note: tweaking settings on a project-specific level can lead to subtle issues that can be difficult to track down. If you notice a bug, in addition to resetting your LaTeXTools.sublime-settings
file, you should remove any LaTeXTools settings from your project file.