Setting up Atom for LaTeX

latex_in_atom.md

Disclaimer: I wrote the packages language-latex2e, autocomplete-latex, latex-wordcount, and hyperclick-latex. I still try to provide a list of all useful packages though, so let me know if I have missed one.

This is a general guide for how to get started with LaTeX in Atom.

NOTE: This guide assumes you already have LaTeX installed on your computer. If you do not, I recommend TeX Live.

• Windows & Linux download page

• Mac download page

  • MacTeX is still TeX Live, just made easier to install on a mac. Please use the full version, disk space is seldom a problem these days.

In general, Atom packages will be simply acting as a "middleman" between the editor and third party programs. You will need to ensure these programs are on your computer already before expecting them to work. If you installed the full TeX Live installation, this should not affect you.

Table of contents

• Quick start
• Detailed walkthrough
  • About Atom
    • Some general notes
  • Getting LaTeX working
    • Compiling
    • Syntax highlighting
    • Snippets & autocompletion
    • Hyperclick
    • Spelling
    • Wordcount
    • Linting
    • Beautify
    • Other

Quick start

• Install Atom
• Install the following packages:
  • language-latex: syntax highlighting
  • latex: compiling
• Install any optional packages:
  • autocomplete-latex: autocomplete customised commands & snippets
  • latex-autocomplete alternative type of auto completion; they work differently and can be active together
  • latex-wordcount: estimate wordcount using TeXcount and wordcount.tex
  • latex-hyperclick: go to label declarations and follow file paths
    • Requires hyperclick
  • linter-chktex: lint the document
    • Requires linter & linter-ui-default
  • atom-beautify: auto reformat your source to improve spacing (does not affect output)
    • Requires some involved setup. See this overview
  • linter-spell-latex: spell check
    • Requires linter-spell. This requires further setup. See Spelling
  • pdf-view: open .pdf documents in Atom

Detailed walkthrough

About Atom

Loosely speaking, Atom is a text editor built on electron. It uses a modular design, splitting most features into individual "packages". The "core" of Atom, with all packages disabled, is extremely limited. Because of this, many functions that are expected of a text editor are provided by "core" packages, which are installed and enabled by default in a new installation. For example, find and replace functionality is provided by find-and-replace, and can be configured in the settings for that package. More on Atom's package system can be found in the flight manual.

Some general notes

Many packages require other packages to actually work with LaTeX. Examples of these include linter-spell, hyperclick, and autocomplete-plus. The idea is that these packages are language agnostic, and specific (distinct) packages such as linter-spell-latex, latex-hyperclick and autocomplete-latex provide the LaTeX support.

A common misconception is how snippets and autocomplete works. The relationship is laid out here:

• snippets is a core package that allows the user to give a list of prefix-snippet pairs. When the prefix is typed in the document, pressing tab replaces the prefix with the snippet body.

• autocomplete-plus is a formerly community package that makes a popup menu appear as you type a word. The default entries are words scraped from the current file, but packages such as autocomplete-latex add LaTeX specific entries to the list. When an entry is selected (by pressing tab or enter), the corresponding action associated with the entry is executed. In most cases, it will simply replace the current word with the body text of the entry.

• autocomplete-snippets is a core package that is a provider similar to autocomplete-latex. Instead of LaTeX completions though, it provides all the available snippets (intended for snippets) to the popup menu of autocomplete-plus. It does have some restrictions though:

  • It will not show snippets that have punctuation in them (punctuation is supported in snippets, just not by this package)
  • It will not provide the snippets if the current scope starts with .comment or .string. Currently in language-latex math mode is scoped to string.other.math, so snippets will never appear in the popup menu when in math mode. However, the snippets still work, as pressing tab after a valid prefix (such as it) will still replace the text.

It is easy to mistake the functionality of each package (I know I did!), but hopefully this makes it clearer. When using language-latex, snippets are provided automatically as part of the package. It does provide math snippets, but, as explained above, these will not appear in the popup menu with the other snippets. Instead, dedicated packages such as autocomplete-latex and latex-autocomplete should be used.

