This project is no longer maintained and — in light of the fact that the Atom editor will be sunset on December 15, 2022 — has therefore been archived. If you wish to keep writing LaTeX documents in Atom and need new functionality, either fork this package or use another package that provides whatever functionality you desire.
LaTeX package
Compile LaTeX, knitr, literate Agda, literate Haskell, or Pweave documents from within Atom.
Installing
Use the Atom package manager and search for "latex", or run apm install latex
from the command line.
Prerequisites
TeX distribution
A reasonably up-to-date and working TeX distribution is required. The only officially supported distributions are TeX Live, and MiKTeX. Although, the latter is not as well tested and supported as TeX Live, hence using TeX Live is highly recommended.
You need to ensure that the package can find your TeX distribution's binaries;
by default the package uses your PATH
environment variable, as well as the
following search paths on Linux and macOS
/usr/texbin
/Library/TeX/texbin
and on Windows it uses
%SystemDrive%\texlive\2017\bin\win32
%SystemDrive%\texlive\2016\bin\win32
%SystemDrive%\texlive\2015\bin\win32
%ProgramFiles%\MiKTeX 2.9\miktex\bin\x64
%ProgramFiles(x86)%\MiKTeX 2.9\miktex\bin
If your TeX distribution's binaries are not installed in one of those locations
or discoverable via the PATH
environment variable, you will need to help the
package find the binaries. This can be done by setting the TeX Path
configuration option to point to the folder containing the binaries, either in
the settings view, or directly in your config.cson
file. See Configuration
for further details regarding the settings of this package.
Syntax Highlighting
In order for this package to behave as expected, your Atom environment must contain a package that provides a LaTeX grammar. We suggest language-latex, but other valid options might exist. Additional syntax packages may be required to build document types other than LaTeX. For more details see Builder Capabilities below.
Builder Selection
The latex
package provides access to two automatic builders for LaTeX and
knitr documents. By default the package will use latexmk
for LaTeX documents
and an included builder to prepare knitr documents for latexmk
. In this case
an up to date installation of latexmk
is required. If you're using TeX Live
then you need only insure that latexmk
is installed and up to date using the
appropriate package manager. If you're using MikTeX then see how to use
latexmk
with MiKTeX.
The JavaScript based DiCy builder may also be used for all documents by
selecting the Use DiCy
option in the settings page. DiCy will be installed
automatically and so no further action is required for either TeX Live or
MiKTeX.
Builder Capabilities
Document types other than LaTeX documents may be processed by this package. The availability and behavior of this feature depends upon the specific builder selected. The following table details the different types of documents that may be processed by each builder and any additional syntax package requirements.
Document Type | latexmk based Builder | DiCy Builder | Required Language Packages |
---|---|---|---|
LaTeX | Yes | Yes | language-latex |
knitr | Yes | Yes | language-r and language-knitr |
literate Agda | No preprocessing | Yes | language-agda |
literate Haskell | No preprocessing | Yes | language-haskell |
Pweave | No | Yes | language-weave |
Usage
The latex:build
command can be invoked from the LaTex menu or by pressing the
default keybind ctrl-alt-b while in a LaTex or
knitr file. Log messages and any other messages from the build may be seen in
the LaTeX log panel accessible from the status bar.
The latex
package supports other commands as detailed in the table below.
Command | Keybinding | Use |
---|---|---|
latex:build |
ctrl-alt-b | Build LaTeX/knitr file and open result. |
latex:rebuild |
None | Force a rebuild of LaTeX/knitr file. |
latex:clean |
ctrl-alt-c | Cleanup files after a build. |
latex:kill |
None | Terminate currently running build. Also available from status indicator. |
latex:sync |
ctrl-alt-s | Use SyncTeX forward if possible from the current cursor position. |
latex:sync-log |
None | Display and highlight log messages from the current cursor position. |
latex:check-runtime |
None | Check for the existence of latexmk , Rscript and PDF/PS/DVI viewers. |
Overriding Build Settings
Many of the build settings in the settings page of the latex
package can be
overridden on a per file basis. One way to override specific build settings is
to use "magic" TeX comments in the form of % !TEX <name> = <value>
. Another
way is to use a YAML formatted file with the same name as your root LaTeX
file, but with an extension of .yaml
. The settings and values that can
overridden via either method are listed in the table below. If multiple setting
names are listed then the first is preferred and following names are available
for compatibility. More details can found at Overridding Build Settings.
Name | Value | Use |
---|---|---|
cleanPatterns |
comma separated patterns, e.g. **/*.blg, foo |
Specify patterns to use for latex:clean |
enableSynctex |
yes , no , true or false |
Override SyncTeX setting |
enableExtendedBuildMode |
yes , no , true or false |
Override extended build mode setting |
enableShellEscape |
yes , no , true or false |
Override shell escape setting |
engine or program |
pdflatex , lualatex , etc. |
Override the LaTeX engine to use for build. |
moveResultToSourceDirectory |
yes , no , true or false |
Override move result to source directory setting |
outputFormat or format |
dvi , ps or pdf |
Override the output format |
jobNames , jobnames or jobname |
comma separated names, e.g. foo, bar |
Control the number and names of build jobs. Only a single name can be used for jobname . |
outputDirectory or output_directory |
directory path, e.g. build |
Specify the output directory that should be used. |
producer |
dvipdf , dvipdfmx , xdvipdfmx or ps2pdf |
Override the PDF producer |
openResultAfterBuild |
yes , no , true or false |
Override open result after build (not available for DiCy) |
root |
file path, e.g. ../file.tex |
Specify the root file that should be built. Only available via "magic" TeX comments. |
There are additional settings that may be configured for the DiCy builder that may not be accessible from this package's setting page, but can be set via a YAML options file or TeX magic comments. For more details please see Options and Configuration in the DiCy documentation.
PDF/DVI/PS Viewers
The latex
package currently supports Atril, Evince, Okular,
pdf-view, Preview, Skim, Sumatra PDF, Windows shell open,
xdg-open, Xreader and Zathura as PDF/DVI/PS viewers. This includes
support for cursor synchronization via SyncTeX if possible. Specific features of
each of the viewers is detailed at Supported Viewers.
Development status
Please note that this package is in a beta state. It is stable, but lacks some important features.
Any and all help is greatly appreciated!
NOTE: latexmk
does not support file paths containing special characters such as ~
. To partially circumvent this, add useRelativePaths: true
to your config file like so
# config.cson
"*":
latex:
useRelativePaths: true
When set, this package will use a relative path in place of an absolute one. This will allow latexmk
to compile projects stored in directories that contain special characters. Note that the project itself must not contain special characters in its directory or file names.
This feature has not been fully tested yet, and there are no guarantees it will work in all cases. Please raise an issue if you find a case where it fails.