The in-progress LaTeX plugin for Sublime Text 2

EDITED 3/26: fixed URLs to reflect the new ‘official’ SubimeText packages repo / organization.

I have been pretty quiet the last couple of weeks. The main reason is that I was working hard to meet a deadline (which I did, sort of). However, I have also finally begun porting my LaTeX plugin for Sublime Text to the new, awesome, cross-platform v. 2.0 of said amazing text editor. Mind you: Sublime Text 2 (ST2 for short) is still in the alpha stage, and so is my ported plugin. On the other hand, I have been using ST2 as my sole text editor for the past two weeks, tweaking and porting the essential features of the LaTeX plugin as I needed them. It has served me well.

Thus, if you like living on the edge, you can get the ST2 alpha version here; or, if you are really adventurous, grab the latest dev build here. Then, head over to the LaTeXTools public GitHub repository; hit the “Downloads” button to get a .zip file of the current version; you will get a silly name like (the final part of the file name will change: it’s part of the hash code of the latest commit I pushed to github). Expand this to a folder, which will be aptly called something like msiniscalchi-LaTeXTools-38ddb5f. Rename this folder to something sane, such as LaTeXTools but NOT just LaTeX (read on), and drop it in ST2’s Packages directory, which you can open from ST2 itself by selecting Preferences|Browse Packages (the exact location of these menu items varies by OS).

An important caveat: the new plugin is designed to coexist with, not replace, the existing snippets, language definitions, etc., that can be found in the LaTeX folder that comes with ST2 (in the Packages) directory. This is the reason why the plugin folder must be names something other than LaTeX. Also, of course you must not erase the existing LaTeX folder.

I am pretty excited about the plugin! It’s certainly not complete, and must currently work around limitations imposed by the fact that the ST2 alpha still lacks certain features that ST1 had (for instance, quick panels). On the other hand, ST2 brings a lot to the table, and the plugin attempts to use the built-in features of ST2 whenever possible; the best example is the use of the Completions API to handle references and citations, and of .sublime-completions files to handle quick LaTeX macro insertion. As a guiding principle, whereas the LaTeX plugin for ST1 tried to be very TextMatey, the LaTeX plugin for ST2 will be more… well, Sublime 🙂

I will blog about specific features of the plugin later. However, if you want to kick the tires, so to speak, here’s the bare minimum you need to know.

  • On Windows, the plugin uses MikTeX and the Sumatra PDF previewer, just like ST1. Both must be installed, and Sumatra must be on the PATH. Check your environment variables.
  • Recent versions of Sumatra allow you to set up inverse search from the GUI. You need to do so before you can use this feature. Go to Settings|Options, and under “Set inverse search command line”, enter sublime-text "%f":%l
  • Similarly, on the Mac, you use MacTeX and the Skim previewer. To set up inverse search, go to Preferences, select the Sync tab, choose Custom from the Preset drop-down menu, and enter subl in the Command field and "%file":%line in the Arguments field. Also make sure the Check for file changes box is not checked (same as for TextMate).
  • To compile a tex file, use the ST2 build system, which you invoke with F7 on Windows and Cmd-B on the Mac. The build will start, and if there are n errors the PDF viewer will be shown.
  • When you recompile (again, with the Build command), the PDF file will be automatically refreshed, but will stay in the background.
  • To use forward search (i.e. jump from tex to pdf), use shift+alt+j on Windows and shift+cmd+j on the Mac. For inverse search, double-click (Sumatra) or shift-cmd-click (Skim) at the relevant position in the pdf file.
  • For the time being, after compiling, the PDF file is either opened on page 1, or else refreshed; you do not automatically move to the page corresponding to the current position in the tex file. This is the same behavior as the ST1 LaTeX plugin, but it is different from TextMate’s behavior. I’ll fix this later.
  • Two PDF-viewer caveats: on Windows, if you try to use forward search but haven’t installed Sumatra, ST2 will crash. On the Mac, if you have Skim running without any windows open, and you try to compile a file or view the current PDF file (with ctrl+opt+v), nothing will happen. Close Skim and try again. Again, it’s something I need to fix.
  • Check the .sublime-keymap file for your platform (in the directory where the new LaTeX plugin lives) to figure out other key bindings, or change the existing ones.
  • A quick primer on the new features: references are inserted by typing ref and then hitting ctrl+space (the ST2-standard long completion key combo). This shows a drop-down menu with all possible references. But, if you know the reference you are looking starts with, say, `sec’, you can type ref_sec, then hit ctrl+space: now only references starting with `sec’ will be shown! Citations work similarly: e.g. type cite_myer and all citations with `myer’ either in the key or the title will come up. There are many more features (and a couple of caveats): you can check the comments in the and files to get an idea, but again, I’ll blog about them later.
  • In math mode, you have access to many convenient shortcuts (completions): e.g. type a, then hit TAB: you get \alpha. In text mode, you get other completions: e.g. bs expands to \bigskip. Note that, for instance, it expands to \mathit in math mode, and to \textit in text mode. Also, you can cycle among certain LaTeX commands. Check the LaTeX.sublime-completions and LaTeX math.sublime-completions for a human-readable list of available shortcuts.

That’s about it for now. Again, it’s all alpha quality, but I have been using the ST2+Plugin combination as my sole LaTeX editing `solution’ (hate that word…) for a couple of weeks, and it is serving me well so far. How’s that for dogfooding?