Getting LaTeX working

Compiling

• Note: I only have experience using latex to compile.

There are a few choices for compiling. The most used package by far is latex, and has worked well enough for me. It uses latexmk to automate runs, and also has the option to use a custom builder called DiCy. Just about everything seems configurable though, so no problems there.

A search shows another called latex-plus. However, it's GitHub page says

🚨 This project is no longer maintained. If you would like to take over ownership, please contact me via email. 🚨

so be careful when chosing one; making sure it is actively maintained is a good step to take with smaller packages.

There is another package called atom-latex, which says it does the following:

• Compile LaTeX with BibTeX
• Preview PDF with build-in viewer
• Parse LaTeX compiling log
• Autocomplete
• Syntax highlighting
• Direct and reverse SyncTeX

I haven't tried it, as I prefer to keep all this functionality modular. If a "one-package-deal" is what you like, it seems actively maintained enough.

Finally, another all-in-one package is latextools. It does not appear to be actively maintained (last commit Oct 2016 as of Jan 2018), and the issue backlog seems quite big. Like I said though, I've never tried it and am not interested in that type of package. If you like it, then by all means use it.

I won't mention these all-in-one packages in the following sections, as 1) I'm mentioning them here, 2) you can't selectively enable / disable any of the features, and 3) many of the following would be incompatible anyway.

Syntax highlighting

An important set of packages in Atom are the language packages. These provide syntax highlighting rules (called grammar in Atom). The core set of packages provide a language package for common programming languages such as JavaScript, C, HTML, and 30 others.

However, LaTeX is not one of these, so a community package must be installed. Searching language-latex in the Install tab in Settings, the top result should be language-latex.

Using language-latex (or a similar grammar package) is important. A problem you may face, especially if you don't use language-latex, is LaTeX packages not activating when they should be. This is due to a feature of Atom, called activation hooks. The idea is good: because Atom is used for many different languages, only the packages related to the current language should be activated. Activation hooks allow packages to tell Atom when they should be activated, preventing bloat when not editing in 30 different languages simultaneously. Unfortunately, the only currently available activation hook (that I am aware of) is on a per package basis. This means that LaTeX package authors must add a hook for each LaTeX grammar package, which is practically impossible, seeing as anyone can write a new grammar package for LaTeX.

• Note: to check if a package is activated, replace <package_name> with the correct name (what appears in the Setting/packages tab) and paste the following into dev tools console (View -> Developer -> Toggle Developer Tools):

!!atom.packages.getActivePackage("<package_name>")

When this happens, it is best to let the author of the grammar package know via an issue. They should then be able to open a PR on the relevant package, adding their own package to the list of activation hooks. If you want to fix it immediately, a quick solution (that will not be kept when the package is updated) is to navigate to .atom/packages/<package_name>/package.json. In here, look for an activationHooks entry. If present, it should look something like this:

"activationHooks": [
  "language-latex:grammar-used"
],

To add the grammar package you're using, add the following line, with the correct name (watch the commas; they're important!)

"activationHooks": [
  "language-latex:grammar-used",
  "<package_name>:grammar-used"
],

Snippets & autocompletion

As discussed in Some general notes, there is a difference between snippets and autocomplete.

language-latex comes with a set of snippets builtin. autocomplete-snippets will add these to the autocomplete-plus popup, but not in math mode. However, these snippets use normal letters as the completion prefix, to aid compatibility with autocomplete-snippets. This means that when you are typing normal text, the snippets will often appear in the popup menu.

If you don't want this, and also want autocomplete options in math mode, there are dedicated autocomplete providers to chose from. Some are general use, such as autocomplete-latex, while others are specific to some feature, such as autocomplete-latex-cite for bibliography citation completions.

• Note: If using language-latex, the snippets it provides will still appear and there is no way to properly disable them. Disabling autocomplete-snippets will work, but this will disable it for all other languages and user defined snippets as well. A quick fix is to delete the folder snippets in .atom/packages/language-latex/, but it will come back after another update.

