Documentation For Atom Grammars?


I’d like to create a grammar definition for the Perch CMS to use with Atom. But I can’t find any documentation for how those grammars are defined. Can anyone offer a reference?

Create a New Language (grammars) Package?
Resources on writing new grammars
How do I create a new language package?
Creating a new language pack
Creating a new laguage scope
Where can I find the styles for grammer tokens?
Where can I find the available generic syntax variables?
Nebwie. Where to start?

Here is what I found

And looks like they’re using something similar to TextMate and they refer to this

You can always see the language- repos for some code like language-python

Hope this is useful.


Thanks! I’ll dig into that some and see what I can learn.


Personally my head is blowing up, because there is no good tutorial. And I will write one if I manage to figure out what is going on. The example says to add a grammar part like this:

  'match': '^#{1,6}\\s+.+$'
  'name': 'markup.heading.gfm'

I’ve figured out that this adds class="markup heading gfm" to the span of the matched element. Now the question is: how this is supposed to work? Is Atom dark theme .markup.heading is nested inside .gfm. Should I wrap everything in .gmf then?

I’d be very thankful for help


The first few parts of the name correspond to the TextMate grammars @AbeEstrada linked, as a pretty straightforward hierarchy (though Atom seems to have some groups that were ad-hoc added, don’t match to TextMate, and aren’t documented anywhere, such as punctuation). The last segment is based on the language - gfm for GitHub Markdown, for example.


Thank you, this is very useful. But TextMate says:

A minimal theme will only assign styles to 10 of the 11 root groups below

And among them there is markup.bold and markup.heading. I’m looking at the default theme of ATOM as it should be the most complete one. And there is no .bold at all and .markup.heading is defined only inside .gfm. Also as far as I can tell ATOM does not specify any naming rules. Is default theme bad? Can we improve it, or is there another one. Can we define syntax styles naming rules like TM? Because for now dev cannot be sure that the grammar that he defines will be styles in most of the themes. Also for now when you are doing a grammar for markup language, you should define it as gfm subset, as there are no general markup styles


Also for now when you are doing a grammar for markup language, you should define it as gfm subset

Take a look at the different grammars. The .gfm is specifically for GitHub Flavored Markdown; other grammars have their own ending, usually matching the source.whatever declared in the file’s scopeName, such as .js for Javascript.

as there are no general markup styles

I’m not sure how exactly the styling works out, but declaring things like keyword.control, variable.parameter, and so on are still highlighted appropriately even without anything language-specific.


Maybe I didn’t give the right example. I’m developing a grammar for markup language. And I have a heading in there. In TextMate doc it says:

  • markup
  • heading — a section header. Optionally provide the heading level as the next element, for example markup.heading.2.html for <h2>…</h2> in HTML.

Now in ATOM there are no docs like that. There is no .markup.heading styling in any of 5 default themes. There is style for .gfm .markup.heading.

So my question is: should there be any rules about tokens and how to style them, and should general things be implemented in pre-installed themes, or I have to make my own syntax styling, or I have to use source.gfm namespace?


So my question is: should there be any rules about tokens and how to style them, and should general things be implemented in pre-installed themes

There probably should be, but there doesn’t seem to be right now.

or I have to make my own syntax styling

I think this is the way to go for the moment—it seems to be part of why you can put CSS/LESS files in bundles.


There probably should be, but there doesn’t seem to be right now.

Is there a way to submit an issue, sat for a feature, or just tell the ATOM team that I can work on the and just need guidelines on what to do?


If you have an idea that applies to one of the standard Atom packages, then you can submit an issue on that package’s GitHub repo. If you have something for Atom Core, then create a separate post with as much detail as you can offer and the Atom team can pick it up from there and add it to their internal issue tracker.


Look like it uses

more info oniguruma:


This article helped me a lot recently.

Despite its shortcomings it’s probably the most comprehensive and recent article I’ve seen on TextMate language grammars.

The “named matches” technique the author describes would make writing a grammar less painful, however I discovered that it’s a feature of a newer version of the TextMate grammar format that isn’t currently compatible with Sublime Text.

I’m not sure of the status of Atom on this but it made it a deal-breaker for me since I wanted one grammar that would work with TextMate, Sublime Text, and Atom.


Is there any way to learn why extra scopes eg: punctuation have been added. The language-gfm, language-javascript, language-java, etc follow the pattern where the opening/closing tokens of a block comment (eg: /* */) are given the scope of punctuation.definition.comment which has a particular style defined in the theme; which means if you want to restyle comments there’s two rules to override as I found out when I did just that. I would assume that the the opening/closing tokens are part of the comment and therefore shouldn’t be given another scope/style.

As I’m writing my own grammar I’d like to understand why these decisions have been made so I can be consistent.


There is something I dont understand. It seems in all the topics we are point it to TextMate, but that program only works for iOS, so should I write the grammar according to those rules and just save the file as a .plist and the convert it? Do I only need one file?

In @leedohm example at can I just modified the inside of generic-config.cson file to make a new grammar? if that is the case then how do I convert that to a package Atom can use?


The top link doesn’t work.


No. Atom grammars are saved in CSON. The TextMate tutorial has the right format, but for JavaScript instead of CoffeeScript. Here’s an example of a very small language package I made to wrap around HTML for a user who had specific markup needs.


If you are still interested, you find here an exhaustive list of scope names extracted from the currect core modules’ grammars.


I did find this, which helped me out with defining grammars and publishing a package.