diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index 96b70c301..56ff03623 100644 --- a/docs/creating-a-package.md +++ b/docs/creating-a-package.md @@ -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 diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index b0ff04ebb..b4bffd075 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -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/`. 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 — 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