In any case, here is a list of autocomplete providers. More can be found by searching the Atom package list

• autocomplete-latex: general LaTeX autocomplete
• latex-autocomplete: general LaTeX autocomplete
  • These two packages seem similar, but do somewhat different things. Use both together for the best experience. Both have settings that can be configured.
• autocomplete-latex-cite: complete's citation keys from the .bib file
• autocomplete-latex-references: completes keys that have been used in \label{}

I believe there are some snippet providers as well, but cannot find them currently. If you know any, please let me know.

Hyperclick

Another big package in Atom is hyperclick. It allows providers to perform certain functions when a word is clicked. For example, it is used by hyperclick-js to jump to a variable declaration.

For LaTeX, there exists two hyperclick providers.

• latex-hyperclick: the more featured one of the two. Click file paths inside \input{}, \include{}, etc. to open the corresponding file. It's README.md file also lists support for \ref and other statements.
• hyperclick-latex: a package I made before realising latex-hyperclick existed. It supports file path opening as well, but not \ref (yet). It does, however, open the documentation for a package or class when clicked (using the texdoc command line tool).

Spelling

There are a couple of options here. Atom comes with the core package spell-check, but it doesn't seem suited to handle LaTeX very well (see language-latex#124). This could change when a scope blacklist is introduced, but for now at least my preferred option is linter-spell-latex.

Getting this working does take some effort however. First, this package is actually a provider for the more general linter-spell. To get this working, you need an "Ispell compatible" program, such as GNU Aspell or Hunspell. I use hunspell, as I had some issues with setting up aspell. If you pick aspell, replace hunspell with aspell in the following steps).

• If you're using macOS, I suggest installing one or the other via homebrew. Suggestions for Linux and Windows alternatives are appreciated.

After installing the program, test that it works in the command line by running hunspell -v (or aspell -v). Once confirmed, run the command which hunspell. Copy and paste the resulting path into the Spell Path setting of litner-spell.

• Note: for Windows users, I don't know the equivalent commands for command prompt. You do not need to download a command line program though, just find the executable path somehow.

Now linter-spell is fully setup. However, the package itself is a provider for linter, so make sure you install that package as well. Additionally, linter-iu-default is required to actually see the results in the user interface.

If all went well, the next time you edit a .tex file it should underline misspelt words, while ignoring commands and other parts that shouldn't be checked.

Wordcount

As far as I know, the only LaTeX sensitive wordcount package is my own latex-wordcount. It's still incomplete, but it does provide a couple of counting techniques. The first is with TeXcount, which comes with a default TeX Live install. The other is with wordcount.tex. More information can be found on the package's page.

Linting

Another tool present in the default TeX Live installation is ChkTeX. It lints the file, providing a list of possible errors in the source. The package linter-chktex can be installed to add this in Atom.

This package does require linter to work. Again, linter-iu-default is required to see the results.

Beautify

atom-beautify provides a way to "beautify" your source, that is, change the spacing to be more consistent and align better. The package itself has no requirements, but LaTeX support is not entirely present by default. It relies on the Perl script latexindent.pl, which comes with TeX Live. You need to get this working in the command line before it will work in Atom.

I did get it working at one point in time, but am unable to right now. I will update with any changes.

Other

This guide is by no means exhaustive. New packages are being added all the time, so the best way to check LaTeX related stuff is to do a search, perhaps with another keyword or two to narrow the scope.

For example, I see a package called latex-tree, which makes a document tree with your section names. It could be useful.

If there are any questions or clarifications, please ask. I don't know what you don't know until you tell me. This document is aimed at someone with any level of LaTeX and general computer knowledge, who's looking to setup Atom to suit their needs.

Christ on a Bike! thank you ser @mjrodgers Be nice to see a dotfile implementation of this pain in the 🍑

There's also built-in support for docker and conda.