Skip to content

Latest commit

 

History

History
210 lines (142 loc) · 12.2 KB

FAQ.md

File metadata and controls

210 lines (142 loc) · 12.2 KB
Raw

FAQ and common issues

Known incompatible Extensions

The following extensions are known to cause issues when active at the same time as LaTeX-Workshop, namely high CPU load issues, and a significant delay when using the Enter key in large files.

Cygwin is not supported

LaTeX Workshop does not support TeX Live installed through Cygwin. Please install TeX Live and other TeX distributions independently of Cygwin.

Using LaTeX Workshop with WSL

Starting with 1.35.0, VS Code supports WSL through Remote - WSL. LaTeX Workshop works well with the extension.

The directory ~/node_modules/ may cause errors

The directory ~/node_modules/ in the home directory may cause errors on Mac and Linux. The modules in the directory might be unintentionally loaded by VSCode because of the default behavior of node.js, which would cause errors such as Extension host terminated unexpectedly. We recommend moving the directory ~/node_modules/ to ~/npm/node_modules/.

I cannot build from a subfile

If you cannot build a multi file LaTeX project from a subfile, it means that the root file is not detected properly. See the Multi file projects page for details on how the root file is discovered. Note that you must open the directory (or one of its antecedents) containing all the project files in vscode for this mechanism to work.

The Problem Pane displays wrong messages

LaTeX compilers usually produce hard wrapped log messages, which makes them really hard to parse. To hopefully deal with complex log messages, we have decided to rely on non hard wrapped log messages. This can be achieved either

  • by setting the environment variable max_print_line. This is automatically done within the extension and works for the TeXLive distribution.
  • by adding the --max-print-line option to the compilers. This is automatically done within the extension and works for the MiKTeX distribution. Unfortunately, some compilers such as lualatex do not understand this option and may therefore fail. To disable the automatic addition of this option, set latex-workshop.latex.option.maxPrintLine.enabled to false.

Note that when log messages are hard wrapped, the Problems Pane is likely to be messed up.

Encoding issues with file names in the Problem Pane

If you experience encoding issues with file names displayed in the Problem Pane, you can try to set latex-workshop.message.convertFilenameEncoding to false.

I cannot use ctrl+alt in a shortcut

The default shortcuts for commands related to build and view use the modifiers ctrl+alt. On some keyboard layouts, ctrl+alt is used to emulate AltrGr, which makes these shortcuts unusable. Alternatively, you can use ctrl+l, alt+letter instead of ctrl+alt+letter by setting latex-workshop.bind.altKeymap.enabled to true.

Disable automatic build on save

Set the configuration variable latex-workshop.latex.autoBuild.run to "never".

I use build on save but I occasionally want to save without building

When latex-workshop.latex.autoBuild.run is set to onFileChange, building is triggered every time a file is saved. If you want to save a file without building it, you can use the Save without Building command from the Command Palette.

My file is built when I paste

Set editor.formatOnPaste to false.

The formatting program latexindent changes the file on disk when formatting and not only the buffer content. VSCode interprets it as a file change and triggers a build if latex-workshop.latex.autoBuild.run to "onFileChange"

Format on save does not work

This is a known issue but we cannot do much from the extension side.

The formatting utility latexindent reads its input from the file on the disk and not from the content of the editor. So when using Format on Save, first you format the file on the disk and then you save the content of the buffer. This is obviously done in the wrong order, but we cannot do much from the extension side to fix this. Note that if you save twice, the editor content is indeed formatted. When using RightClick->Format Document, we first save the buffer before calling the formatting program.

My file gets messed up

This is most likely related to the two following variables being set together latex-workshop.latex.autoBuild.run: "onFileChange" and editor.formatOnSave: true.

Formatting a .tex file actually changes it on the disk and then if latex-workshop.latex.autoBuild.run is "onFileChange" it saves the file and triggers a build. You will get two formatting processes running together and using the same temporary file. Hence, the mess you see in your file.

Large bibtex files are ignored

