Documentation for Custom Language/Grammar/Syntax Highlighting


I am working in a tiny language, that there aren’t any syntax for in atom or text-editor.

I just recently migrated to atom from Sublime. I also had to make my own sublime syntax for it back then. And I’d like to make one for Atom as well. However, it’s almost impossible to find any sort of documentation on it.

The only /not closed/ topic I can find here on the subject is over 2 years old. And mostly just suggest to look at textmate tutorials.

I understand how the whole grammar and .cson files work thanks to this tutorial:

But what I can’t find any information on, is where I put my CSS styling for the classes you make in the .cson file.

I know there is a converter from Sublime to textmate, and a converter from textmate to Sublime. But I can do a much better job at my syntax highlighting now than I could when I made my Sublime package. So I’d like to start from scratch. If only I could find some documentation on how to do so :frowning:


This is a thing I started looking into a little while ago, but have been distracted recently. I have just posted a gist with my notes in the form of a template.

As far as I can tell, the only thing that matters for having a valid language package is to have a valid .cson file in the grammars directory of a package that loads properly (well-formed package.json and all dependencies installed). For an example of how complex a language package can be, you can look at language-markdown.


Thanks for the reply and template!

I got the whole grammar thing working, with a valid .cson file.

My problem is the styling. I know how to do it. But I can’t for the life of me figure out where to put my css.less file, (I tried putting it in a /styles/mylanguage.less But it doesn’t seem to recognize any of it.

How do I make it recognize my styling for my language?


I don’t know. I haven’t gotten that far. If you share a repo for the package, I could take a look at it.


I finally figured it out.

I just had a typo in my language.less file

For anyone else wondering about this.

Just put your stylings in /styles/yourlanguage.less and it should work fine, for the most part.


hello all! I have been using atom for my scripts daily and love it. I have tried to create a custom language file for a program that I am using: Quantum Espresso which uses input files with a simple syntax. Unfortunately I don’t really have much experience in these kind of languages and I don’t know where to start with this new grammar file.

I have looked at the template and tried to adapt a vim syntax file that I have for Quantum Espresso but I don’t know how to start.

Can someone get me started with one or two lines please? Here you can find the Quantum Espresso vim file where all the terms are defined:

Thank you!


Try my guide. I’m always looking for feedback, so please let me know if I’m assuming too much, or leaving something out, etc. Really though, the best way to learn them is by doing. Try something, and work out why it’s not doing what you expected (instead of cursing at the monitor like I did when starting out…)


Thank you for the guide! I will give it my best shot in the following days. From what I understand, your guide will help me write the grammar file, but how will I know if it is working if there is no theme? And by theme I mean the colours. Do I have to do that separately?


If you write your grammar so that it gives class names that match existing grammars, existing themes will already highlight it properly.


Ok, I found something that is missing from the guide and can’t figure it out: Once you start working on a grammar file, how can you check the progress? I.e. see that what I did is working or there are problems? I can’t see how to activate the new grammar file.


OK, I’ll add some extra for that.

There is a section in the guide that says just follow the flight manual for setting up a new package (e.g., linking it to Atom’s packages and stuff).

If you link it correctly, it will appear in the grammar selection menu. Additionally, if you set up the file extensions array correctly, it will automatically apply itself to files with the correct extensions.

When testing after making a change, I just reloaded the whole Atom window. This will reload all packages, and so refresh the grammar too. With few other community packages, the reload time is relatively quick. There may be ways to reload the grammar directly, but I never bothered to try.


I have a trick I use to make grammar development a lot faster. I have this code in my and when I’m making a grammar I can attach it to a keybinding. This only works if the editor is saved, because Atom requires that you load an existing file.

atom.commands.add 'atom-text-editor', 'custom:load-active-editor-as-grammar', ->
  editor = atom.workspace.getActiveTextEditor()