View
A document can be previewed a number of ways, namely the icon that appears in the top left of an open TeX document (see gif) 
, or by the shortcut ctrl+alt+v (see also the FAQ for an alternative shortcut). The command associated to these keybindings is latex-workshop.view. Note that each call to this command opens a new viewer.
If you want to preview the PDF file in a separated window, you can do that with the browser selecting View in web browser in the side bar (command latex-workshop.viewInBrowser).
The extension also allows to view any PDF file possibly not related to a LaTeX project. To open such a PDF file, it is sufficient to open from the Explorer. Any PDF file opened this is way is monitored by a file watcher to be automatically reloaded when it changes on disk. Note that this is a different mechanism as the one used for PDF files related to LaTeX projects, which get reloaded after every successful building.
Delay before reloading a PDF file after last change, in milliseconds.
You must reload VSCode to take into account a change in this configuration.
| type | default value |
|---|---|
| number | 250 |
| Setting key | Description | Default | Type |
|---|---|---|---|
latex-workshop.latex.outDir |
Where to find the PDF files | "%DIR%" |
string |
latex-workshop.view.pdf.viewer |
The default PDF viewer | (see details) | string |
latex-workshop.view.pdf.ref.viewer |
The PDF viewer to preview \ref
|
(see details) | string |
The PDF viewer provided with the extension internally uses PDF.js. The keybindings support by PDF.js are documented here.
You can customize the look and feel of the internal PDF viewer. Of course, this is only relevant when using the internal PDF viewer for viewing the PDF produced by the building toolchain, ie when latex-workshop.view.pdf.viewer is set to tab. Although the PDF viewer should refresh automatically when needed, you can request it explicitly by calling the command latex-workshop.refresh-viewer. If you experience some focus issues after opening a viewer tab, consider increasing latex-workshop.view.pdf.tab.openDelay.
Below are the detailed explanations for the different possible settings
| Setting key | Description |
|---|---|
latex-workshop.view.pdf.tab.editorGroup |
Define the editor group for the tab viewer |
latex-workshop.view.pdf.zoom |
The default zoom level of the PDF viewer |
latex-workshop.view.pdf.scrollMode |
The default scroll mode of the PDF viewer |
latex-workshop.view.pdf.spreadMode |
The default spread mode of the PDF viewer |
latex-workshop.view.pdf.hand |
Enable the hand tool |
latex-workshop.view.pdf.trim |
The default trim mode of the PDF viewer |
latex-workshop.view.pdf.backgroundColor |
The background color of the PDF viewer |
Additional settings for the internal viewer:
| Setting key | Description |
|---|---|
latex-workshop.view.pdf.internal.synctex.keybinding |
How to trigger synctex with the internal viewer |
latex-workshop.viewer.pdf.internal.port |
Which port internal viewer server communicates through |
latex-workshop.viewer.pdf.internal.keyboardEvent |
The shortcuts of VS Code on the internal viewer |
A kind of dark mode for the PDF viewer is available. Set latex-workshop.view.pdf.invert to about 0.9 to 1.0.
| Setting key | Description |
|---|---|
latex-workshop.view.pdf.invertMode.enabled |
Enable the CSS invert filter. |
latex-workshop.view.pdf.invert |
Define the CSS invert filter level |
latex-workshop.view.pdf.invertMode.brightness |
brightness filter level |
latex-workshop.view.pdf.invertMode.grayscale |
grayscale filter level |
latex-workshop.view.pdf.invertMode.hueRotate |
hue-rotate filter angle |
latex-workshop.view.pdf.invertMode.sepia |
sepia filter level |
The javascript built-in version of SyncTeX is used by default. See settings. See Using SyncTeX with an external viewer also.
Forward/Direct synctex (source to pdf) can either be activated by selecting 'Navigate, select, and edit' > 'SyncTeX from cursor' in the side bar, or by the shortcut ctrl+alt+j (cmd+option+j on Mac), see also the FAQ for an alternative shortcut.
Backward/Reverse synctex (pdf to source) is activated by selecting the relevant element of the pdf preview. When using the internal viewer, the keybinding to select an element is defined by latex-workshop.view.pdf.internal.synctex.keybinding.
| Setting key | Description | Default | Type |
|---|---|---|---|
latex-workshop.synctex.afterBuild.enabled |
Forward synctex at cursor after compiling | false |
boolean |
latex-workshop.synctex.path |
SyncTeX location | "synctex" |
string |
latex-workshop.synctex.synctexjs.enabled |
Enable using a built-in synctex function. | true |
boolean |
You can view PDF files with external PDF viewers by calling View LaTeX PDF file in external viewer (command latex-workshop.viewExternal) either from the Command Palette or the TeX badge. This function is not officially supported.
| Setting key | Description | Default | Type |
|---|---|---|---|
latex-workshop.view.pdf.external.viewer.command |
The command to execute when using external viewer | (see details) | string |
latex-workshop.view.pdf.external.viewer.args |
The arguments to supply to the above command | (see details) | array |
latex-workshop.view.pdf.external.synctex.command |
SyncTeX command for the external viewer | (see details) | string |
latex-workshop.view.pdf.external.synctex.args |
Arguments to use for the above command | (see details) | array |
Note: this function is not officially supported.
The following configuration has been reported to work with SumatraPDF (see here)
In settings.txt of SumatraPDF, set
// the part of cli.js is deleted
InverseSearchCmdLine = "C:\Users\<Username>\AppData\Local\Programs\Microsoft VS Code\Code.exe" "C:\Users\<Username>\AppData\Local\Programs\Microsoft VS Code\resources\app\out\cli.js" --ms-enable-electron-run-as-node -r -g "%f:%l"
EnableTeXEnhancements = true
Add the following option to your settings.json in your VS Code
"latex-workshop.view.pdf.viewer": "external",
"latex-workshop.view.pdf.external.synctex.command": "C:/Users/zhang/AppData/Local/SumatraPDF/SumatraPDF.exe",
"latex-workshop.view.pdf.external.synctex.args": [
"-forward-search",
"%TEX%",
"%LINE%",
"-reuse-instance",
"-inverse-search",
"\"C:\\Users\\<Username>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe\" \"C:\\Users\\<U>\\AppData\\Local\\Programs\\Microsoft VS Code\\resources\\app\\out\\cli.js\" --ms-enable-electron-run-as-node -r -g \"%f:%l\"",
"%PDF%"
],Do not forget to set the paths according to your installation.
Evince support
This is trickier, but works. See here.
-
Download this file (modified to work with VScode):
- for Python 2: evince_synctex2.zip
- for Python 3: evince_synctex3.zip
-
Unzip it in any folder in your PATH (for instance,
$HOME/bin/or$HOME/.local/bin). -
Make sure that all files are executable with
chmod +rx evince2 evince_forward_search evince_backward_search -
Add the following options to your configuration:
"latex-workshop.view.pdf.viewer": "external", "latex-workshop.view.pdf.external.viewer.command": "evince2". "latex-workshop.view.pdf.external.viewer.args": [ "%PDF%" ], "latex-workshop.view.pdf.external.synctex.command": "evince_forward_search", "latex-workshop.view.pdf.external.synctex.args": [ "%PDF%", "%LINE%", "%TEX%" ],
To make this work both ways, first open the pdf file with the external viewer.
Zathura support
Forward: --synctex-forward flag
Backward: Use %{input} and %{line} as placeholders.
"latex-workshop.view.pdf.viewer": "external",
"latex-workshop.view.pdf.external.viewer.command": "zathura",
"latex-workshop.view.pdf.external.viewer.args": [
"--synctex-editor-command",
"code --reuse-window -g \"%{input}:%{line}\"",
"%PDF%"
],
"latex-workshop.view.pdf.external.synctex.command": "zathura",
"latex-workshop.view.pdf.external.synctex.args": [
"--synctex-forward=%LINE%:0:%TEX%",
"%PDF%"
],Okular support
Add the following options to your configuration:
"latex-workshop.view.pdf.viewer": "external",
"latex-workshop.view.pdf.external.viewer.command": "okular",
"latex-workshop.view.pdf.external.viewer.args": [
"--unique",
"%PDF%"
],
"latex-workshop.view.pdf.external.synctex.command": "okular",
"latex-workshop.view.pdf.external.synctex.args": [
"--unique",
"%PDF%#src:%LINE%%TEX%"
],Thanks to @miterion for figuring this out.
Backward: In Skim > Preferences > Sync, select Visual Studio Code in the Preset tab
Forward: Edit settings.json as follows, then use
- cmd+option+v to open Skim at the beginning of the PDF
- cmd+option+j to jump to Skim at the current line
"latex-workshop.view.pdf.viewer": "external",
"latex-workshop.view.pdf.external.viewer.command": "/Applications/Skim.app/Contents/SharedSupport/displayline",
"latex-workshop.view.pdf.external.viewer.args": [
"0",
"%PDF%"
],
"latex-workshop.view.pdf.external.synctex.command": "/Applications/Skim.app/Contents/SharedSupport/displayline",
"latex-workshop.view.pdf.external.synctex.args": [
"-r",
"-b",
"%LINE%",
"%PDF%",
"%TEX%",
],The directory where the extension tries to find project files (e.g., PDF and SyncTeX generated files).
Both relative and absolute paths are supported. Relative path start from the root file location, so beware if it is located in sub-directory. Note that the LaTeX toolchain should output files to this path. The default recipes, which relies on latexmk, takes care of putting all the generated files to the directory specified by latex-workshop.latex.outDir. The path given to this option must not contain a trailing slash.
The following placeholders defined in the recipes section can be used.
| type | default value |
|---|---|
| string | "%DIR%" |
The default PDF viewer.
| type | default value | possible values |
|---|---|---|
| string | "none" |
"none", "browser", "tab", or "external"
|
-
"none": Undetermined viewer. A viewer selector will pop up upon viewing PDF. -
"browser": Open PDF with the default web browser. SyncTeX and other features available. -
"tab": Open PDF with the built-in tab viewer. SyncTeX and other features available. -
"external": Experimental Open PDF with the external viewer set in "View > Pdf > External: command"
PDF viewer used for [View on PDF] link on \ref.
| type | default value | possible values |
|---|---|---|
| enum | "auto" |
"auto", "tabOrBrowser", or "external"
|
Define the editor group to use for the viewer tab.
| type | default value |
|---|---|
| string | "right" |
-
"current": Use the current editor group -
"left": Put the viewer tab in a new group on the left of the current one -
"right": Put the viewer tab in a new group on the right of the current one -
"above": Put the viewer tab in a new group above the current one -
"below": Put the viewer tab in a new group below the current one
The default zoom level of the PDF viewer. This default value will be passed to the viewer upon opening.
| type | default value | possible values |
|---|---|---|
| string | "auto" |
"auto", "page-actual", "page-fit", "page-width", one-based scale values (e.g., 0.5 for 50%, 2.0 for 200%) |
The default scroll mode of the PDF viewer. This default value will be passed to the viewer upon opening.
| type | default value | possible values |
|---|---|---|
| enum | 0 |
0, 1, 2, 3
|
-
0: Vertical scroll -
1: Horizontal scroll -
2: Wrapped display -
3: Page scroll
The default spread mode of the PDF viewer. This default value will be passed to the viewer upon opening.
| type | default value | possible values |
|---|---|---|
| enum | 0 |
0, 1, 2
|
-
0: No spread -
1: Odd spread -
2: Even spread
Define if the hand tool is enabled by default in the PDF viewer.
| type | default value |
|---|---|
| boolean | false |
Define the background color for the PDF viewer.
Possible values are any strings representing a color in CSS. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| type | default value |
|---|---|
| string | "#ffffff" |
The default trim mode of the PDF viewer
| type | default value | possible values |
|---|---|---|
| enum | 0 |
0, 1, 2, 3
|
-
0: No page trimming -
1: Trim 5% at margin -
2: Trim 10% at margin -
3: Trim 15% at margin
Defines the port on which the internal viewer listens for events such as synctex or refreshing the viewer. The default value of 0 means that the port is chosen randomly by the extension.
| type | default value |
|---|---|
| number | 0 |
Note: keep this value set to 0 unless you know what you are doing.
Rebroadcast KeyboardEvent on the internal PDF viewers. If the keyboard shortcuts of VS Code do not work well on the internal viewer, change this setting. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| type | default value | possible values |
|---|---|---|
| enum | auto |
auto, force, never
|
Enable the CSS invert filter. The possible choices are
-
auto: Enable the invert filter when using a dark theme. -
always: Always enable invert filter. -
compat: Enable the invert filter only ifinvert > 0. -
never: Disable the invert filter.
You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| type | default value | possible values |
|---|---|---|
| enum | compat |
auto, always, compat, never
|
Define the CSS invert filter level of the PDF viewer.
This config can invert the color of PDF. Possible values are any floating point numbers from 0 to 1. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| type | default value |
|---|---|
| number | 0 |
Define the CSS brightness filter level of the PDF viewer when the invert mode is enabled. Possible values are from 0 to 2.
| type | default value |
|---|---|
| number | 1 |
Define the CSS grayscale filter level of the PDF viewer when the invert mode is enabled. Possible values are from 0 to 1.
| type | default value |
|---|---|
| number | 0.6 |
Define the CSS hue-rotate filter angle of the PDF viewer when the invert mode is enabled. Possible values are from 0 to 360.
| type | default value |
|---|---|
| number | 180 |
Define the CSS sepia filter level of the PDF viewer when the invert mode is enabled. Possible values are from 0 to 1.
| type | default value |
|---|---|
| number | 0 |
Which keybinding to use for the internal PDF viewer for reverse SyncTeX. You must reload VSCode or the PDF viewer to take into account a change in this configuration.
| type | default value | possible values |
|---|---|---|
| enum | "ctrl-click" |
"ctrl-click" or "double-click"
|
Define the delay in milliseconds to wait for a tab opening.
Please increase the value if you encounter a focus issue after opening a tab.
| type | default value |
|---|---|
| number | 1000 |
Execute forward synctex at cursor position after compiling LaTeX project.
| type | default value |
|---|---|
| boolean | false |
Define the location of SyncTeX executive file.
Additional arguments, e.g., synctex modes and position of click, will be appended to this command.
| type | default value |
|---|---|
| string | "synctex" |
Enable using a builtin synctex function. The command set in latex-workshop.synctex.path will not be used. This builtin synctex works well even if the path of TeX files contains non-ASCII characters.
| type | default value |
|---|---|
| boolean | true |
The command to execute when using external viewer. When left empty, the default PDF viewer provided by the operating system is used.
This function is not officially supported. %PDF% is the placeholder for the absolute path to the generated PDF file.
| type | default value |
|---|---|
| string | "" |
"latex-workshop.view.pdf.external.viewer.command": "/usr/bin/okular",This works with latex-workshop.view.pdf.external.viewer.command to provide the arguments to the external viewer.
| type | default value |
|---|---|
| array | [ "%PDF%" ] |
e.g.
"latex-workshop.view.pdf.external.viewer.args": [
"--unique",
"%PDF%"
],The command to execute when forward synctex to external viewer.
| type | default value |
|---|---|
| string | "" |
Note: this function is not officially supported.
The arguments to apply to the external forward synctex command. %LINE% is the line number, %PDF% is the placeholder for the absolute path to the generated PDF file, and %TEX% is the source LaTeX file path with .tex extension from which syncTeX is fired.
| type | default value |
|---|---|
| array | ["%LINE%", "%PDF%", "%TEX%" ] |
Note: this function is not officially supported.