Bibtex files listed in a project are parsed for citation completion. This may induce significant slow down with large bibtex files. You can configure the maximum size of bibtex files parsed by the extension with latex-workshop.intellisense.citation.maxfilesizeMB".

Path containing Chinese or ~ characters

On some platforms, when the path of a TeX file contains Chinese characters or other non-ASCII characters, the compilation does not work well. In such cases, please use %DOCFILE% instead of %DOC% in your recipes. See also LaTeX recipes. Note that using relative paths instead of absolute ones may lead to other issues, see the following issues for a discussion on this: 1070 and 1137.

On some platforms, synctex does not work well with the path containing non-ASCII characters either. In such cases, please use a built-in synctex functionality. See Viewing & Synctex.

The LaTeX sidebar keeps reopening

If you like to work with no sidebar in Visual Studio Code and yet the LaTeX sidebar keeps showing up each time you switch focus from a non TeX file to a TeX file, you need to set latex-workshop.view.autoFocus.enabled to false.

Spell check

Code Spellchecker did a great job. Users may also find other extensions better alternatives, e.g., LanguageTool credited for its multi-lingual support.

I cannot nest snippets

Nesting snippets requires to have intellisense automatically triggered inside snippets. This can be achieved by setting editor.suggest.snippetsPreventQuickSuggestions to false.

Some @ snippets are not TAB completed

This is mostly related to the editor.quickSuggestions setting. The following value works well

"editor.quickSuggestions": {
        "other": true,
        "comments": false,
        "strings": false
      }

It is known that setting "other": false will prevent some @ snippets from being TAB expanded.

How to pass -shell-escape to latexmk

Some packages such as minted requires LaTeX compilers to use the -shell-escape flag. Passing this flag can be achieved in several different ways.

  1. Modify the section of latex-workshop.latex.tools related to latexmk in the following way

    "name": "latexmk",
"command": "latexmk",
"args": [
    "-shell-escape",
    "-synctex=1",
    "-interaction=nonstopmode",
    "-file-line-error",
    "-pdf",
    "-outdir=%OUTDIR%",
    "%DOC%"
]

  2. Directly specify -shell-escape in the compiler flag of latexmk. Modify the section of latex-workshop.latex.tools related to latexmk in the following way

    "name": "latexmk",
"command": "latexmk",
"args": [
    "-synctex=1",
    "-interaction=nonstopmode",
    "-file-line-error",
    "-pdf",
    "-pdflatex=pdflatex -shell-escape %O %S",
    "-outdir=%OUTDIR%",
    "%DOC%"
]

  3. Create a .latexmkrc config file (in your home directory or in the working directory) containing at least

    $pdflatex='pdflatex -shell-escape';

LaTeX-Workshop shadows vscode's default keybindings

LaTeX-Workshop uses Ctrl+L as the first key of many keybindings

Since vscode 1.32.0, Ctrl+L has been set to expandLineSelection. We define a new keybinding for expandLineSelection: Ctrl+L, Ctrl+L.

LaTeX-Workshop uses Ctrl+M for fonts keybindings

vscode sets Ctrl+M to editor.action.toggleTabFocusMode. We define a new keybinding for editor.action.toggleTabFocusMode: Ctrl+L, Ctrl+M.

Syntax Highlighting does not work for most elements

Please change VS Code theme you are using. For example, Visual Studio Dark and Visual Studio Light do not work with LaTeX Workshop.

Install older version

You can install older versions of LaTeX Workshop by right-clicking it in the extension panel of VS Code and selecting Install Another Version.

Customizing a Color Theme

To customize a color theme, you can refer to the official documentation. The following is an example to make fonts black in math environment. Writing it in your settings.json, you can enable that. To find an appropriate scope for each element in a TeX document, you can use the scope inspector of VS Code. Please refer to this document.

    "editor.tokenColorCustomizations": {
        "textMateRules": [
            {
                "scope": [
                    "support.class.math.block.environment.latex",
                ],
                "settings": {
                    "foreground": "#000000"
                }
            }
        ]
    }