Skip to content

Latest commit

 

History

History
328 lines (224 loc) · 15.3 KB

View.md

File metadata and controls

328 lines (224 loc) · 15.3 KB

Viewing & Synctex

intellisense demo

Viewing Documents

A document can 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).

Overview

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.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.ref.viewer The PDF viewer to preview \ref (see details) string

Internal PDF viewer

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.

Below are the detailed explanations for the different possible settings

Setting key Description
latex-workshop.view.pdf.tab.useNewGroup Use new 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.invert Define the CSS invert filter level
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.view.pdf.tab.useNewGroup

When set to true, the viewer is opened in a new editor group, otherwise the current group is used.

type default value
boolean true

latex-workshop.view.pdf.zoom

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%)

latex-workshop.view.pdf.scrollMode

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
  • 0: Vertical scroll
  • 1: Horizontal scroll
  • 2: Wrapped display

latex-workshop.view.pdf.spreadMode

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

latex-workshop.view.pdf.hand

Define if the hand tool is enabled by default in the PDF viewer.

type default value
boolean false

latex-workshop.view.pdf.invert

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.

type default value
number 0

latex-workshop.view.pdf.trim

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

latex-workshop.viewer.pdf.internal.port

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.

Synctex

This extension will automatically look for synctex in the expected location (see settings) and will alert the user if it is not found. Alternatively, you can use the javascript built-in version of synctex, see settings.

Synctex may fail if the path contains non-ASCII characters, see FAQ.

Usage

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 using the following keybinding on the relevant element of the pdf preview.

latex-workshop.view.pdf.internal.synctex.keybinding

type default value possible values
enum "ctrl-click" "ctrl-click" or "double-click"

Using synctex with an external viewer

Windows

The solution is simple, and works with sumatraPDF. Just add the following option to your configuration

"latex-workshop.view.pdf.external.synctex.command": "C:/Program Files/SumatraPDF/SumatraPDF.exe",
"latex-workshop.view.pdf.external.synctex.args": [
    "-forward-search",
    "%TEX%",
    "%LINE%",
    "-reuse-instance",
    "-inverse-search",
    "code \"C:\\Users\\<name>\\AppData\\Local\\Programs\\Microsoft VS Code\\resources\\app\\out\\cli.js\" -r -g \"%f:%l\"",
    "%PDF%",
],

Do not forget to set the paths according to your installation. You can also replace code with the Code.exe path.

Linux

This is trickier, but works. See here.

  1. Download this file (modified to work with VScode):

  2. Unzip it in any folder in your PATH (for instance, $HOME/bin/ or $HOME/.local/bin).

  3. Add the following options to your configuration:

    "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%"
],

Overview

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.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
latex-workshop.synctex.synctexjs.enabled Enable using a built-in synctex function. true boolean

Relevant Settings

latex-workshop.latex.outDir

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 recipe, 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 %DOC%, %DOCFILE, %DIR% and %TMPDIR% can be used.

type default value
string "%DIR%"

latex-workshop.synctex.afterBuild.enabled

Execute forward synctex at cursor position after compiling LaTeX project.

type default value
boolean false

latex-workshop.synctex.path

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"

latex-workshop.view.pdf.external.synctex.command

The command to execute when forward synctex to external viewer.

type default value
string ""

Note: this function is not officially supported.

latex-workshop.view.pdf.external.synctex.args

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%" ]

latex-workshop.synctex.synctexjs.enabled

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

latex-workshop.view.pdf.viewer

The default PDF viewer.

type default value
string "none" | "browser" | "tab" | "external"
  • "none": Undetermined viewer. A viewer selector will pop up upon viewing PDF.
  • "browser": Open PDF with the default web browser.
  • "tab": Open PDF with the built-in tab viewer.
  • "external": Experimental Open PDF with the external viewer set in "View > Pdf > External: command"

latex-workshop.view.pdf.ref.viewer

PDF viewer used for [View on PDF] link on \ref.

type default value possible values
enum "auto" "auto" | "tabOrBrowser" | "external"

latex-workshop.view.pdf.external.viewer.command

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",

latex-workshop.view.pdf.external.viewer.args

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%"
    ],