[Solved] Creating a new package for a custom language in Atom


Hi! I’ve been using atom for awhile, and recently thought to try and add a new language with the package system. As far as I can tell, every search against the Atom docs simply directs me to the general information on packages page.

Most threads I’ve seen so far require the use of TextMate “bundles”. This would be fine, but the TextMate documentation on the subject is also… questionable, to put it lightly. The instructions are outdated (I believe they were designed for TextMate 1) and attempting to follow them in any way has failed, with the system deleting large chunks of text or simply failing to find the options listed.

As such, I am left with no options (most threads on the topic are pretty old and either link to the outdated TextMate docs or the nonexistent Atom docs). If there are any possible links to help or information that isn’t at least 3 years old and using a version of TextMate literally unusable for current operating systems, I’d love to know. Thanks!


You can view the list of all core language packages at https://github.com/atom/atom/blob/master/docs/build-instructions/build-status.md#languages. I have a WIP tutorial for how to write one at https://github.com/atom/flight-manual.atom.io/blob/7f11d44a3a618db2b0d79f2d5dc63d32ad85bb82/content/hacking-atom/sections/creating-a-grammar.md.

Some good ones to look at are language-coffee-script, language-java, language-javascript, language-html, language-php.

If you have any questions, feel free to ask.


I made a cheat sheet for myself back when I was learning how grammars worked.



I am interested in your project and efforts -
Please… for which grammar do you hope to provide for?

You have heard from the two individuals that is worth listening to when it it comes to grammars. Just to make it seem like a party, I’ll put down some additional notes from a non-expert perspective. (wink)

I have found the notes from @DamnedScholar very helpful. He has been very helpful to me in developing my own grammar. Please see the topics:
(open) Making a custom Assembler type grammar work comfortably in Atom

Ask about making my package (user) configurable?

The tutorial linked to by @Wliu aims to close the gap when it comes to documenting how grammars are defined. (I wish I used these notes.) Your feedback on these notes will be highly appreciated (thank you).

Much of the TexMate V2 notes that you find are still relevant. I recommend you start reading this very helpful blog to get an overview: [xx]

I also used the following notes:

There goes a lot of energy into developing the right regular expressions. Put special focus on understanding how these are written down for the grammar.


  1. Try to keep with the Standard Scopes (see blog xx).

  2. There is a order in how the match is made. For the top order it is first-come-first-served. (see blog xx for details)

Have fun exploring grammars.
- Dan


And @danPadric as well, since new users can only quote 2 users in one post.


Hello everyone,
Massive thanks for all of your help! The project is going smoothly, and I will hopefully finish it within the month. My sincere gratitude to everybody for their contributions (I’m pretty new to atom)!

Oh, and the language in particular was really nothing special, a weird kind of pseudo-assembly for a virtual machine I was messing around with (Only 10 opcodes, pointer operated register machine, a dime a dozen).

@Wliu @DamnedScholar


That tutorial looks really useful. I had the same experience as @UtilityHotbar — my experience with writing a syntax highlighting package involved ages of just looking for a guide on how to get started (the flight manual didn’t have your tutorial then). I eventually found several of the links given here, but it was a real struggle to understand everything and get started.

Of course, now that I know more about packages, CSON, and regex I look back on my strugle and think “wow, all the answers were right in front of me, how did I not see it?”. The problem, though, was I didn’t know what I was looking at. Existing language packages looked like jargon, being full of alien looking strings of characters (more commonly known as regex). Especally ones that had been converted from textmate, as they had spurious \t and \n's that had not been properly converted (so much of it looked like gibberish). Other forum posts / guides all pointed me to the textmate manuals, which totally baffled me. I wanted to write one for atom, not some other program.

Not knowing that the “syntax highlighting package” I was trying to make was actually called a “grammar package” (by those in the know) also didn’t help. I had no idea there was a distinction between the highlighting and the labelling of how each part should be highlighted.

I think now I would still get stuck (initially) if writing one with no prior experience. However, in desparation, I would read the entire flight manual, and see that the “creating a grammar” section has something that looks like what I want. This is the documentation that was missing when I tried to make one my first time, and should be a very big help to future grammar writers. Of course, LaTeX sucks to write grammars for anyway, but that’s a different issue.


Thanks for the feedback! We’re actively trying to improve Atom’s documentation :slight_smile:. The grammar tutorial is now live at http://flight-manual.atom.io/hacking-atom/sections/creating-a-grammar/ in WIP form. Now if you search for “syntax highlighting” (or similar) it does show up in the list of results.

Unfortunately that \t\n gibberish is an apm conversion bug because it literally converts the file instead of taking some beautification liberties :/.


Thanks for the good work, @Wliu! I’ve checked it out and I would have loved it when I was first looking for advice…