Build Document
There are currently two approaches to dealing with building your LaTeX document with this extension (other than running in external terminal):
- via
texlab - 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:
One could also build in a docker container as discussed at the end of Build Document.
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).
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.
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.
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.
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.
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".
If you have
latexmkon 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.
tectonic:
// ~/.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"
]
}
}
}
}
}
}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.
Screencast.from.2024-11-15.17-10-54.mp4
Alternatively you can also view the .log file for the build (likely in the same directory), or tail -f FILE.log in the terminal.
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".
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
latexmkon 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.
Forwards search can also be set up via tasks instead of via texlab. The benefit here is the ability to add a keybind and also get more accurate forward search compared to on-save via texlab. Here is an example for skim (MacOS) which could be adjusted with the help of the "Preview" page:
{
"label": "Forward Search",
// The following makes the assumption that the output PDF is in the same directory and has the same base name as the current file:
"command": "/Applications/Skim.app/Contents/SharedSupport/displayline -r -z -b $ZED_ROW $ZED_DIRNAME/$ZED_STEM.pdf",
// alternative with file name hardcoded:
// "command": "/Applications/Skim.app/Contents/SharedSupport/displayline -r -z -b $ZED_ROW $ZED_DIRNAME/filename.pdf",
"allow_concurrent_runs": false,
"reveal": "no",
},At this point, this task could be given a keybind:
// ~/.config/zed/keymap.json
// ...
{
"context": "Workspace",
"bindings": {
"shift shift": ["task::Spawn", { "task_name": "Forward Search" }]
}
}
]These tasks are not currently provided by this extension as it is difficult to create a robust solution which works in situations with multiple files and projects with extra latexmk settings or (pdf/lua)latex arguments altering the basename and location of the PDF output.
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).