Using Tectonic with VS Code

[ujjwal123123]

I have been using Tectonic from terminal itself, manually entering compilation commands and editing with files with gedit. But since VS Code has great extension like TexLab and LaTeX Workshop, I wanted to try it and could not get those extensions to work with Tectonic.

It would be helpful if someone could share instructions for configuring one of these extensions to work with Tectonic.

[Jarmos-san]

EDIT: So, after taking a look at this answer I wanted to update my workflow to adhere to tectonic's v2 interface as well. This answer is an attempt to do so & if you would like to check out the older v1 way of doing things, see this answer (comment).

Creating a Base to Start Working From

You should generate a base work environment by invoking the tectonic -X new command. It should create the follow directory structure:

.
├── src
│   ├── _preamble.tex
│   ├── _postamble.tex
│   └── index.tex
└── Tectonic.toml

You'll figure out the significance of the .tex files eventually. But it's important to pay special heed to the Tectonic.toml file since this is what'll help tectonic with the file names! The file names are also important without which Latex-Workshop willn't function properly.

That said, here's a bare minimum Tectonic.toml file:

[doc]
name = "example-book"
# The following bundle will be generated automatically by the "tectonic -X new" command. DO NOT change it!
bundle = "https://some-remote-url.tar"

[[output]]
# DO NOT change! The VSCode plugin mightn't work as expected if you do so.
name = "index"
type = "pdf"

You can update & modify the file as per your needs by referring to the official documentations on the Tectonic.toml file.

NOTE: It's IMPORTANT you don't change the value of output.name unless you know what you're doing. Else Latex-Workshop won't open the in-built PDF viewer properly, more on it in a later section.

Update the Contents of the Generated .tex Files

The .tex files tectonic generates is a good starting point for us to start with. You can read up more on the tectonic -X new command in it's official documentations. The documentations speaks of a "suggested framework".

Following the framework means, you needn't maintain an individual preamble.tex file & then \include them in a main.tex file (see "Module Documents"). \include is known to break workflows & is prone to errors which are difficult to fix especially for modular project structures.

But fortunately, tectonic takes care of those issues! Hence, all you need is a single command - tectonic -X build to compile your PDF file.

Configuring VSCode to Use tectonic

To use Latex in VSCode, I personally suggest using Latex-Workshop because of how feature-full it is. The alternative is TexLabs which isn't as feature-full but provides better LSP than Latex-Workshop.

That said, following are the VSCode configurations you need to copy-paste into your settings.json file:

  "latex-workshop.latex.recipe.default": "tectonic",
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%/build/index",
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.latex.recipes": [
    {
      "name": "tectonic",
      "tools": ["tectonic"]
    }
  ],
  "latex-workshop.latex.tools": [
    {
      "name": "tectonic",
      "command": "tectonic",
      "args": ["-X", "build", "--keep-intermediates", "--keep-logs"],
      "env": {}
    }
  ]

The "latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%/build/index" settings requires special attention here. Remember when I mentioned not to change the value of output.name in the Tectonic.toml file? It;s because of this VSCode setting which enables the plugin to search for the compiled .pdf file in the right place.

That said, at the end of the day when you're draft is complete, Press the compile button in VSCode & find the index.pdf file under the build/index directory. Rename the file to something more apt & you're good to go!

The updated answer turned out to be lengthier than I expected but I hope it helps you guys out there to use VSCode & LaTex for writing your PhD thesis! 😅

CREDITS: Thanks to @LeCyberDucky for sharing his configurations which makes use of the v2 interface of tectonic. I updated this answer (and my current workflow) by taking inspirations from his config.

[albertothedev]

@Zeta611

I have since switched to Typst 😅 but I am sure your detailed answer will help someone else.

[Zeta611]

@albertothedev Hey, from genuine curiosity, why did you switch to typst? I've been thinking to try it--is it usable to produce high quality documents?

[albertothedev]

@Zeta611

Depends on what you mean by "high-quality documents". I suppose you are talking about document complexity, but that is a very broad spectrum even before accounting for features provided by packages so I can't give you an answer.

Typst is currently on major version 0 so expect frequent breaking changes. It has a passionate and ambitious community, so expect huge improvements too. I see that you speak Korean and I have seen some bugs with certain languages so you might run into some yourself. I have also seen that you're plenty familiar with LaTeX. Knowing those too things it's up to you to decide whether you are willing to give it a chance or would prefer waiting for a 1.0 release.

[Zeta611]

@albertothedev Thanks a lot for the detailed answer. I really appreciate it 😀

[eljamm]

I'd like to thank everyone who has contributed to this discussion for helping me set up Tectonic in VSCode and I'd just like to add a small improvement to @Zeta611's answer.

Imagine you have two documents that use the same _preamble and _postamble.

[[output]]
name = "english"
index = "english"
type = "pdf"

[[output]]
name = "german"
index = "german"
type = "pdf"

Building this project results in the following structure:

build/
├── english
│   ├── english.pdf
│   └── ...
├── german
│   ├── german.pdf
│   └── ...
└── index

However, trying to open a PDF file from the LaTeX previewer results in the following message:

