ken-okabe/splitting-atoms

a community-built, community-driven guide to hacking on the Atom editor

Splitting Atoms

a community-built guide to hacking on the Atom editor

A hackable text editor for the 21st Century

At GitHub, we're building the text editor we've always wanted. A tool you can customize to do anything, but also use productively on the first day without ever touching a config file. Atom is modern, approachable, and hackable to the core. We can't wait to see what you build with it.

To find out more about Atom from the team itself, read Introducing Atom and The Nucleus of Atom.

Contributing to Splitting Atoms

There are a number of ways to contribute to this project:

• What are the sections, topics, and guides that are missing? There should still be lots of them, so open up some issues and send pull requests!

• If you are excited about Atom and have already started digging into it and hacking on it, then you are just the person we need to contribute to this community-built, community-driven guide. Write about your experience tinkering with part of Atom and help refine and clarify what is already written here. Send pull requests and open issues. Specific areas you can help

  • Write a guide on building a package, especially if it involves an interesting part of the Atom API or uses a 3rd party library in an innovative way. These belong on the PackageGuides directory.
  • Write a guide on building a theme. These belong in the ThemeGuides directory.
  • Write a guide for defining killer configuration settings. These belong in the ConfigurationGuides directory.
  • Write a guide describing a particular workflow for development with a given language or technology. These belong in the WorkflowGuides directory.

• If something about Atom completely perplexes you or you find parts of the official Atom documentation that are completely lacking, open an issue so that we can look into it and address it in the guide.

• Create a badass Splitting Atoms logo that can eventually be displayed in our README, on our website, and in an eBook.

Further instructions can be found in contributing guide.

Getting Started

You can start by going through the official Atom documentation which contains a handful of helpful guides for creating packages and themes as well as advanced topics such as configuring your environment.

Check out the Atom API for more detailed documentation on the APIs that are available to those developing packages or hacking on existing ones.

Packages

Installing Packages

There are two main approaches to installing packages. You can easily do it from inside Atom from the Package management tab in settings. For those still inclined to using the command-line, the Atom Package Manager binary, apm, can also be used to install packages as well. This utilises the Node Package Manager, npm, behind the scenes.

Installing from Atom

From the Atom editor menus, navigate to Atom -> Preferences.

From there, open the Packages tab and have at it.

The other way to get to this menu is to take advantage of command palette. Press Cmd-shift-P to bring up the command palette and then start typing, packages. You should see the Settings View: Install Packages option show up in the palette.

Installing with apm

On the command line, type apm install package-name.

Searching for Packages

You can search for packages from Atom -> Preferences -> Packages, on the main Atom site, or from apm. To search for packages on apm, type apm search package-name in the command line. One thing to keep in mind when searching for packages is that some package authors prefix their Atom packages with *atom-*package-name, others don't. There doesn't seem to be a consistent standard, so it's probably best to leave the atom- prefix off your search, unless you know the package you're looking for starts with it.

Managing Packages

Atom gives you insight into the load-time that each package is adding to the overall performance of the editor. Based on this information, you can browse your packages enabling and disabling them as you see fit.

Where are packages stored?

All the Atom configuration files, styles, packages, etc. are stored in an Atom dot directory, namely ~/.atom. Inside that directory, you can find another directory named packages which contains all of your packages. For those that have used NPM or Bower, it is similar to your node_modules or bower_components directories.

Uninstalling Packages

Atom uses a clone of npm called apm as it's package manager. (See list of apm command.)

You can see all installed non-bundled packages by going to the Packages section on left hand side of the Settings view (cmd-,) or by using the comman apm list.

Uninstall a package using apm

To uninstall a package using apm, simply run the command apm uninstall <package name>. This will remove tha package from your ~/.atom/packages/ directory.

Here's a sample run of the command:

$ apm uninstall toggle-quotes
Uninstalling toggle-quotes ✓

Uninstall a package using Atom

All third-party packages can also be uninstalled from within Atom. Simply go to Settings (cmd-,). In the settings sidebar, click on a package you want to uninstall and simply click on the "Uninstall" button. This will remove tha package from your ~/.atom/packages/ directory and take you to the main packages page.

Splitting Atoms' Goals

• Develop supplementary guides, documentation, and tutorials for Atom
• Organize the guides, documentation, and tutorials into an Atom developers guide
• Publish the Atom developers guide as a website
• Publish the Atom developers guide as a PDF/eBook

License

Everything here is licensed under the MIT license.