06-customizing.asc

Basic Customization

Now that we are feeling comfortable with just about everything built into Atom, let’s look at how to tweak it. Perhaps there is a keybinding that you use a lot but feels wrong or a color that isn’t quite right for you. Atom is amazingly flexible, so let’s go over some of the simpler flexes it can do.

Style Tweaks

If you want to apply quick-and-dirty personal styling changes without creating an entire theme that you intend to publish, you can add styles to the styles.less file in your ~/.atom directory.

You can open this file in an editor from the Atom > Open Your Stylesheet menu.

Figure 1. Open your stylesheet

For example, to change the color of the cursor, you could add the following rule to your ~/.atom/styles.less file:

atom-text-editor::shadow .cursor {
  border-color: pink;
}

The easiest way to see what classes are available to style is to inspect the DOM manually via the developer tools. We’ll go over the developer tools in great detail in the next chapter, but for now let’s take a simple look.

You can open the Developer Tools by hitting alt-cmd-I, which will bring up the Chrome developer tools panel.

Figure 2. Developer Tools

You can now easily inspect all the elements in your current editor. If you want to update the style of something, you simply need to figure out what classes it has and add a Less rule to your styles file to modify it.

If you are unfamiliar with Less, it is a basic CSS preprocessor that makes some things in CSS a bit easier. You can learn more about it at lesscss.org. If you prefer to use CSS instead, this file can also be named styles.css and contain CSS.

Customizing Key Bindings

Atom keymaps work similarly to stylesheets. Just as stylesheets use selectors to apply styles to elements, Atom keymaps use selectors to associate keystrokes with events in specific contexts. Here’s a small example, excerpted from Atom’s built-in keymaps:

'atom-text-editor':
  'enter': 'editor:newline'

'atom-text-editor[mini] input':
  'enter': 'core:confirm'

This keymap defines the meaning of enter in two different contexts. In a normal editor, pressing enter emits the editor:newline event, which causes the editor to insert a newline. But if the same keystroke occurs inside a select list’s mini-editor, it instead emits the core:confirm event based on the binding in the more-specific selector.

By default, ~/.atom/keymap.cson is loaded when Atom is started. It will always be loaded last, giving you the chance to override bindings that are defined by Atom’s core keymaps or third-party packages.

You can open this file in an editor from the Atom > Open Your Keymap menu.

You’ll want to know all the commands available to you. Open the Settings panel (cmd-,) and select the Keybindings tab. It will show you all the keybindings currently in use.

Global Configuration Settings

Atom loads configuration settings from the config.cson file in your ~/.atom directory, which contains CoffeeScript-style JSON: CSON.

'core':
  'excludeVcsIgnoredPaths': true
'editor':
  'fontSize': 18

The configuration itself is grouped by the package name or one of the two core namespaces: core and editor.

You can open this file in an editor from the Atom > Open Your Config menu.

Configuration Key Reference

• core

  • disabledPackages: An array of package names to disable

  • excludeVcsIgnoredPaths: Don’t search within files specified by .gitignore

  • ignoredNames: File names to ignore across all of Atom

  • projectHome: The directory where projects are assumed to be located

  • themes: An array of theme names to load, in cascading order

• editor

  • autoIndent: Enable/disable basic auto-indent (defaults to true)

  • nonWordCharacters: A string of non-word characters to define word boundaries

  • fontSize: The editor font size

  • fontFamily: The editor font family

  • invisibles: A hash of characters Atom will use to render whitespace characters. Keys are whitespace character types, values are rendered characters (use value false to turn off individual whitespace character types)

    • tab: Hard tab characters

    • cr: Carriage return (for Microsoft-style line endings)

    • eol: \n characters

    • space: Leading and trailing space characters

  • preferredLineLength: Identifies the length of a line (defaults to 80)

  • showInvisibles: Whether to render placeholders for invisible characters (defaults to false)

  • showIndentGuide: Show/hide indent indicators within the editor

  • showLineNumbers: Show/hide line numbers within the gutter

  • softWrap: Enable/disable soft wrapping of text within the editor

  • softWrapAtPreferredLineLength: Enable/disable soft line wrapping at preferredLineLength

  • tabLength: Number of spaces within a tab (defaults to 2)

• fuzzyFinder

  • ignoredNames: Files to ignore only in the fuzzy-finder

• whitespace

  • ensureSingleTrailingNewline: Whether to reduce multiple newlines to one at the end of files

  • removeTrailingWhitespace: Enable/disable stripping of whitespace at the end of lines (defaults to true)

• wrap-guide

  • columns: Array of hashes with a pattern and column key to match the path of the current editor to a column position.

Language Specific Configuration Settings

You can also set several configuration settings differently for different file types. For example, you may want Atom to soft wrap markdown files, have two-space tabs for ruby files, and four-space tabs for python files.

There are several settings now scoped to an editor’s language. Here is the current list:

editor.tabLength
editor.softWrap
editor.softWrapAtPreferredLineLength
editor.preferredLineLength
editor.scrollPastEnd
editor.showInvisibles
editor.showIndentGuide
editor.nonWordCharacters
editor.invisibles
editor.autoIndent
editor.normalizeIndentOnPaste

Language-specific Settings in the Settings View

You can edit these config settings in the settings view on a per-language basis. Just search for the language of your choice in the left panel, select it, and edit away!

Figure 3. Python specific settings

Language-specific Settings in your Config File

You can also edit the actual configuration file directly. Open your config file via the Command Palette, type ``open config'', and hit enter.

Global settings are under a global key, and each language can have its own top-level key. This key is the language’s scope. Language-specific settings override anything set in the global section.

'global': # all languages unless overridden
  'editor':
    'softWrap': false
    'tabLength': 8

'.source.gfm': # markdown overrides
  'editor':
    'softWrap': true

'.source.ruby': # ruby overrides
  'editor':
    'tabLength': 2

'.source.python': # python overrides
  'editor':
    'tabLength': 4

Finding a language’s scope name

In order to write these overrides effectively, you’ll need to know the scope name for the language. We’ve already done this for finding a scope for writing a snippet in [_snippet_format], but we can quickly cover it again.

The scope name is shown in the settings view for each language. Search for the language of your choice in the left panel, select it, and you should see the scope name under the language name heading:

Figure 4. Finding a language grammar