From 53b0ac22cc3483acc8c71f4b360605f66313f865 Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Wed, 16 Oct 2013 15:11:20 -0700 Subject: [PATCH 1/6] Update theme docs --- docs/creating-a-theme.md | 56 +++++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 10 deletions(-) diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index b0ff04ebb..7e344a367 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. @@ -60,12 +60,44 @@ 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 +## Development workflow -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. +There are a few of tools to help make theme development much faster. + +### Live Reload + +Reloading via `cmd-r` after you make changes to your theme is slow. 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__ 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 +106,7 @@ 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 +[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 From 887dadd5899550c0de31a8efad3883bd9d16cc00 Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Wed, 16 Oct 2013 17:05:26 -0700 Subject: [PATCH 2/6] fix theme docs --- docs/creating-a-package.md | 6 +++--- docs/creating-a-theme.md | 10 ++++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index 96b70c301..0a87afb46 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 @@ -618,7 +618,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 7e344a367..df99d4941 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -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`. @@ -80,7 +81,7 @@ If you'd like to reload all styles at any time, you can use the shortcut ### 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__ or by using the +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 @@ -110,3 +111,4 @@ styleguide or use the shortcut `cmd-ctrl-shift-g`. [styleguide]: https://github.com/atom/styleguide [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 From 201677eb1d81dedc0e7db9981bee114d724fca10 Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Wed, 16 Oct 2013 17:18:32 -0700 Subject: [PATCH 3/6] Add notes about creating a UI theme --- docs/creating-a-theme.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index df99d4941..9f2f0a74a 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -61,9 +61,23 @@ 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. +To create a UI theme, do the following: + +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 much faster. +There are a few of tools to help make theme development fast. ### Live Reload @@ -96,7 +110,7 @@ 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_ or use the shortcut `cmd-ctrl-shift-g`. ![styleguide-img] @@ -109,6 +123,8 @@ styleguide or use the shortcut `cmd-ctrl-shift-g`. [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 From 436ffd90d4cdb2ab38174db13239666019466a51 Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Wed, 16 Oct 2013 17:34:05 -0700 Subject: [PATCH 4/6] Small changes to the pkg docs --- docs/creating-a-package.md | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index 0a87afb46..a4ccb73ba 100644 --- a/docs/creating-a-package.md +++ b/docs/creating-a-package.md @@ -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 From 89ea353d99cf9ecae782fc481a4c07600b178bf2 Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Thu, 17 Oct 2013 13:41:40 -0700 Subject: [PATCH 5/6] Fix based on matts suggestions --- docs/creating-a-package.md | 2 +- docs/creating-a-theme.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index a4ccb73ba..56ff03623 100644 --- a/docs/creating-a-package.md +++ b/docs/creating-a-package.md @@ -123,7 +123,7 @@ 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 opening the styleguide: open the command palette (`cmd-p`) and search for _styleguide_ or just -`cmd-ctrl-shift-G`. +`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 diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index 9f2f0a74a..6dd9efed7 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -58,8 +58,6 @@ 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. To create a UI theme, do the following: From b1d474fd5c471015ed4ffebc3c237c68bff08033 Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Thu, 17 Oct 2013 13:42:25 -0700 Subject: [PATCH 6/6] Remove slow --- docs/creating-a-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index 6dd9efed7..b4bffd075 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -79,7 +79,7 @@ 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 is slow. Atom +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