Sigh. Docs are not clear. Working with ContextMenus


I’m having trouble doing a few things and would appreciate some help if possible.

  1. Optionally adding a context menu item if another package is installed
  2. Figuring out how to add the function call to do this (which file do I create? where does it go? what are required functions to get started?)
  3. Figuring out how to add a context menu item and getting the textual contents of what was right clicked?

Now I think #2 is adding a ‘main’ entry to the package.json file. I think that I need to call atom.commands.add() in the module.exports.activate function of the file pointed to in main in the package.json file. I don’t know how to remove the item on deactivate and I don’t know how to test for the installation or availability of another package before continuing. A lot of functions have something like namespace:function-name. How do I declare that namespace and function name specifically?

Finally, there seems to be little to no documentation on how to get the data of the clicked item in the context menu hook. How to add the hook also seems a little … unclear.

Gripe #1: All of the documentation seems to assume contextual knowledge of where to put things and what to put in them. Really annoying for someone coming in and learning

Gripe #2: Dear God, why CoffeeScript?! In a day where traceur and other ES6 options exist, why CoffeeScript

If possible please respond using JavaScript code snippets. I can work with CoffeeScript but it does happen to invoke the gag reflex a bit. Thanks.


I don’t understand this. Packages don’t interfere with each other’s context menu items.

Do you mean how to add a context menu? That is part of a package. The docs …

I see your gripes overflowed into another post. I have responded to them there.

P.S. Why are you sighing? Surely you have needed help in the past without sighing.


I can sympathize with you running into so many troubles. Getting up and running on a pre-release software package can sometimes be a journey. But, you’ve come to the right place :grinning:

To address your questions:

  1. Generally, adding a context menu item is a “do it or don’t” proposition, not conditional. @mark_hahn pointed to the documentation for creating a package and the section on menus talks about how to do it for a package. To do it dynamically, you can use the atom.contextMenu.add method. It will expect you to supply the CSS selector for which the context menu should apply. For example atom-text-editor for the context menu in an editor view or atom-workspace for the context menu anywhere in the window (except the title bar).
  2. This is highly dependent on whether you want this to work for just you or you wish to create a package to share with others. If you want it to be for just you, you can add code to your which is found in your ~/.atom directory (let us know if you’re running Windows because we can translate that path to something meaningful there). You can also open it by going to the Command Palette (Shift+Cmd+P on OS X and Ctrl+Shift+P on other platforms), typing open your init and pressing ENTER. If you want to create a package, I highly recommend following the tutorial Your First Package.
  3. In order to create a context menu item, you’ll need to create a command which you will have done by following the tutorial mentioned in #2. Once you have a command, you can use the Atom API to get the active editor (atom.workspace.getActiveTextEditor()), get the cursor position (editor.getCursorBufferPosition()) and then decide what to do from there.

As for your first gripe, I suspect you dove straight in to the API documentation and missed the general documentation. Yes, the API documentation assumes you know what you’re doing … but there really is a decent amount of general documentation and it is getting better all the time :smile:

The second gripe, well … there’s a whole topic here on Discuss that was open for most of a year that went back and forth and back and forth on that with no real resolution. The simple fact of the matter is, that’s what GitHub chose. Some of us prefer CoffeeScript, some of us prefer JavaScript. After v0.177.0, ES6-ish using 6to5 is available as an option.

Let us know if that doesn’t cover what you need or if you have more questions.

Welcome to Discuss! :grinning:


Optionally adding a context menu if another package is installed means

I only want the context menu to appear (i.e. be added) when another package by another author is currently installed.

Figuring out how to add the function call to do this

The docs behind that link, show a snippet of code without indication as to what file or directory they should show up in, linking to a command string that is a short form for a (function?) call. There is no direct indication as to how and where that function is actually defined. By looking at other folks’ code it seems many people put the code in a relative lib/ directory but is there a naming convention?


Thanks for the replies. I am pretty frustrated because I did read through all those tutorials and I’ve even managed to get a syntax highlighting up and working on apm. I did all that before posting here. So I have been scraping through all the documentation that both you and @mark_hahn provided. The biggest troubles I’ve encountered are, like I said, that the documentation is written with an expectation that you already know the system.

You mention using CSS selectors to determine where things go, but where can I find a list of what exists so that I know what I am choosing? Without the two you provided, I would have to search for a possible reference in either the docs or code written by others. Also, are those “elements” or classes?

And to @mark_hahn and yourself, the reason for the sighs is that Atom could be such an amazing product, and likely will be, but suffers from lack of thorough documentation. There are so many places where things are referenced but not explained. But, in fairness, you’re right; inflecting attitude into the post isn’t the best approach so I apologize.


Some of the documentation is better than others, but yes, there are some assumptions made in a lot of it. For example, you mention:

I don’t know how much you know about web development (Atom is built on top of Chromium, the open source base of Google’s Chrome), so I’m going to start with the basics. Unfortunately, it is impossible to list the set of all possible CSS selectors. There are some common ones, like the ones I mention above … but it quickly gets out of hand, especially because any package with UI can introduce new elements, classes, attributes and the like that increase the size of the selector domain exponentially. This article was a great help to me in learning about CSS selectors:

The selectors I mention above, atom-workspace and atom-text-editor, are elements.

You can open the developer tools, just like you would in Chrome, by going to the menu View > Developer > Toggle Developer Tools. This will allow you to inspect the HTML, CSS and etc that is used to build the UI of the application live. From there, you can decide what CSS selectors to use for various parts of the UI. Also, if you open Atom in Developer Mode by executing atom --dev from the command line, you can right-click on any part of the UI and select Inspect Element from the context menu that comes up. The UI of Atom is pretty complex in some spots though (especially with the new Shadow DOM feature, see all the topics mentioning it here on Discuss) so it may take a bit of digging to figure out what you’re looking at.

The GitHub team has mentioned that they have someone working on the documentation for Atom and they’ll be releasing a new documentation repository when it gets closer to completion. Until then, feel free to mention things that aren’t clear here or in bugs on

I totally understand getting frustrated and I hope that we can help you get further along :grinning: