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.
Reload vscode to make any change in this configuration effective.
| 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 | "tab" |
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.
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 |
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 |
The internal viewer listens on localhost. In some very specific use cases, one might require to change the host to listen on. As that may create a severe security breach, this cannot be changed by a permanent setting but only by calling the function latex-workshop.changeHostName(Change server listening hostname). This change will not remain across VS Code reloads. It can also be reset by calling latex-workshop.resetHostName (Reset server listening hostname to 127.0.0.1).
| Setting key | Description |
|---|---|
latex-workshop.view.pdf.color.light.pageColorsForeground |
The foreground color in light mode |
latex-workshop.view.pdf.color.light.pageColorsBackground |
The background color in light mode |
latex-workshop.view.pdf.color.light.backgroundColor |
The background color of the viewer in light mode |
latex-workshop.view.pdf.color.light.pageBorderColor |
The border color of pages in light mode |
latex-workshop.view.pdf.color.dark.pageColorsForeground |
The foreground color in dark mode |
latex-workshop.view.pdf.color.dark.pageColorsBackground |
The background color in dark mode |
latex-workshop.view.pdf.color.dark.backgroundColor |
The background color of the viewer in dark mode |
latex-workshop.view.pdf.color.dark.pageBorderColor |
The border color of pages in dark mode |
A kind of dark mode for the PDF viewer is available. Set latex-workshop.view.pdf.invert to about 0.9 to 1.0. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| 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 for backward sync by default. 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 pointing at the relevant element of the pdf preview. When using the internal viewer, the default keybinding to point at an element in the pdf preview is ctrl+click. It can be changed to double-click using the setting 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.indicator |
Define the visibility and style of SyncTeX indicator after a forward SyncTeX in the PDF viewer. | rectangle |
string |
Note: this function is not officially supported.
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.
| 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.
The configuration is described here.
Edit Sioyek's prefs.config to include the line
inverse_search_command "C:\path\to\vscode\Code.exe" "C:\path\to\vscode\resources\app\out\cli.js" --ms-enable-electron-run-as-node -r -g "%1:%2"
Add the following to your VSCode settings.json:
"latex-workshop.view.pdf.external.viewer.command": "C:\\path\\to\\sioyek\\sioyek.exe",
"latex-workshop.view.pdf.external.synctex.command": "C:\\path\\to\\sioyek\\sioyek.exe",
"latex-workshop.view.pdf.external.synctex.args": [
"--inverse-search",
"\"C:\\path\\to\\vscode\\Code.exe\" \"C:\\path\\to\\vscode\\resources\\app\\out\\cli.js\" --ms-enable-electron-run-as-node -r -g \"%1:%2\"",
"--reuse-instance",
"--forward-search-file",
"%TEX%",
"--forward-search-line",
"%LINE%",
"%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 -r -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%"
],According to https://unix.stackexchange.com/a/700749, you may need to add --no-sandbox when calling code
"latex-workshop.view.pdf.external.viewer.args": [
"--synctex-editor-command",
"code --no-sandbox -r -g \"%{input}:%{line}\"",
"%PDF%"
]Okular support
For forward search, 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.
For backward search, configure Okular to use vscode as editor:
Goto Settings > Configure Okular... > Editor and choose Custom Text Editor as editor while inserting code -r --goto %f:%l as the command.
Make sure to not have okular installed via snap otherwise it can not execute arbitary binaries.
To use it, make sure the browse tool is enabled (Tools > Browse), and simply left click while holding Shift (see here).
Thanks to @zyrikby for figuring this out.
qpdfview support
Forward:
"latex-workshop.view.pdf.viewer":"external",
"latex-workshop.view.pdf.external.viewer.command": "qpdfview",
"latex-workshop.view.pdf.external.viewer.args": [
"--unique",
"%PDF%"
],
"latex-workshop.view.pdf.external.synctex.command": "qpdfview",
"latex-workshop.view.pdf.external.synctex.args": [
"--unique",
"%PDF%#src:%TEX%:%LINE%:0",
],Backward:
Goto Edit > Settings... > Behavior > Source editor and set the command to
code --goto "%1:%2"
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. The path must not contain a trailing slash. The LaTeX toolchain should output files to this path. For a list of supported placeholders, please visit https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#placeholders. Note that if this config is set to %DIR% (default value) or %DIR_W32%, the extension will try to parse the last LaTeX tools used and look for -out-directory= and -outdir=, and automatically determine the output directory. This means that you can safely ignore this config if you use latexmk and do not manually mv the output files in your recipe.
| type | default value |
|---|---|
| string | "%DIR%" |
The default PDF viewer.
| type | default value | possible values |
|---|---|---|
| string | "tab" |
"browser", "tab", or "external"
|
-
"tab": Open PDF with the built-in tab viewer. SyncTeX and other features available. -
"browser": Open PDF with the default web browser. 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 |
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
|
The foreground color of the document when the OS appearance is light. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "" |
The background color of the document when the OS appearance is light. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "" |
The background color of the viewer when the OS appearance is light. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "#ffffff" |
The border color of pages when the OS appearance is light. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "lightgrey" |
The foreground color of the document when the OS appearance is dark. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "" |
The background color of the document when the OS appearance is dark. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "" |
The background color of the viewer when the OS appearance is dark. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "#ffffff" |
The border color of pages when the OS appearance is dark. The string must represent a color in HTML. Reload vscode to make any change in this configuration effective.
| type | default value |
|---|---|
| string | "lightgrey" |
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. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| 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. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| 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. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| 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. You must reopen the internal viewers or restart VS Code to take into account a change in this configuration.
| type | default value |
|---|---|
| number | 0 |
Which keybinding to use for the internal PDF viewer for reverse SyncTeX. Reload vscode to make any change in this configuration effective.
| type | default value | possible values |
|---|---|---|
| enum | "ctrl-click" |
"ctrl-click" or "double-click"
|
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" |
Define the visibility and style of SyncTeX indicator after a forward SyncTeX in the PDF viewer.
| type | default value | possible values |
|---|---|---|
| enum | "rectangle" |
"none", "circle", or "rectangle"
|
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.
Delay to wait for GitHub Codespaces Authentication of port forwarding to be resolved, in milliseconds.
| type | default value |
|---|---|
| number | 20000 |