There are currently two approaches to dealing with building your LaTeX document with this extension (other than running in external terminal):

• via texlab (which is configured automatically when a suitable PDF viewer is detected)
• via Zed tasks

Reminder from the Home page:

Installing this Zed extension will not install any LaTeX distribution, which is necessary for building LaTeX documents. These can be found here:

• https://tug.org/texlive/
• https://miktex.org/
• https://tug.org/mactex/

One could also build in a docker container as discussed at the end of Build Document.

Build via texlab

With texlab, you adjust some settings to make the language server run a build with your specified command whenever a relevant file is saved in Zed. The main benefit of this approach is that it works well with previewing and forwards+inverse search (see Preview page). This is because texlab is quite reliable at locating the PDF output. The downside is that due to limitations in the Zed extension API and user configs, there is no way to send the custom "build" request to texlab on, say, a user keybind. This means that building via texlab can only be done on save which is achieved by setting "lsp.texlab.settings.texlab.build.onSave" to true. One downside of this is that texlab is not always able to determine the cursor location accurately when notified about the save, to the forward-search can be inacurate (related to Zed limitation mentioned above).

[!TIP] In a workspace with multiple directories, adding a .texlabroot file next to the main LaTeX file will make the build command run in that same directory.

Autoconfig

Currently, in order to improve the out-of-the-box experience for most users, this extension specifies user settings when a suitable PDF viewer is found, to set up build-on-save and forward-search-on-save (and inverse search too when possible). This is however not done if it overrides any explicitly specified user settings.

Disable autoconfig

In particular, setting "lsp.texlab.settings.texlab.forwardSearch" to {} will disable this autoconfig; alternatively setting "lsp.texlab.settings.texlab.build.onSave" to false will have the same end-user effect.

Explicitly, having this in your Zed settings will remove build+preview on save:

{
  // rest of your settings
  "lsp": {
    "texlab": {
      "settings": {
        "texlab": {
          "build": {
            "onSave": false
          }
        }
      }
    }
  }
}

Adjust autoconfig

If you are happy with build-on-save but want to adjust the build command, you can adjust settings as specified in the "configure the build command" section. If you want to keep build-on-save but stop the forward-search (preview) on each save you can set "lsp.texlab.settings.texlab.build.forwardSearchAfter" to false.

Configure the build command

To control the command to build the document (default is latexmk), you can change the Zed settings "lsp.texlab.settings.texlab.build.executable" and "lsp.texlab.settings.texlab.build.args".

[!TIP] If you have latexmk on path and just want to adjust something like the latex compiler (pdflatex/lualatex/...), output location, aux file location... you may want to consider adding a latexmkrc file next to your main LaTeX file to specify these things instead of touching any Zed settings.

Tectonic example

// ~/.config/zed/settings.json
{
  "lsp": {
    "texlab": {
      "settings": {
        "texlab": {
          "build": {
            // "onSave": true,
            // "forwardSearchAfter": true,
            "executable": "tectonic",
            "args": [
              "-X",
              "compile",
              "%f",
              "--untrusted",
              "--synctex",
              "--keep-logs",
              "--keep-intermediates"
            ]
          }
        }
      }
    }
  }
}

Build logs

When diagnosing build errors and warnings, the diagnostics in the editor (relayed by the language server) are a convenient first help. But for certain failures where the diagnostics are not helpful, you can find the output from the build command by searching "debug: open language server logs" and choosing "texlab" in the dropdown. A current downside is that Zed does to autoscroll to the bottom with these log files, making it harder to keep track of ongoing builds.

https://github.com/user-attachments/assets/2d0e1ae0-b544-46ca-a390-8cbbfde04e02

Alternatively you can also view the .log file for the build (likely in the same directory), or tail -f FILE.log in the terminal.

Build via Zed tasks

There should be a "run" button in your main LaTeX file with options of Zed "tasks" to build your document:

You may also add your own tasks to appear here with a custom build command by providing a Zed task in a tasks.json file (see zed tasks docs) with the tag "latex-build".

Customise build command

Here is an example from this extension which you can adjust:

[
  //...
  {
    "label": "latexmk",
    "command": "latexmk",
    "args": ["-synctex=1", "-pdf", "-recorder", "$ZED_FILENAME"],
    "cwd": "$ZED_DIRNAME",
    "tags": ["latex-build"]
  },
  //...
]

Here is a reminder from earlier on this page:

If you have latexmk on path and just want to adjust something like the latex compiler (pdflatex/lualatex/...), output location, aux file location... you may want to consider adding a latexmkrc file next to your main LaTeX file to specify these things whilst not touching any Zed settings.

Build on keybind

If you launch a task in Zed (such as one of the tasks mentioned above for building the LaTeX document), you can rerun the last task with alt-t. If you only use one task, then this could be used as the "build LaTeX document keybinding".

Alternatively, a benefit of the tasks approach is that one can define custom keybindings for tasks. Don't forget to disable build-on-save through texlab when doing this.

For example, if you want to run the "latexmk" task provided by this extension when pressing F5 you can use the following:

// ~/.config/zed/keymap.json
[
// ...
  {
    "context": "Workspace",
    "bindings": {
      "f5": ["task::Spawn", { "task_name": "latexmk" }]
    }
  }
]

Build in "dev"-container

If the reader prefers using a docker container to build the document instead of installing a LaTeX distribution, there is a template demonstrating this (requires docker, or podman with some alterations).