github/atom
1
1
Fork 0
mirror of https://github.com/atom/atom.git synced 2026-01-23 05:48:10 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #965 from atom/document-themes

Browse Source 
Theme Documentation
This commit is contained in:
Matt Colyer
2013-10-16 12:10:34 -07:00
parent 60aca173ce dbef7a26ce
commit 28a45c0fcd
7 changed files with 417 additions and 492 deletions
Download Patch File Download Diff File Expand all files Collapse all files

413
docs/creating-a-package.md
View File

@@ -1,12 +1,8 @@
{{{
"title": "Creating a Package"
}}}
# Authoring Packages
Packages are at the core of Atom. Nearly everything outside of the main editor manipulation
is handled by a package. That includes "core" pieces like the command panel, status bar,
file tree, and more.
Packages are at the core of Atom. Nearly everything outside of the main editor
is handled by a package. That includes "core" pieces like the command panel,
status bar, file tree, and more.
A package can contain a variety of different resource types to change Atom's
behavior. The basic package layout is as follows (though not every package will
@@ -14,63 +10,44 @@ have all of these directories):
```text
my-package/
lib/
stylesheets/
keymaps/
snippets/
grammars/
keymaps/
lib/
menus/
spec/
package.json
snippets/
stylesheets/
index.coffee
package.json
```
## Publishing
Atom bundles a command line utility called [apm](http://github.com/atom/apm)
which can be used to publish Atom packages to the public registry.
Once your package is written and ready for distribution you can run the
following to publish your package:
```sh
cd my-package
apm publish minor
```
This will update your `package.json` to have a new minor `version`, commit
the change, create a new [Git tag](http://git-scm.com/book/en/Git-Basics-Tagging),
and then upload the package to the registry.
Run `apm help publish` to see all the available options and `apm help` to see
all the other available commands.
## package.json
Similar to [npm packages][npm], Atom packages
can contain a _package.json_ file in their top-level directory. This file contains metadata
about the package, such as the path to its "main" module, library dependencies,
and manifests specifying the order in which its resources should be loaded.
Similar to [npm packages][npm], Atom packages can contain a _package.json_ file
in their top-level directory. This file contains metadata about the package,
such as the path to its "main" module, library dependencies, and manifests
specifying the order in which its resources should be loaded.
In addition to the regular [npm package.json keys](https://npmjs.org/doc/json.html)
available, Atom package.json files have their own additions.
In addition to the regular [npm package.json keys][npm-keys] available, Atom
package.json files have their own additions.
- `main` (**Required**): the path to the CoffeeScript file that's the entry point
to your package
- `stylesheets` (**Optional**): an Array of Strings identifying the order of the
stylesheets your package needs to load. If not specified, stylesheets in the _stylesheets_
directory are added alphabetically.
stylesheets your package needs to load. If not specified, stylesheets in the
_stylesheets_ directory are added alphabetically.
- `keymaps`(**Optional**): an Array of Strings identifying the order of the
key mappings your package needs to load. If not specified, mappings in the _keymaps_
directory are added alphabetically.
key mappings your package needs to load. If not specified, mappings in the
_keymaps_ directory are added alphabetically.
- `menus`(**Optional**): an Array of Strings identifying the order of
the menu mappings your package needs to load. If not specified, mappings
in the _keymap_ directory are added alphabetically.
- `snippets` (**Optional**): an Array of Strings identifying the order of the
snippets your package needs to load. If not specified, snippets in the _snippets_
directory are added alphabetically.
snippets your package needs to load. If not specified, snippets in the
_snippets_ directory are added alphabetically.
- `activationEvents` (**Optional**): an Array of Strings identifying events that
trigger your package's activation. You can delay the loading of your package until
one of these events is trigged.
trigger your package's activation. You can delay the loading of your package
until one of these events is trigged.
## Source Code
@@ -127,57 +104,92 @@ module.exports =
serialize: -> # ...
```
Beyond this simple contract, your package has full access to Atom's internal
API. Anything we call internally, you can call as well. Be aware that since we
are early in development, APIs are subject to change and we have not yet
established clear boundaries between what is public and what is private. Also,
please collaborate with us if you need an API that doesn't exist. Our goal is
to build out Atom's API organically based on the needs of package authors like
you.
Beyond this simple contract, your package has access to Atom's API. Be aware
that since we are early in development, APIs are subject to change and we have
not yet established clear boundaries between what is public and what is private.
Also, please collaborate with us if you need an API that doesn't exist. Our goal
is to build out Atom's API organically based on the needs of package authors
like you.
See [Atom's built-in packages](https://github.com/atom/atom/)
for examples of Atom's API in action.
Check out [wrap-guide] for a simple example of Atom's package API in action.
## Stylesheets
Stylesheets for your package should be placed in the _stylesheets_ directory.
Any stylesheets in this directory will be loaded and attached to the DOM when
your package is activated. Stylesheets can be written as CSS or LESS.
your package is activated. Stylesheets can be written as CSS or [LESS] (but LESS
is recommended).
An optional `stylesheets` array in your _package.json_ can list the stylesheets by
name to specify a loading order; otherwise, stylesheets are loaded alphabetically.
Ideally you will not need much in the way of styling. We've provided a standard
set of components. You can view all components by using the command palette
(`cmd-p`) and searching for "styleguide" or just `cmd+ctrl+G`.
If you do need styling, we try to keep only structural styles in the package
stylesheets. Colors and sizing should be taken from the active theme's
[ui-variables.less][ui-variables]. If you follow this guideline, your package
will look good out of the box with any theme!
An optional `stylesheets` array in your _package.json_ can list the stylesheets
by name to specify a loading order; otherwise, stylesheets are loaded
alphabetically.
## Keymaps
Keymaps are placed in the _keymaps_ subdirectory. It's a good idea to provide
default keymaps for your extension, especially if you're also adding a new command.
```coffeescript
'.tree-view-scroller':
'ctrl-V': 'changer:magic'
```
By default, all keymaps are loaded in alphabetical order. An optional `keymaps`
array in your _package.json_ can specify which keymaps to load and in what order.
It's recommended that you provide key bindings for commonly used actions for
your extension, especially if you're also adding a new command.
See the [main keymaps documentation](../internals/keymaps.md) for more information on
Keymaps are placed in the _keymaps_ subdirectory. By default, all keymaps are
loaded in alphabetical order. An optional `keymaps` array in your _package.json_
can specify which keymaps to load and in what order.
See the [main keymaps documentation][keymaps] for more detailed information on
how keymaps work.
## Menus
Menus are placed in the _menus_ subdirectory. It's useful to specify a
context menu items if if commands are linked to a specific part of the
interface, say for example adding a file in the tree-view.
Menus are placed in the _menus_ subdirectory. By default, all menus are loaded
in alphabetical order. An optional `menus` array in your _package.json_ can
specify which menus to load and in what order.
By default, all menus are loaded in alphabetical order. An optional
`menus` array in your _package.json_ can specify which menus to load
and in what order.
Context menus are created by determining which element was selected and
then adding all of the menu items whose selectors match that element (in
the order which they were loaded). The process is then repeated for the
elements until reaching the top of the dom tree.
NOTE: Currently you can only specify items to be added to the context
menu, the menu which appears when you right click. There are plans to
add support for adding to global menu.
### Application Menu
```coffee-script
'menu': [
{
'label': 'Packages'
'submenu': [
{
'label': 'My Package'
'submenu': [
{
'label': 'Toggle'
'command': 'my-package:toggle'
}
]
}
]
}
]
```
It's recommended that you create an application menu item for common actions
with your package that aren't tied to a specific element.
To add your own item to the application menu simply create a top level `menu`
key in any menu configuration file in _menus_ (since the above is [CSON] it
should end with `.cson`)
The menu templates you specify are merged with all other templates provided
by other packages in the order which they were loaded.
### Context Menu
```coffee-script
'context-menu':
'.tree-view':
'Add file': 'tree-view:add-file'
@@ -185,10 +197,25 @@ add support for adding to global menu.
'Inspect Element': 'core:inspect'
```
It's recommended to specify a context menu item for commands that are linked to
specific parts of the interface, like adding a file in the tree-view.
To add your own item to the application menu simply create a top level
`context-menu` key in any menu configuration file in _menus_ (since the above is
[CSON] it should end with `.cson`)
Context menus are created by determining which element was selected and
then adding all of the menu items whose selectors match that element (in
the order which they were loaded). The process is then repeated for the
elements until reaching the top of the DOM tree.
In the example above, the `Add file` item will only appear when the focused item
or one of its parents has the `tree-view` class applied to it.
## Snippets
An extension can supply language snippets in the _snippets_ directory. These can
be `.cson` or `.json` files. Here's an example:
An extension can supply language snippets in the _snippets_ directory which
allows the user to enter repetitive text quickly.
```coffeescript
".source.coffee .specs":
@@ -203,24 +230,26 @@ be `.cson` or `.json` files. Here's an example:
"""
```
A snippets file contains scope selectors at its top level (`.source.coffee .spec`).
Each scope selector contains a hash of snippets keyed by their name (`Expect`, `Describe`).
Each snippet also specifies a `prefix` and a `body` key. The `prefix` represents
the first few letters to type before hitting the `tab` key to autocomplete. The
`body` defines the autofilled text. You can use placeholders like `$1`, `$2`, to indicate
regions in the body the user can navigate to every time they hit `tab`.
A snippets file contains scope selectors at its top level (`.source.coffee
.spec`). Each scope selector contains a hash of snippets keyed by their name
(`Expect`, `Describe`). Each snippet also specifies a `prefix` and a `body` key.
The `prefix` represents the first few letters to type before hitting the `tab`
key to autocomplete. The `body` defines the autofilled text. You can use
placeholders like `$1`, `$2`, to indicate regions in the body the user can
navigate to every time they hit `tab`.
All files in the directory are automatically loaded, unless the
_package.json_ supplies a `snippets` key. As with all scoped
items, snippets loaded later take precedence over earlier snippets when two
snippets match a scope with the same specificity.
All files in the directory are automatically loaded, unless the _package.json_
supplies a `snippets` key. As with all scoped items, snippets loaded later take
precedence over earlier snippets when two snippets match a scope with the same
specificity.
## Language Grammars
If you're developing a new language grammar, you'll want to place your file in
the _grammars_ directory. Each grammar is a pairing of two keys, `match` and
`captures`. `match` is a regular expression identifying the pattern to highlight,
while `captures` is an object representing what to do with each matching group.
`captures`. `match` is a regular expression identifying the pattern to
highlight, while `captures` is an object representing what to do with each
matching group.
For example:
@@ -245,14 +274,14 @@ To capture a single group, simply use the `name` key instead:
}
```
This indicates that Markdown header lines (`#`, `##`, `###`) should be applied with
the `markup.heading.gfm` token.
This indicates that Markdown header lines (`#`, `##`, `###`) should be applied
with the `markup.heading.gfm` token.
More information about the significance of these tokens can be found in
[section 12.4 of the TextMate Manual](http://manual.macromates.com/en/language_grammars.html).
[section 12.4 of the TextMate Manual][tm-tokens].
Your grammar should also include a `filetypes` array, which is a list of file extensions
your grammar supports:
Your grammar should also include a `filetypes` array, which is a list of file
extensions your grammar supports:
```coffeescript
'fileTypes': [
@@ -279,26 +308,59 @@ You can also use the `atom` protocol URLs in themes.
## Writing Tests
Your package **should** have tests, and if they're placed in the _spec_ directory,
they can be run by Atom.
Your package **should** have tests, and if they're placed in the _spec_
directory, they can be run by Atom.
Under the hood, [Jasmine] is being used to execute the tests, so you can
assume that any DSL available there is available to your package as well.
**FIXME: Explain the following**
* jasmine
* jasmine-focused
* `spec/fixtures` and global.project
* setTimeout
* whatever else is different in spec-helper
## Running tests
Once you've got your test suite written, the recommended way to run it is `apm
test`. `apm test` prints its output to the console and returns the proper status
code depending on whether tests passed or failed.
## Publishing
Atom bundles a command line utility called [apm] which can be used to publish
Atom packages to the public registry.
Once your package is written and ready for distribution you can run the
following to publish your package:
```sh
cd my-package
apm publish minor
```
This will update your `package.json` to have a new minor `version`, commit the
change, create a new [Git tag][git-tag], and then upload the package to the
registry.
Run `apm help publish` to see all the available options and `apm help` to see
all the other available commands.
Under the hood, [Jasmine](https://github.com/pivotal/jasmine) is being used to
execute the tests, so you can assume that any DSL available there is available
to your package as well.
# Full Example
Let's take a look at creating our first package.
Atom has a command you can enter that'll create a package for you:
`package-generator:generate`. Otherwise, you can hit `cmd-p`, and start typing
"Package Generator." Once you activate this package, it'll ask you for a name for
your new package. Let's call ours _changer_.
To get started hit `cmd-p`, and start typing "Package Generator." to generate
the package. Once you select the package generator command, it'll ask you for a
name for your new package. Let's call ours _changer_.
Now, _changer_ is going to have a default set of folders and files created for us.
Hit `cmd-r` to reload Atom, then hit `cmd-p` and start typing "Changer." You'll
see a new `Changer:Toggle` command which, if selected, pops up a new message. So
far, so good!
Now, _changer_ is going to have a default set of folders and files created for
us. Hit `cmd-r` to reload Atom, then hit `cmd-p` and start typing "Changer."
You'll see a new `Changer:Toggle` command which, if selected, pops up a new
message. So far, so good!
In order to demonstrate the capabilities of Atom and its API, our Changer plugin
is going to do two things:
@@ -311,9 +373,9 @@ Let's get started!
## Changing Keybindings and Commands
Since Changer is primarily concerned with the file tree, let's write a keybinding
that works only when the tree is focused. Instead of using the default `toggle`,
our keybinding executes a new command called `magic`.
Since Changer is primarily concerned with the file tree, let's write a
key binding that works only when the tree is focused. Instead of using the
default `toggle`, our keybinding executes a new command called `magic`.
_keymaps/changer.cson_ can easily become this:
@@ -325,10 +387,11 @@ _keymaps/changer.cson_ can easily become this:
Notice that the keybinding is called `ctrl-V`--that's actually `ctrl-shift-v`.
You can use capital letters to denote using `shift` for your binding.
`.tree-view-scroller` represents the parent container for the tree view. Keybindings
only work within the context of where they're entered. For example, hitting `ctrl-V`
anywhere other than tree won't do anything. You can map to `body` if you want
to scope to anywhere in Atom, or just `.editor` for the editor portion.
`.tree-view-scroller` represents the parent container for the tree view.
Keybindings only work within the context of where they're entered. For example,
hitting `ctrl-V` anywhere other than tree won't do anything. You can map to
`body` if you want to scope to anywhere in Atom, or just `.editor` for the
editor portion.
To bind keybindings to a command, we'll use the `rootView.command` method. This
takes a command name and executes a function in the code. For example:
@@ -337,19 +400,21 @@ takes a command name and executes a function in the code. For example:
rootView.command "changer:magic", => @magic()
```
It's common practice to namespace your commands with your package name, and separate
it with a colon (`:`). Rename the existing `toggle` method to `magic` to get the
binding to work.
It's common practice to namespace your commands with your package name, and
separate it with a colon (`:`). Rename the existing `toggle` method to `magic`
to get the binding to work.
Reload the editor, click on the tree, hit your keybinding, and...nothing happens! What the heck?!
Reload the editor, click on the tree, hit your keybinding, and...nothing
happens! What the heck?!
Open up the _package.json_ file, and notice the key that says `activationEvents`.
Basically, this tells Atom to not load a package until it hears a certain event.
Let's change the event to `changer:magic` and reload the editor.
Open up the _package.json_ file, and notice the key that says
`activationEvents`. Basically, this tells Atom to not load a package until it
hears a certain event. Let's change the event to `changer:magic` and reload the
editor.
Hitting the key binding on the tree now works!
## Working with styles
## Working with Styles
The next step is to hide elements in the tree that aren't modified. To do that,
we'll first try and get a list of files that have not changed.
@@ -360,10 +425,11 @@ some of the bundled libraries Atom provides by default](#included-libraries).
Let's bring in jQuery:
```coffeescript
$ = require 'jquery'
{$} = require 'atom'
```
Now, we can query the tree to get us a list of every file that _wasn't_ modified:
Now, we can query the tree to get us a list of every file that _wasn't_
modified:
```coffeescript
magic: ->
@@ -393,9 +459,9 @@ ol.entries .hide-me {
}
```
Refresh atom, and run the `changer` command. You'll see all the non-changed files
disappear from the tree. There are a number of ways you can get the list back;
let's just naively iterate over the same elements and remove the class:
Refresh atom, and run the `changer` command. You'll see all the non-changed
files disappear from the tree. There are a number of ways you can get the list
back; let's just naively iterate over the same elements and remove the class:
```coffeescript
magic: ->
@@ -412,11 +478,11 @@ magic: ->
The next goal of this package is to append a pane to the Atom editor that lists
some information about the modified files.
To do that, we're going to first create a new class method called `content`. Every
package that extends from the `View` class can provide an optional class method
called `content`. The `content` method constructs the DOM that your package uses
as its UI. The principals of `content` are built entirely on [SpacePen](https://github.com/nathansobo/space-pen),
which we'll touch upon only briefly here.
To do that, we're going to first create a new class method called `content`.
Every package that extends from the `View` class can provide an optional class
method called `content`. The `content` method constructs the DOM that your
package uses as its UI. The principals of `content` are built entirely on
[SpacePen], which we'll touch upon only briefly here.
Our display will simply be an unordered list of the file names, and their
modified times. Let's start by carving out a `div` to hold the filenames:
@@ -429,9 +495,9 @@ modified times. Let's start by carving out a `div` to hold the filenames:
@li 'Test2'
```
You can add any HTML5 attribute you like. `outlet` names the variable
your package can uses to manipulate the element directly. The fat pipe (`=>`) indicates
that the next set are nested children.
You can add any HTML5 attribute you like. `outlet` names the variable your
package can uses to manipulate the element directly. The fat pipe (`=>`)
indicates that the next set are nested children.
We'll add one more line to `magic` to make this pane appear:
@@ -442,8 +508,8 @@ rootView.vertical.append(this)
If you hit the key command, you'll see a box appear right underneath the editor.
Success!
Before we populate this, let's apply some logic to toggle the pane off and on, just
like we did with the tree view:
Before we populate this, let's apply some logic to toggle the pane off and on,
just like we did with the tree view:
```coffeescript
# toggles the pane
@@ -454,12 +520,12 @@ else
```
There are about a hundred different ways to toggle a pane on and off, and this
might not be the most efficient one. If you know your package needs to be toggled
on and off more freely, it might be better to draw the UI during the initialization,
then immediately call `hide()` on the element to remove it from the view. You can
then swap between `show()` and `hide()`, and instead of forcing Atom to add and remove
the element as we're doing here, it'll just set a CSS property to control your package's
visibility.
might not be the most efficient one. If you know your package needs to be
toggled on and off more freely, it might be better to draw the interface during the
initialization, then immediately call `hide()` on the element to remove it from
the view. You can then swap between `show()` and `hide()`, and instead of
forcing Atom to add and remove the element as we're doing here, it'll just set a
CSS property to control your package's visibility.
You might have noticed that our two `li` elements aren't showing up. Let's set
a color on them so that they pop. Open up `changer.css` and add this CSS:
@@ -474,8 +540,8 @@ Refresh Atom, hit the key combo, and see your brilliantly white test list.
## Calling Node.js Code
Since Atom is built on top of Node.js, you can call any of its libraries, including
other modules that your package requires.
Since Atom is built on top of Node.js, you can call any of its libraries,
including other modules that your package requires.
We'll iterate through our resulting tree, and construct the path to our modified
file based on its depth in the tree:
@@ -501,14 +567,14 @@ $('ol.entries li.file.modified span.name').each (i, el) ->
modifiedFiles.push modifiedFilePath
```
`modifiedFiles` is an array containing a list of our modified files. We're also using
the node.js [`path` library](http://nodejs.org/docs/latest/api/path.html) to get
the proper directory separator for our system.
`modifiedFiles` is an array containing a list of our modified files. We're also
using the node.js [`path` library][path] to get the proper directory separator
for our system.
Let's remove the two `@li` elements we added in `@content`, so that we can populate
our `modifiedFilesList` with real information. We'll do that by iterating over
`modifiedFiles`, accessing a file's last modified time, and appending it to
`modifiedFilesList`:
Let's remove the two `@li` elements we added in `@content`, so that we can
populate our `modifiedFilesList` with real information. We'll do that by
iterating over `modifiedFiles`, accessing a file's last modified time, and
appending it to `modifiedFilesList`:
```coffeescript
# toggles the pane
@@ -522,11 +588,11 @@ else
rootView.vertical.append(this)
```
When you toggle the modified files list, your pane is now populated with the filenames
and modified times of files in your project. You might notice that subsequent calls
to this command reduplicate information. We could provide an elegant way of rechecking
files already in the list, but for this demonstration, we'll just clear the `modifiedFilesList`
each time it's closed:
When you toggle the modified files list, your pane is now populated with the
filenames and modified times of files in your project. You might notice that
subsequent calls to this command reduplicate information. We could provide an
elegant way of rechecking files already in the list, but for this demonstration,
we'll just clear the `modifiedFilesList` each time it's closed:
```coffeescript
# toggles the pane
@@ -543,14 +609,29 @@ else
# Included Libraries
In addition to core node.js modules, all packages can `require` the following popular
libraries into their packages:
FIXME: Describe `require 'atom'
* [SpacePen](https://github.com/nathansobo/space-pen) (as `require 'space-pen'`)
* [jQuery](http://jquery.com/) (as `require 'jquery'`)
* [Underscore](http://underscorejs.org/) (as `require 'underscore'`)
In addition to core node.js modules, all packages can `require` the following
popular libraries into their packages:
* [SpacePen] (as `require 'space-pen'`)
* [jQuery] (as `require 'jquery'`)
* [Underscore] (as `require 'underscore'`)
Additional libraries can be found by browsing Atom's _node_modules_ folder.
[npm]: http://en.wikipedia.org/wiki/Npm_(software)
[npm-keys]: https://npmjs.org/doc/json.html
[apm]: https://github.com/atom/apm
[git-tag]: http://git-scm.com/book/en/Git-Basics-Tagging
[wrap-guide]: https://github.com/atom/wrap-guide/
[keymaps]: internals/keymaps.md
[tm-tokens]: http://manual.macromates.com/en/language_grammars.html
[spacepen]: https://github.com/nathansobo/space-pen
[path]: http://nodejs.org/docs/latest/api/path.html
[jquery]: http://jquery.com/
[underscore]: http://underscorejs.org/
[jasmine]: https://github.com/pivotal/jasmine
[cson]: https://github.com/atom/season
[less]: http://lesscss.org
[ui-variables]: https://github.com/atom/atom-dark-ui/blob/master/stylesheets/ui-variables.less

120
docs/creating-a-theme.md
View File

@@ -1,76 +1,76 @@
{{{
"title": "Creating a Theme"
}}}
# Creating a Theme
## Overview
Atom's interface is rendered using HTML and it's styled via [LESS] (a superset
of CSS). Don't worry if you haven't heard of LESS before, it's just like CSS but
with a few handy extensions.
* Explain the difference between ui themes and syntax themes
Since CSS is the basis of the theming system, we can load multiple themes within
Atom and they behaves just as they would on a website. Themes loaded first are overridden by
themes which are loaded later (the order is controlled from within the Settings
pane).
This flexibility is helpful for users which prefer a light interface with a dark
syntax theme. Atom currently has interface and syntax themes but it's easy see
how one might want to create their own language specific syntax theme for very
specific styling.
## Getting Started
* What do I need to install?
* Atom - to edit text
* Git - to track and distribute your themes
* What do I need to know?
* CSS/LESS - as that's what themes are written in
* Devtools - so you can find the selector you're looking for.
* Is there an example I can start from?
* Yes, you can clone https://github.com/atom/solarized-dark-syntax
To create your own theme you'll need a few things:
# Create a minimal syntax theme
* A working install of [Atom], so you can work on your new theme.
* A working install of [git] to track changes.
* And a [GitHub] account, so you can distribute your themes.
```bash
cd ~/.atom/packages
mkdir my-theme
cd my-theme
git init
mkdir stylesheets
apm init --theme
cat > index.less <<END
@import "./stylesheets/base.less";
@import "./stylesheets/overrides.less";
END
cat > stylesheets/base.less <<END
@import "ui-variables";
Themes are pretty straight forward but it's still helpful to be familiar with
a few things before starting:
.editor {
color: fade(@text-color, 20%);
}
END
cat > stylesheets/overrides.less <<END
@import "ui-variables";
* LESS is a superset of CSS but it has some really handy features like
variables. If you aren't familiar with its syntax take a few minutes
to [familiarize yourself][less-tutorial].
* Atom uses Chrome at its core, so you can use Chrome devtools to
inspect the current state of the interface. Checkout Google's
[extensive tutorial][devtools-tutorial] for a short introduction.
.editor {
color: fade(@text-color, 80%);
}
END
```
# Creating a Minimal Syntax Theme
### Important points
1. Open the Command Palette (`cmd+p`)
1. Search for `Package Generator: Generate Theme` and select it.
1. Choose a name for the folder which will contain your theme.
1. An Atom window will open with your newly created theme.
1. Open `package.json` and update the relevant parts.
1. Open `stylesheets/colors.less` to change the various colors variables which
have been already been defined.
1. Open `stylesheets/base.less` and modify the various syntax CSS selectors
that have been already been defined.
1. When you're ready update the `README.md` and include an example screenshot
of your new theme in action.
1. Open a terminal to your new theme directory
1. Run `apm link` to install it locally.
1. Reload Atom (`cmd-r`) and your theme should now be applied.
1. To publish, initialize a git repository, push to GitHub, and run
`apm publish`.
* Notice the theme attribute in the package.json file (generated by apm). This
is specific to Atom and required for all theme packages. Otherwise they won't
be displayed in the theme chooser.
* Notice the ui-variables require. If you'd like to make your theme adapt to the
users choosen ui theme, these variables allow you to create your own colors
based on them.
## Interface Themes
## How to create a UI theme
There are only two differences between interface and syntax themes - what
they target and what they provide. Interface themes only target elements which
are outside of the editor and **must** provide a `ui-variables.less` file which
contains all of the variables provided by the [core themes][ui-variables].
Syntax themes don't need to provide any variables to other themes and only
target elements within the editor.
* Needs to have a file called ui-variables and it must contain the following
variables:
* A list of variables from @benogle's theme refactor.
## How to Style a Specific Element
## How to just override UI colors
Once you've got the basics down you'll find that there will be changes you want
to make but you aren't sure how to reference an element. That's when the
devtools become really useful. To open them use `cmd+alt+i` and switch to the
`Elements` tab to inspect the element you're interested in.
* Not interested in making an entire theme? Not to worry, you can override just
the colors.
* Create a theme as above but just include a single file in your `stylesheets`
directory called `ui-variables.less`
* IMPORTANT: This theme must come before
## How to create a syntax theme
* Explain the idea behind grammars/tokens and classes you'd want to override.
[less]: http://lesscss.org/
[git]: http://git-scm.com/
[atom]: https://atom.io/
[github]: https://github.com/
[less-tutorial]: https://speakerdeck.com/danmatthews/less-css
[devtools-tutorial]: https://developers.google.com/chrome-developer-tools/docs/elements
[ui-variables]: https://github.com/atom/atom-dark-ui/blob/master/stylesheets/ui-variables.less

136
docs/customizing-atom.md
View File

@@ -1,58 +1,23 @@
{{{
"title": "Customizing Atom"
}}}
# Customizing Atom
# Configuration Settings
To change a setting, configure a theme, or install a package just open the
Settings pane in the current window by pressing `cmd+,`.
## Your .atom Directory
## Changing The Theme
When you install Atom, an _.atom_ directory is created in your home directory.
If you press `cmd-,`, that directory is opened in a new window. For the
time being, this serves as the primary interface for adjusting configuration
settings, adding and changing key bindings, tweaking styles, etc.
Because Atom themes are based on CSS, it's possible (and encouraged) to have
multiple themes active at the same time. Atom comes with both light and dark
interface themes as well as several syntax themes (you can also [create your
own][create-theme]).
Atom loads configuration settings from the `config.cson` file in your _~/.atom_
directory, which contains CoffeeScript-style JSON:
To change the active themes just open the Settings pane (`cmd-,`) and select the
`Themes` tab. You can install non-bundled themes by going to the `Available
Themes` section on the `Packages` tab within the Settings panel.
```coffeescript
core:
hideGitIgnoredFiles: true
editor:
fontSize: 18
```
## Installing Packages
Configuration is broken into namespaces, which are defined by the config hash's
top-level keys. In addition to Atom's core components, each package may define
its own namespace.
## Glossary of Config Keys
- `core`
- `disablePackages`: An array of package names to disable
- `hideGitIgnoredFiles`: Whether files in the _.gitignore_ should be hidden
- `ignoredNames`: File names to ignore across all of Atom (not fully implemented)
- `themes`: An array of theme names to load, in cascading order
- `autosave`: Save a buffer when its view loses focus
- `editor`
- `autoIndent`: Enable/disable basic auto-indent (defaults to `true`)
- `autoIndentOnPaste`: Enable/disable auto-indented pasted text (defaults to `false`)
- `nonWordCharacters`: A string of non-word characters to define word boundaries
- `fontSize`: The editor font size
- `fontFamily`: The editor font family
- `invisibles`: Specify characters that Atom renders for invisibles in this hash
- `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`)
- `fuzzyFinder`
- `ignoredNames`: Files to ignore *only* in the fuzzy-finder
- `whitespace`
- `ensureSingleTrailingNewline`: Whether to reduce multiple newlines to one at the end of files
- `wrapGuide`
- `columns`: Array of hashes with a `pattern` and `column` key to match the
the path of the current editor to a column position.
You can install non-bundled packages by going to the `Available Packages`
section on the `Packages` tab within the Settings panel (`cmd-,`).
## Customizing Key Bindings
@@ -66,7 +31,7 @@ built-in keymaps:
'enter': 'editor:newline'
".select-list .editor.mini":
'enter': 'core:confirm',
'enter': 'core:confirm'
```
This keymap defines the meaning of `enter` in two different contexts. In a
@@ -80,32 +45,68 @@ in alphabetical order when Atom is started. They will always be loaded last,
giving you the chance to override bindings that are defined by Atom's core
keymaps or third-party packages.
## Changing The Theme
## Advanced Configuration
Atom comes bundled with two themes `atom-dark-*` and `atom-light-*`.
Atom loads configuration settings from the `config.cson` file in your _~/.atom_
directory, which contains CoffeeScript-style JSON:
Because Atom themes are based on CSS, it's possible to have multiple themes
active at the same time.
```coffeescript
core:
hideGitIgnoredFiles: true
editor:
fontSize: 18
```
For example, you'll usually select a theme for the UI and another theme for
syntax highlighting. You can change themes from the preferences pane.
The configuration itself is grouped by the package name or one of the two core
namespaces: `core` and `editor`.
You install new themes by placing them in the _~/.atom/themes_ directory. A
theme can be a single LESS file or a directory containing multiple LESS files.
### Configuration Key Reference
## Installing Packages
- `core`
- `autosave`: Save a buffer when its view loses focus
- `disabledPackages`: An array of package names to disable
- `excludeVcsIgnoredPaths`: Don't search within files specified by _.gitignore_
- `hideGitIgnoredFiles`: Whether files in the _.gitignore_ should be hidden
- `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`)
- `autoIndentOnPaste`: Enable/disable auto-indented pasted text (defaults to `false`)
- `nonWordCharacters`: A string of non-word characters to define word boundaries
- `fontSize`: The editor font size
- `fontFamily`: The editor font family
- `invisibles`: Specify characters that Atom renders for invisibles in this hash
- `tab`: Hard tab characters
- `cr`: Carriage return (for Microsoft-style line endings)
- `eol`: `\n` characters
- `space`: Leading and trailing space characters
- `normalizeIndentOnPaste`: Enable/disable conversion of pasted tabs to spaces
- `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 striping of whitespace at the end of lines (defaults to `true`)
- `wrapGuide`
- `columns`: Array of hashes with a `pattern` and `column` key to match the
the path of the current editor to a column position.
FIXME: Rewrite for the new dialog.
## Quick Personal Hacks
### Quick Personal Hacks
### user.coffee
When Atom finishes loading, it will evaluate _user.coffee_ in your _~/.atom_
directory, giving you a chance to run arbitrary personal CoffeeScript code to
make customizations. You have full access to Atom's API from code in this file.
Please refer to the [Atom Internals Guide](./internals/intro,md) for more information. If your
customizations become extensive, consider [creating a package](./packages/creating_packages.md).
If customizations become extensive, consider [creating a
package][create-a-package].
### user.less
@@ -113,8 +114,8 @@ If you want to apply quick-and-dirty personal styling changes without creating
an entire theme that you intend to distribute, you can add styles to
_user.less_ in your _~/.atom_ directory.
For example, to change the color of the highlighted line number for the line that
contains the cursor, you could add the following style to _user.less_:
For example, to change the color of the highlighted line number for the line
that contains the cursor, you could add the following style to _user.less_:
```less
@highlight-color: pink;
@@ -123,3 +124,6 @@ contains the cursor, you could add the following style to _user.less_:
color: @highlight-color;
}
```
[create-a-package]: creating-packages.md
[create-theme]: creating-a-theme.md

56
docs/getting-started.md
View File

@@ -1,32 +1,28 @@
{{{
"title": "Getting Started"
}}}
# Getting Started
Welcome to Atom! This guide provides a quick introduction so you can be
productive as quickly as possible. There are also guides which cover
[configuring][configuring], [theming][theming], and [extending][extending] Atom.
[configuring], [theming], and [extending] Atom.
## The Command Palette
If there's one key-command you must remember in Atom, it should be `cmd-p`. You
can always hit `cmd-p` to bring up a list of commands that are relevant to the
currently focused UI element. If there is a key binding for a given command, it
is also displayed. This is a great way to explore the system and get to know the
key commands interactively. If you'd like to learn about adding or changing a
binding for a command, refer to the [key bindings](#customizing-key-bindings)
currently focused interface element. If there is a key binding for a given
command, it is also displayed. This is a great way to explore the system and get
to know the key commands interactively. If you'd like to learn about adding or
changing a binding for a command, refer to the [key bindings][key-bindings]
section below.
![Command Palette](https://f.cloud.github.com/assets/1424/1091618/ee7c3554-166a-11e3-9955-aaa61bb5509c.png)
![Command Palette]
## The Basics
### Working With Files
Atom windows are scoped to the directory in which they're opened from. So if
you launch Atom from the command line, everything will be relative to the
current directory. This means that the tree view on the left will only show files
Atom windows are scoped to the directory in which they're opened from. So if you
launch Atom from the command line, everything will be relative to the current
directory. This means that the tree view on the left will only show files
contained within that directory.
This can be a useful way to organize multiple projects, as each project will be
@@ -57,21 +53,23 @@ To delete a file, select it in the tree view and hit `delete`.
#### Find and Replace
FIXME: Describe https://github.com/atom/find-and-replace
To search within a buffer use `cmd-f`. To search the entire project use
`cmd-shift-f`. To find and replace within the current buffer use `cmd-alt-f`.
#### Navigating By Symbols
If you want to jump to a method, the `cmd-j` binding opens a list of all symbols
in the current file. `cmd-.` jumps to the tag for the word currently under the cursor.
in the current file. `cmd-.` jumps to the tag for the word currently under the
cursor.
To search for symbols across your project use `cmd-shift-j`, but you'll need to
make sure you have a tags file generated for the project Also, if you're editing
CoffeeScript, it's a good idea to update your `~/.ctags` file to understand the
language. Here is [a good example](https://github.com/kevinsawicki/dotfiles/blob/master/.ctags).
language. Here is [a good example][ctags].
### Split Panes
You can split any editor pane horizontally or vertically by using `ctrl-\` or
You can split any editor pane horizontally or vertically by using `ctrl-w s` or
`ctrl-w v`. Once you have a split pane, you can move focus between them with
`ctrl-tab` or `ctrl-w w`. To close a pane, close all tabs inside it.
@@ -79,8 +77,7 @@ You can split any editor pane horizontally or vertically by using `ctrl-\` or
You can fold everything with `ctrl-{` and unfold everything with
`ctrl-}`. Or, you can fold / unfold by a single level with `ctrl-[` and
`ctrl-]`. The user interaction around folds is still a bit rough, but we're
planning to improve it soon.
`ctrl-]`.
### Soft-Wrap
@@ -91,18 +88,15 @@ command.
## Configuration
If you press `cmd-,`, a configuration panel will appear in the currently focused
pane. This will serve as the primary interface for adjusting configuration
settings, adding and changing key bindings, tweaking styles, etc.
pane. This serves as the primary interface for adjusting settings, installing
packages and changing themes.
For more advanced configuration see the [customization guide][customization].
## Installing Packages
To install a package, open the configuration panel and select the packages tab.
FIXME: Needs more details.
[configuring]: customizing-atom.html
[theming]: creating-a-theme.html
[extending]: creating-a-package.html
[customization]: customizing-atom.html
[configuring]: customizing-atom.md
[theming]: creating-a-theme.md
[extending]: creating-a-package.md
[customization]: customizing-atom.md
[key-bindings]: #customizing-key-bindings
[command palette]: https://f.cloud.github.com/assets/1424/1091618/ee7c3554-166a-11e3-9955-aaa61bb5509c.png
[ctags]: https://github.com/kevinsawicki/dotfiles/blob/master/.ctags

20
docs/index.md
View File

@@ -1,16 +1,12 @@
{{{
"title": "Guides"
}}}
## Guides
* [Getting Started](getting-started.html)
* [Customizing Atom](customizing-atom.html)
* [Creating a Package](creating-a-package.html)
* [Creating a Theme](creating-a-theme.html)
* [Getting Started](getting-started.md)
* [Customizing Atom](customizing-atom.md)
* [Creating a Package](creating-a-package.md)
* [Creating a Theme](creating-a-theme.md)
### Advanced Topics
* [Configuration](internals/configuration.html)
* [Keymaps](internals/keymaps.html)
* [Serialization](internals/serialization.html)
* [View System](internals/view-system.html)
* [Configuration](internals/configuration.md)
* [Keymaps](internals/keymaps.md)
* [Serialization](internals/serialization.md)
* [View System](internals/view-system.md)

13
docs/internals/view-system.md
View File

@@ -2,9 +2,8 @@
### SpacePen Basics
Atom's view system is built around the [SpacePen](http://github.com/nathansobo/space-pen)
view framework. SpacePen view objects inherit from the jQuery prototype, and
wrap DOM nodes
Atom's view system is built around the [SpacePen] view framework. SpacePen
view objects inherit from the jQuery prototype, and wrap DOM nodes
View objects are actually jQuery wrappers around DOM fragments, supporting all
the typical jQuery traversal and manipulation methods. In addition, view objects
@@ -28,8 +27,7 @@ editorView = editorElement.view()
editorView.setCursorBufferPosition([1, 2])
```
Refer to the [SpacePen](http://github.com/nathansobo/space-pen) documentation
for more details.
Refer to the [SpacePen] documentation for more details.
### RootView
@@ -38,7 +36,7 @@ singleton instance of the `RootView` view class. The root view fills the entire
window, and contains every other view. If you open Atom's inspector with
`alt-cmd-i`, you can see the internal structure of `RootView`:
![RootView in the inspector](https://f.cloud.github.com/assets/1424/1091631/1932c2d6-166b-11e3-8adf-9690fe82d3b8.png)
![RootView in the inspector][rootview-inspector]
#### Panes
@@ -62,3 +60,6 @@ rootView.horizontal.prepend(new MyView)
# place a view below the panes (or use .prepend() to place it above)
rootView.vertical.append(new MyOtherView)
```
[spacepen]: http://github.com/nathansobo/space-pen
[rootview-inspector]: https://f.cloud.github.com/assets/1424/1091631/1932c2d6-166b-11e3-8adf-9690fe82d3b8.png

151
docs/template.jst
View File

@@ -1,151 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css" rel="stylesheet">
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap-theme.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="../../assets/js/html5shiv.js"></script>
<script src="../../assets/js/respond.min.js"></script>
<![endif]-->
<title>Atom - <%= title %></title>
<style>
/*github.com style (c) Vasily Polovnyov <vast@whiteants.net>*/
pre code {
display: block; padding: 0.5em;
color: #333;
background: #f8f8ff
}
pre .comment,
pre .template_comment,
pre .diff .header,
pre .javadoc {
color: #998;
font-style: italic
}
pre .keyword,
pre .css .rule .keyword,
pre .winutils,
pre .javascript .title,
pre .nginx .title,
pre .subst,
pre .request,
pre .status {
color: #333;
font-weight: bold
}
pre .number,
pre .hexcolor,
pre .ruby .constant {
color: #099;
}
pre .string,
pre .tag .value,
pre .phpdoc,
pre .tex .formula {
color: #d14
}
pre .title,
pre .id {
color: #900;
font-weight: bold
}
pre .javascript .title,
pre .lisp .title,
pre .clojure .title,
pre .subst {
font-weight: normal
}
pre .class .title,
pre .haskell .type,
pre .vhdl .literal,
pre .tex .command {
color: #458;
font-weight: bold
}
pre .tag,
pre .tag .title,
pre .rules .property,
pre .django .tag .keyword {
color: #000080;
font-weight: normal
}
pre .attribute,
pre .variable,
pre .lisp .body {
color: #008080
}
pre .regexp {
color: #009926
}
pre .class {
color: #458;
font-weight: bold
}
pre .symbol,
pre .ruby .symbol .string,
pre .lisp .keyword,
pre .tex .special,
pre .prompt {
color: #990073
}
pre .built_in,
pre .lisp .title,
pre .clojure .built_in {
color: #0086b3
}
pre .preprocessor,
pre .pi,
pre .doctype,
pre .shebang,
pre .cdata {
color: #999;
font-weight: bold
}
pre .deletion {
background: #fdd
}
pre .addition {
background: #dfd
}
pre .diff .change {
background: #0086b3
}
pre .chunk {
color: #aaa
}
body {
padding-top: 50px;
}
</style>
</head>
<body>
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/<%= tag %>/index.html">Atom Documentation</a>
</div>
<div class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li><a href="/<%= tag %>/index.html">Guides</a></li>
<li><a href="/<%= tag %>/api/index.html">API</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
<div class="container">
<%= content %>
</div>
</body>
</html>