Intellisense
This extension provides a variety of intellisense completions for different LaTeX features; notably for citations, commands, environments, labels, and file names. Intellisense suggestions are updated on file save but a more aggressive updating strategy can be used by setting intellisense.update.aggressive.enabled to true, which triggers update after no key has been stroked for the delay defined by latex-workshop.intellisense.update.delay. Most of the intellisense data are obtained by parsing the project files. Some environments should be considered as verbatim like and therefore be skipped. The list of such environments can be configured by latex-workshop.latex.verbatimEnvs
Every file of a LaTeX project is parsed to look for bibliography resources, either directly in a thebibliography environment or given by the bibliography or addbibresource commands or variants of them. If some of these resources are located outside the project directly, you need to list the directories where to look for them in latex-workshop.latex.bibDirs. You can also rely on the kpsewhich command to resolve bibliography files by setting latex-workshop.kpsewhich.enabled to true.
Then, when citation commands like \cite and its derivatives are automatically completed with bibliography entries found in the various resources.
If you use very large bibtex files, you may experience temporary freezing. Hence, files larger than 5MB are ignored (see latex-workshop.bibtex.maxFileSize).
| Setting key | Description | Default | Type |
|---|---|---|---|
latex-workshop.intellisense.citation.label |
Citation property used as suggestion label | "bibtex key" |
string: "bibtex key" | "title" | "authors" |
latex-workshop.intellisense.citation.format |
List of fields to display and to use for filtering suggestions | array of strings | |
latex-workshop.bibtex.maxFileSize |
Maximum bibtex file size (in MB) | 5 |
float |
latex-workshop.intellisense.citation.type |
Type of vs code suggestion to use | "inline" |
string: "inline" | "browser" (dropdown menu) |
latex-workshop.intellisense.package.enabled |
Enabling of auto-completion for commands and environments from loaded packages | true |
boolean |
latex-workshop.latex.bibDirs |
List of paths to look for .bib files. |
[] |
array of strings |
latex-workshop.kpsewhich.enabled |
Use kpsewhich to resolve .bib files. |
false |
boolean |
latex-workshop.kpsewhich.path |
location of the kpsewhich executable file. | "kpsewhich" |
string |
Similarly as for the citation mechanism, all files of a LaTeX project are search for labels. We scan labels defined by \label{...} in the whole document or by label={...} but only inside the first argument of an environment. Label definition with commands other than \label{...} can be set in latex-workshop.intellisense.label.command.
Any \ref related command is automatically completed with label keys.
The key \ automatically triggers completion of LaTeX commands. You can define additional triggers. Several mechanisms play together to build the list of available commands.
- A set of standard LaTeX commands is provided in the file
data/commands.json. You may overwrite some of these commands or add new ones by using thelatex-workshop.intellisense.command.userconfiguration variable. - The files of a LaTeX project are searched for any already used commands in the form
mycommandfollowed by several{}groups. Then, a snippet is dynamically built for each of them and they are added to the command completion list. - When
latex-workshop.intellisense.package.enabledistrue, the command completion list is also populated with the commands provided by all the standard packages used in the project (through\usepackage). The list of commands provided by every package is described here. Note that homemade packages are ignored in this mechanism because they do not come with a.cwlfile. - If you use personal macro files and want them to be taken into account by intellisense but store them in some
texmfstructure or dedicated directory. Just add the directory containing the file tolatex-workshop.latex.texDirs. The file must be loaded in the LaTeX project through the\inputmacro. - If you write your own package along with the corresponding
.cwlfile, you can use the Typescript script parse-cwl.ts. For details on how to run this script, please read https://github.com/James-Yu/LaTeX-Workshop/tree/master/dev#parse-cwlts . Place the generated<mypackage>.jsonfile in a folder defined inlatex-workshop.intellisense.package.dirs. Note it only works whenlatex-workshop.intellisense.package.enabledis set totrueand you have imported this package in LaTeX, i.e.,\usepackage{mypackage}. - Many snippets use text hints of the form
${\d:some_tex}for their argument. You may prefer to hide instead by settinglatex-workshop.intellisense.argumentHint.enabledtotrue. - We provide one entry in the intellisense completion list per LaTeX command signature. If you feel, it makes the completion list too long, set
latex-workshop.intellisense.optionalArgsEntries.enabledtofalse.
| Setting key | Description | Default | Type |
|---|---|---|---|
latex-workshop.intellisense.triggers.latex |
Additional trigger characters for intellisense of LaTeX documents. | ["{"] |
array of strings |
latex-workshop.intellisense.package.enabled |
Enabling of auto-completion for commands and environments from loaded packages | true |
boolean |
latex-workshop.intellisense.package.env.enabled |
Enable \envname snippets |
true |
boolean |
latex-workshop.intellisense.package.extra |
Extra packages to load for intellisense | [] |
array of strings |
latex-workshop.intellisense.package.dirs |
Extra directories where to look for intellisense data | [] |
array of strings |
latex-workshop.intellisense.unimathsymbols.enabled |
Show unimath symbols as suggestions when \ pressed |
false |
boolean |
latex-workshop.intellisense.argumentHint.enabled |
Hide argument hints in intellisense completion | false |
boolean |
latex-workshop.intellisense.optionalArgsEntries.enabled |
Add one completion item per command signature | true |
boolean |
latex-workshop.latex.texDirs |
List of paths to look for input .tex files. |
[] |
array of strings |
There are three different ways to insert a new environment
-
The
\begin / \endsnippet. Type\beginand autocomplete with Insert\begin / \end. It will leave you with a multi-cursor inside the braces of\begin{}and\end{}and a list of environments will pop up.
-
The
\beginonly approach. Type\beginand directly choose the environment name from the list. It will automatically add the closing command. Note that this approach enables us to take into account extra arguments. For instance, thealignat*environment takes the number of "equation columns"{n}as a mandatory argument. Note that dealing with extra arguments is not possible with the\begin / \endsnippet.
-
The
\envnameapproach. Standard environments can be inserted by typing\followed by the environment name. This approach can deal with extra arguments.
Completion for environments is based on a set of predefined environments enriched with those defined by the included packages when latex-workshop.intellisense.package.enabled is true. Moreover, when latex-workshop.intellisense.package.env.enabled is also true, environments provided by used packages can be inserted by using the \envname approach. On top of this, any custom environment is added to the completion list after being used once.
We support intellisense for file completion inside the following commands : include, includegraphics, input, and all the commands from the import package. For the includegraphics command, when some paths are defined by the \graphicspath command, only the files located under these directories are listed.
Note that any file matching one of the patterns listed in the following variables is removed from the list: files.exclude, latex-wokrshop.intellisense.file.exclude.
When latex-workshop.intellisense.includegraphics.preview.enabled is set to true, triggering graphics file completion shows a preview of the file.
Next to intellisense for anything starting with \, we provide an independent intellisense mechanism triggered by @. The trigger character @ is set by the configuration variable latex-workshop.intellisense.atSuggestion.trigger.latex and can be replaced by any other non-alphabetical character. Setting latex-workshop.intellisense.atSuggestion.trigger.latex to the empty string deactivates these suggestions. You can remove, modify or define new suggestions using the setting latex-workshop.intellisense.atSuggestion.user.
| Prefix | Letter |
|---|---|
@a |
\alpha |
@b |
\beta |
@c |
\chi |
@d |
\delta |
@e |
\epsilon |
@f |
\phi |
@g |
\gamma |
@h |
\eta |
@i |
\iota |
@k |
\kappa |
@l |
\lambda |
@m |
\mu |
@n |
\nu |
@p |
\pi |
@q |
\theta |
@r |
\rho |
@s |
\sigma |
@t |
\tau |
@u |
\upsilon |
@o |
\omega |
@& |
\wedge |
@x |
\xi |
@y |
\psi |
@z |
\zeta |
@D |
\Delta |
@F |
\Phi |
@G |
\Gamma |
@Q |
\Theta |
@L |
\Lambda |
@X |
\Xi |
@Y |
\Psi |
@S |
\Sigma |
@U |
\Upsilon |
@W |
\Omega |
@ve |
\varepsilon |
@vf |
\varphi |
@vs |
\varsigma |
@vq |
\vartheta |
| Prefix | Command |
|---|---|
@( |
\left( $1 \right) |
@{ |
\left\{ $1 \right\} |
@[ |
\left[ $1 \right] |
@. |
\cdot |
@8 |
\infty |
@6 |
\partial |
@/ |
\frac{$1}{$2} |
@% |
\frac{$1}{$2} |
@^ |
\Hat{$1} |
@_ |
\bar{$1} |
@@ |
\circ |
@0 |
^\circ |
@; |
\dot{$1} |
@: |
\ddot{$1} |
@= |
\equiv |
@* |
\times |
@< |
\leq |
@> |
\geq |
@2 |
\sqrt{$1} |
@I |
\int_{$1}^{$2} |
@| |
\Big | |
@+ |
\bigcup |
@- |
\bigcap |
@, |
\nonumber |
Enable preview for \includegraphics completion.
| type | default value |
|---|---|
| boolean | true |
Define what field to show as suggestion labels when intellisense provides citation suggestions in inline mode.
-
bibtex key: Show bibtex keys in the inline intellisense. -
title: Show publication titles in the inline intellisense. -
author: Show publication authors in the inline intellisense.
| type | default value |
|---|---|
| string | "bibtex key" |
List of fields to display for citation preview and intellisense. This list is also used as the filter text to narrow down the intellisense suggestions.
| type | default value |
|---|---|
| array of strings | ["author", "title", "journal", "publisher", "booktitle", "year"] |
Define the maximum bibtex file size for the extension to parse in MB.
| type | default value |
|---|---|
| float | 5 |
Define which type of hint to show when intellisense provides citation suggestions.
- inline: Use the inline intellisense to provide citation completion items.
- browser: Use a dropdown menu to provide citation completion items.
| type | default value |
|---|---|
| string | "inline" |
Additional trigger characters for intellisense of LaTeX documents. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| array of strings | ["{"] |
Auto-complete commands and environments from used packages.
| type | default value |
|---|---|
| boolean | true |
List of packages to exclude from the auto-completion mechanism.
When latex-workshop.intellisense.package.enabled is set to true, the commands and environments defined in these packages will not be added to the intellisense suggestions. This setting has a higher priority over latex-workshop.intellisense.package.extra. You may include the string "lw-default" in the list to remove all default commands and environments.
| type | default value |
|---|---|
| array of strings | [] |
List of extra packages to always add to the auto-completion mechanism.
When latex-workshop.intellisense.package.enabled is set to true, the commands and environments defined in these extra packages will be added to the intellisense suggestions
| type | default value |
|---|---|
| array of strings | [] |
List of extra directories to look for package completion files in addition to those provided by the extension.
See the section on Commands intellisense to learn how to generate these files. Files found in these directories have a higher priority over the default ones. This setting is only relevant when latex-workshop.intellisense.package.env.enabled is true.
| type | default value |
|---|---|
| array of strings | [] |
If true, every environment provided by an included package is available by a snippet \envname. Only applies when latex-workshop.intellisense.package.enabled is true.
| type | default value |
|---|---|
| boolean | true |
Many LaTeX commands can have several signatures, each with different arguments. If set to True, the intellisense completion list will have one entry for each form of a given command.
| type | default value |
|---|---|
| boolean | true |
Many snippets use text hints of the form ${\d:some_tex} for their argument. You may prefer to hide instead by setting this configuration to true.
| type | default value |
|---|---|
| boolean | false |
Reload vscode after change.
The name of LaTeX commands that indicates a label definition. The command must accept one mandatory argument of the label reference string, e.g, \linelabel{ref-str}.
| type | default value |
|---|---|
| array of strings | ["label", "linelabel"] |
When \ is typed, show unimath symbols in the dropdown selector.
| type | default value |
|---|---|
| boolean | false |
Dictionary of "command name": "command snippet" to add to, replace, or remove the default ones in data/commands.json. The key of the dictionary is the command name with optional braces indicating the command arguments. The value of the dictionary is the snippet to be inserted. If the key is identical to a default command suggestion defined in data/commands.json, the new value in the dictionary is used for suggestion. If the value is an empty string, the command is removed from suggestion. Leading backslashes will be added to both the name and snippet by the extension, so don't include them in this config. For example, {"mycommand[]{}": "notsamecommand[${2:option}]{$TM_SELECTED_TEXT$1}", "parbox{}{}": "parbox{${2:width}}{$TM_SELECTED_TEXT$1}", "overline{}": ""} adds a new command with name mycommand[]{} that inserts \\notsamecommand[]{}, replaces the default snippet of \\parbox{}{} to make it include current selected text, and removes \\overline{} from suggestion.
| type | default value |
|---|---|
| dictionary of string: string | {} |
Character to trigger @ suggestions as part of intellisense. Set this variable to '' to deactivate these suggestions.
| type | default value |
|---|---|
| string | @ |
Dictionary of "@prefix": "snippet command" to add to, replace, or remove the default suggestions in data/at-suggestions.json. The key of the dictionary is the triggering string, which must starts with @ regardless of latex-workshop.intellisense.atSuggestion.trigger.latex. The value of the dictionary is the snippet to be inserted. If the key is identical to a default snippet defined in data/at-suggestions.json, the new value in the dictionary is used for suggestion. If the value is an empty string, the snippet is removed from suggestion. For example, { "@.": "\\cdot", "@6": "" }.
| type | default value |
|---|---|
| dictionary of string: string | {} |
List of directories where to look for .bib files.
Absolute paths are required. This setting is only used by the intellisense feature, you may also need to set the environment variable BIBINPUTS properly for the LaTeX compiler to find the .bib files.
| type | default value |
|---|---|
| array of strings | [] |
Define the location of the kpsewhich executable file.
| type | default value |
|---|---|
| string | "kpsewhich" |
Use kpsewhich -format=.bib to resolve bibliography files in addition to looking into the directories listed in latex-workshop.latex.bibDirs.
The ksepwhich executable is defined by latex-workshop.kpsewhich.path.
| type | default value |
|---|---|
| boolean | false |
Patterns to ignore in file completion
| type | default value |
|---|---|
| array of strings | [ "**/*.aux", "**/*.bbl", "**/*.bcf", "**/*.blg", "**/*.idx", "**/*.ind", "**/*.lof", "**/*.lot", "**/*.out", "**/*.toc", "**/*.acn", "**/*.acr", "**/*.alg", "**/*.glg", "**/*.glo", "**/*.gls", "**/*.ist", "**/*.fls", "**/*.log", "**/*.fdb_latexmk", "**/*.synctex.gz", "**/*.run.xml" ] |
Specify the base directory for file completion. The possible choices are
- Completion from the root file directory
- Completion from the current file directory
- both
| type | default value |
|---|---|
| enum | "root relative"|"file relative"|"both" |
Defines whether the extension aggressively parses the changed content after stopped typing.
Disable this config will let the extension only update intellisense after saving changed files.
| type | default value |
|---|---|
| boolean | false |
Defines the delay in milliseconds for the extension to update current active file content for intellisense after stopped typing.
This config works only when intellisense.update.aggressive.enabled is enabled. Lower this value will let the extension to know newly defined commands/references/environments more quickly, at the cost of more frequent content parsing: more computation burden.
| type | default value |
|---|---|
| number | 1000 |
Two types of completion are available for BibTeX files
-
Hitting
@triggers completion for adding a new entry. The available completions are described in data/bibtex-entries.json. The user can override any entry by redefining it in the variablelatex-workshop.intellisense.bibtexJSON.replace. The entries are formatted according to the variables already used for bibtex formatting: -
Inside an entry, when at the beginning of a line, intellisense suggests optional fields. the completion menu pops up after typing two characters but can also be manually triggered using ctrl + space. The available completions are described in data/bibtex-optional-entries.json.
Backend to use for citation intellisense.
| type | default value | possible values |
|---|---|---|
| enum | "bibtex" |
"bibtex" | "biblatex" |
Dictionary of "entry name": ["array", "of", "fields"] to replace the default fields used in data/bibtex-entries.json.
This variable is used when latex-workshop.intellisense.citation.backend is set to biblatex.
| type | default value |
|---|---|
| dictionary of string: string | {} |
Dictionary of "entry name": ["array", "of", "fields"] to replace the default fields used in data/bibtex-entries.json.
This variable is used when latex-workshop.intellisense.citation.backend is set to bibtex.
| type | default value |
|---|---|
| dictionary of string: string | {} |