github/atom
1
1
Fork 0
mirror of https://github.com/atom/atom.git synced 2026-02-18 10:31:54 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #988 from atom/bo-package-doc-update

Browse Source 
Doc update for themes
This commit is contained in:
Ben Ogle
2013-10-17 13:43:56 -07:00
parent 766634c428 b1d474fd5c
commit a0c5e38cdd
2 changed files with 79 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,8 +1,8 @@
# Authoring Packages
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.
is handled by a package. That includes "core" pieces like the file tree, status
bar 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
@@ -121,8 +121,9 @@ your package is activated. Stylesheets can be written as CSS or [LESS] (but LESS
is recommended).
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`.
set of components. You can view all components by opening the styleguide: open
the command palette (`cmd-p`) and search for _styleguide_ or just
`cmd-ctrl-shift-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
@@ -380,14 +381,14 @@ default `toggle`, our keybinding executes a new command called `magic`.
_keymaps/changer.cson_ can easily become this:
```coffeescript
'.tree-view-scroller':
'.tree-view':
'ctrl-V': 'changer:magic'
```
Notice that the keybinding is called `ctrl-V`--that's actually `ctrl-shift-v`.
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.
`.tree-view` 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
@@ -473,9 +474,9 @@ magic: ->
$(el).removeClass("hide-me")
```
## Creating a New Pane
## Creating a New Panel
The next goal of this package is to append a pane to the Atom editor that lists
The next goal of this package is to append a panel 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`.
@@ -527,16 +528,7 @@ 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:
```css
ul.modified-files-list {
color: white;
}
```
Refresh Atom, hit the key combo, and see your brilliantly white test list.
Refresh Atom, hit the key combo, and see your test list.
## Calling Node.js Code
@@ -618,7 +610,7 @@ popular libraries into their packages:
* [jQuery] (as `require 'jquery'`)
* [Underscore] (as `require 'underscore'`)
Additional libraries can be found by browsing Atom's _node_modules_ folder.
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

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

@@ -10,9 +10,9 @@ 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.
syntax theme. Atom currently has only interface and syntax themes but it is
possible to create a theme to style something specific — say a changing
the colors in the tree view or creating a language specific syntax theme.
## Getting Started
@@ -32,9 +32,9 @@ a few things before starting:
inspect the current state of the interface. Checkout Google's
[extensive tutorial][devtools-tutorial] for a short introduction.
# Creating a Minimal Syntax Theme
## Creating a Minimal Syntax Theme
1. Open the Command Palette (`cmd+p`)
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.
@@ -45,9 +45,10 @@ a few things before starting:
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. Reload Atom (`cmd-r`) and your theme should now be applied.
1. Look in the theme settings, your new theme should be show in the enabled themes section
![themesettings-img]
1. Open a terminal to your new theme directory; it should be in `~/.atom/packages/<my-name>`.
1. To publish, initialize a git repository, push to GitHub, and run
`apm publish`.
@@ -57,15 +58,59 @@ 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.
## How to Style a Specific Element
To create a UI theme, do the following:
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.
1. Fork one of the following repos
1. [atom-dark-ui]
1. [atom-light-ui]
1. Open a terminal in the forked theme's directory
1. Open your new theme in a Dev Mode Atom window (either run `atom -d .` in the terminal or use `cmd-shift-o` from atom)
1. Change the name of the theme in the theme's `package.json` file
1. Run `apm link` to tell Atom about your new theme
1. Reload Atom (`cmd-r`)
1. Enable the theme via the themes panel in settings
1. Make changes! Since you opened the theme in a Dev Mode window, changes will
be instantly reflected in the editor without having to reload.
## Development workflow
There are a few of tools to help make theme development fast.
### Live Reload
Reloading via `cmd-r` after you make changes to your theme less than ideal. Atom
supports [live updating][livereload] of styles on Dev Mode Atom windows.
1. Open your theme directory in a dev window by either using the
__File > Open in Dev Mode__ menu or the `cmd-shift-o` shortcut
1. Make a change to your theme file and save &mdash; your change should be
immediately applied!
If you'd like to reload all styles at any time, you can use the shortcut
`cmd-ctrl-shift-r`.
### Developer Tools
Atom is based on the Chrome browser, and supports Chrome's Developer Tools. You
can open them by selecting the __View > Toggle Developer Tools__ menu or by using the
`cmd-option-i` shortcut.
The dev tools allow you to inspect elements and take a look at their CSS
properties.
![devtools-img]
### Atom Styleguide
If you are creating an interface theme, you'll want a way to see how your theme
changes affect all the components in the system. The [styleguide] is a page with
every component Atom supports rendered.
To open the styleguide, open the command palette (`cmd-p`) and search for
_styleguide_ or use the shortcut `cmd-ctrl-shift-g`.
![styleguide-img]
[less]: http://lesscss.org/
[git]: http://git-scm.com/
@@ -74,3 +119,10 @@ devtools become really useful. To open them use `cmd+alt+i` and switch to the
[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
[livereload]: https://github.com/atom/dev-live-reload
[styleguide]: https://github.com/atom/styleguide
[atom-dark-ui]: https://github.com/atom/atom-dark-ui
[atom-light-ui]: https://github.com/atom/atom-light-ui
[styleguide-img]: https://f.cloud.github.com/assets/69169/1347390/2d431d98-36af-11e3-8f8e-3f4ce1e67adb.png
[devtools-img]: https://f.cloud.github.com/assets/69169/1347391/2d51f91c-36af-11e3-806f-f7b334af43e9.png
[themesettings-img]: https://f.cloud.github.com/assets/69169/1347569/3150bd0c-36b2-11e3-9d69-423503acfe3f.png