20 responses to “The in-progress LaTeX plugin for Sublime Text 2

  1. Absolutely fantastic work! Not only is ST2 an even better editor than its predecessor, your package is much improved as well. Thank you very much.

    That said, is there any way to make the citation lookup case insensitive?

  2. Oh, and if I may be so bold to ask for even more features, is there any way to auto-complete “” on elements that take overlay specifications (like \item, \alert, etc.), perhaps with some sane default option already between the brackets?

  3. Thanks Tobias! Both suggestions seem doable. Right now “i” auto-completes to “\item”, but maybe “io” could autocomplete to “\item” with the # selected. Would this work for you? (“o” is just the first thing that came to mind: it suggests “overlay”).

  4. Oops, apparently WordPress ate some of my last comment.

    What I meant wasn’t a tab-triggered snippet to for an \item with an overlay specification. Very seldom do I know I want an overlay spec when I type out the \item, so such a snippet would be of limited use, at least to me. More often I add it at some later point.

    Obviously I have no idea if ST2 is flexible enough to allow for such extremely context-dependent behavior, but what I think would be handy is bracket matching of the smaller-than sign with the larger-than sign (and possibly some default #) when typed after LaTeX commands that can take overlay specifications.

    • Ah. OK. Yes, bracket matching per se is not a problem; the question is whether it can be made scope-specific so it doesn’t get triggered when it makes no sense. I’ll look into it.

  5. I have problems with the cite completion. I know it’s not the best way to handle the bibliography, but I often have drafts where the bibliography is directly in the paper between \begin{thebibliography}{99} and \end{thebibliography}.
    It is not difficult to correct your script, but it would be nice if you could commit the change.

    • Ciao Pippo,
      You are right of course. Right now the plugin simply doesn’t support in-file bibliographies. It’s on my to-do list. I hope to have more time next month to add new features such as this. Please hang in there!

  6. silvio mercadante

    I’m so sorry for such a dummy question (actually I met ST for the very 1st time just few hours ago…): you Marciano wrote “on the Mac, you use MacTeX and the Skim previewer. To set up inverse search, go to Preferences, select the Sync tab,…” Well, I can’t find the Sync tab.
    Under Sublime Text 2 > Preferences I can see “Browse Package…”, “File Settings – Default/User/More”, and a few others, but no Sync stuff. I’m apparently looking in the wrong place…

    Could you be so kind to point me in the right direction?

    Grazie, ciao


  7. I meant the Preferences menu option for Skim, not Sublime Text… sorry if I wasn’t clear about this.


  8. silvio mercadante

    Thank you Marciano. 😉


  9. Do we need Skim to use this? I’m trying to use this on my mac and Preview is my primary PDF viewer. When I build the project, everything builds properly and all of the output files are created including the pdf file, but the pdf doesn’t open automatically. Do I need to install Skim? And if I do, will it just work on its own after I install Skim, or do I have to configure something else?

    • You do need to install Skim. The reason is that Preview does not support forward or inverse search, which for most users (me included!) is an essential feature [if you have never tried, trust me, you’ll love it!]

      After installing Skim, follow the instructions in the plugin’s README file to configure inverse search. Happy TeXing! M

  10. Just want to say: THANK YOU!

    Fantastic work – I use Sublime Text and your LaTeXTools on Windows7/64bit with TexLive 2011 and on MacLion with MacTex without any problems so fare.

  11. Would the plug-in work for Linux/Ubuntu? Does it need anything special?

  12. Hi, thanks for the plugin. It works well, I’m able to search from sublime to skim, however I can’t figure out how to do a reverse search. Cmd+Shift+Click does not work for me. (I’m mac user) Any suggestion?

  13. Hello,

    First thanks for this awesome plugin, I feel like before that I was coding like a caveman.

    I suggest you to add /opt/local/bin to the path in sublime-build for Mac OS X. It’s the default path for LaTeX binaries when installing LaTeX using Macports.

  14. Hi!
    Is it possible for ST to auto indent latex codes? I would for instance like my \item’s to indent once, and \end{enumerate} to indent back automatically.
    Thanks in advance!

  15. Hello! I understand this is kind of off-topic but I had to ask.

    Does managing a well-established website such as yours require a massive amount work?
    I am brand new to operating a blog however I do write in my diary on a daily basis.

    I’d like to start a blog so I can easily share my personal experience and views online. Please let me know if you have any ideas or tips for brand new aspiring blog owners. Appreciate it!

  16. Pingback: The best Latex Editor for MAC | 郭大侠

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s