Cannot view file PDF file. File not found: file:///home/user/project/build/index/english.pdf

To solve this, instead of hardcoding the output directory in LaTeX Workshop, we can change it to dynamically point to the document name:

-  "latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%/build/index",
+  "latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%/build/%DOCFILE%",

This matches Tectonic's output directory using the output.name in the Tectonic.toml.

In this example, this means that the LaTeX previewer will look for the following documents:

file:///home/user/project/build/english/english.pdf
file:///home/user/project/build/german/german.pdf

As @Zeta611 explained, though, we need to specify % !TEX root for each document first or the previewer will look for _preamble, instead:

%% Inside src/english.tex:

% !TEX root = ./english.tex
Hello, world.

%% Inside src/german.tex:

% !TEX root = ./german.tex
Hallo Welt.

In conclusion, using %DOCFILE% for the outDir gives more naming flexibility and correct PDF previewing for both single and multi-output projects.

[LeCyberDucky]

Here's my configuration with VS Code and LaTeX Workshop. My document structure doesn't fit the default Tectonic structure, so I'm using the compile command for building. Also, I'm doing one initial run to get rid of warnings about undefined citations. This keeps some intermediate files around that I'm not a fan of, so I'm still trying to figure out how to get rid of those.

"latex-workshop.latex.autoBuild.cleanAndRetry.enabled": false,
"latex-workshop.latex.autoBuild.run": "onSave",
"latex-workshop.latex.recipe.default": "tectonic",
"latex-workshop.latex.recipes": [
    ...
    {
        "name": "tectonic",
        "tools": [
            "tectonic-biber",
            "tectonic"
        ]
    }
],
"latex-workshop.latex.tools": [
...
    {
        "args": [
            "-X",
            "compile",
            "%DOCFILE_EXT%",
            // "-Z",
            // "shell-escape",
            "--synctex",
            "--print"
        ],
        "command": "tectonic",
        "env": {},
        "name": "tectonic"
    },
    {
        "args": [
            "-X",
            "compile",
            "%DOCFILE_EXT%",
            "-k",
            "--reruns",
            "0"//,
           // "-Z",
            // "shell-escape" // Don't include shell-escape, unless you have a very good reason for doing so
        ],
        "command": "tectonic",
        "env": {},
        "name": "tectonic-biber"
        // See: 
        // https://github.com/tectonic-typesetting/tectonic/issues/195
        // https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#latex-recipes
        // https://github.com/James-Yu/LaTeX-Workshop/wiki/FAQ#suggestions-for-bibtex-files-are-not-updated
    }
],
"latex-workshop.latex.watch.usePolling": true,
"latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
"latex-workshop.view.pdf.viewer": "tab",

[Jarmos-san]

Thanks for sharing you configuration! I'll update my answer so that it adheres to the v2 interface of tectonic.

Besides, a heads up for the unwary, you might not need to pass the -Z shell-escape flags to tectonic if you're ensure of what it does. Be ABSOLUTELY sure you want to run arbitrary Shell commands in your LaTex files before using those flags. For more information on this, check the following resources:

• The "unstable options" of the tectonic -X compile command.
• The unofficial docs on \write18 to understand how you can invoke arbitrary Shell commands within LaTex files.
• An example of how, where & why to use \write18 within your LaTex files.

[LeCyberDucky]

Thanks for the heads up. You make a good point, but in my case I do need shell-escape. I'll update my reponse to remove it, though, in case somebody copies it without thinking about that line.

[ratmice]

Also note that for the V2 interface IIUC shell-escape can be enabled in the Tectonic.toml It'd be nice to eventually hook into the trusted/untrusted workspace settings of vscode to pass this flag.

I believe trusted is the default unless --untrusted is specified, but I should probably check that.

[Jarmos-san]

NOTE: I updated my workflow to adhere to tectonic's v2 interface just a while ago & as such I'm updating the original answer with the updated configuration & and explanation. This new comment here is kept for historical & reference purpose. So, if you want to check the latest configuration, check out this answer (comment).

The Old Answer:

Having using both TexLab & LaTex Workshop, I can confidently suggest using the later even though the former's LSP suggestions & highlight is the best!

LaTex Workshop did a great job at documenting it's features, is prompt when responding to issues/queries & the plugin is VERY feature rich. You almost won't need the command-line at all if using the plugin. So, I suggest reading their documentations in case you want to work with LaTex frequently on VSCode.

But regardless, I believe you need to have these properties in your settings.json:

  "latex-workshop.latex.recipes": [
    {
      "name": "tectonic",
      "tools": ["tectonic"]
    }
  ],
  "latex-workshop.latex.tools": [
    {
      "name": "tectonic",
      "command": "tectonic",
      "args": ["%DOC%.tex", "--outdir", "%OUTDIR%", "--synctex"],
      "env": {}
    }
  ],
  "latex-workshop.latex.outDir": "build",

P.S: Read more about "latex-recipes" & "latex-tools" before customising your VSCode-LaTex experience.

[danmackinlay]

Minor quibble: AFAIK the recommended way to write `"%DOC%.tex" is in fact "%DOC_EXT%".