document how to use themes

History.markdown

@@ -1,3 +1,5 @@
+# History
+
 ## HEAD
 
 ### Minor Enhancements

site/_config.yml

@@ -2,6 +2,9 @@ markdown: kramdown
 highlighter: pygments
 permalink: /news/:year/:month/:day/:title/
 excerpt_separator: ""
+kramdown:
+  input: GFM
+  hard_wrap: false
 
 gauges_id: 503c5af6613f5d0f19000027
 google_analytics_id: UA-50755011-1

site/_data/docs.yml

@@ -26,6 +26,7 @@
   - permalinks
   - pagination
   - plugins
+  - themes
   - extras
 
 - title: Deployment

site/_docs/themes.md

@@ -0,0 +1,107 @@
+---
+layout: docs
+title: Themes
+permalink: /docs/themes/
+---
+
+Jekyll has an extensive theme system, which allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package layouts, includes, stylesheets, and static assets in a way that can be overridden by your site's content.
+
+## Installing a theme
+
+1. To install a theme, first, add the theme to your site's `Gemfile`:
+
+    ```ruby
+    gem 'my-awesome-jekyll-theme'
+    ```
+
+2. Save the changes to your `Gemfile`
+3. Run the command `bundle install` to install the theme
+4. Finally, activate the theme by adding the following to your site's `_config.yml`:
+
+    ```yml
+    theme: my-awesome-jekyll-theme
+    ```
+
+You can have multiple themes listed in your site's Gemfile, but only one theme can be selected in your site's `_config.yml`.
+{: .note .info }
+
+## Overriding theme defaults
+
+Jekyll themes set default layouts, includes, stylesheets and static assets, that can be overridden by your site's content. For example, if your selected theme has a `page` layout, you can override the theme's layout by creating your own `page` layout in the `_layouts` folder (e.g., `_layouts/page.html`).
+
+Jekyll will look first to your site's content, before looking to the theme's defaults, for any requested file in the following folders:
+
+* `/_layouts`
+* `/_includes`
+* `/_sass`
+* `/assets/`
+
+Refer to your selected theme's documentation and source repository for more information on what files you can override.
+{: .note .info}
+
+## Creating a theme
+
+Jekyll themes are distributed as Ruby gems. The only required file is the [Ruby Gemspec](http://guides.rubygems.org/specification-reference/). Here's an example of a minimal Gemspec for the `my-awesome-jekyll-theme` theme, saved as `/my-awsome-jekyll-theme.gemspec`:
+
+```ruby
+Gem::Specification.new do |s|
+  s.name     = 'My Awesome theme'
+  s.version  = '0.1.0'
+  s.license  = 'MIT'
+  s.summary  = 'This is an awesome Jekyll theme!'
+  s.author   = 'Dr. Jekyll'
+  s.email    = 'doc@jekyllrb.com'
+  s.homepage = 'https://github.com/jekyll/my-awesome-jekyll-theme'
+  s.files    = `git ls-files -z`.split("\x0").grep(%r{^(assets|_sass|_includes|_layouts)/})
+end
+```
+
+### Layouts and includes
+
+Theme layouts and includes work just like they work in any Jekyll site. Place layouts in your theme's `/_layouts` folder, and place includes in your themes `/_includes` folder.
+
+For example, if your theme has a `/_layouts/page.html` file, and a page has `layout: page` in its YAML front matter, Jekyll will first look to the site's `_layouts` folder for a the `page` layout, and if none exists, will use your theme's `page` layout.
+
+### Stylesheets
+
+Your theme's stylesheets should be placed in your theme's `/_sass` folder, again, just as you would when authoring a Jekyll site. Your theme's styles can be included in the user's stylesheet using the `@import` directive.
+
+You may also need to output the rendered styles, by adding an `/assets/style.scss` file, which imports the necessary stylesheets, by following the instructions in the [static assets](#static-assets) section below.
+
+Do not place your theme's styles in the `/assets/style.scss` file. Storing styles in the `/_sass` folder allows users to use SaSS's `@import` directive, to combine their custom styles, with the theme's in a single file.
+{: .info .note }
+
+### Static assets
+
+You may also bundle static assets within your theme (e.g., javascripts, images, and fonts). Place any files you'd like in your theme's `/assets` folder, which will be included in the published site. It's common to group files into folders, such as `/assets/js`, `/assets/img`, and `/assets/fonts`.
+
+### Documenting your theme
+
+Your theme should include a `/README.md` file, which explains how site authors can install and use your theme. What layouts are included? What includes? Do they need to add anything special to their site's configuration file?
+
+### Adding a screenshot
+
+Themes are visual. Show users what your theme looks like by including a screenshot as `/screenshot.png` within your theme's repository where it can be retrieved programatically. You can also include this screenshot within your theme's documentation.
+
+### Previewing your theme
+
+To preview your theme as you're authoring it, it may be helpful to add dummy content in, for example, `/index.html` and `/page.html` files. This will allow you to use the `jekyll build` and `jekyll serve` commands to preview your theme, just as you'd preview a Jekyll site.
+
+If you do preview your theme locally, be sure to add `/_site` to your theme's `.gitignore` file to prevent the compiled site from also being included when you distribute your theme.
+{: .info .note}
+
+### Publishing your theme
+
+Themes are published via [RubyGems.org](https://rubygems.org). You'll need a RubyGems account, which you can [create for free](https://rubygems.org/sign_up).
+
+1. First, package your theme, by running the following command, replacing `my-awesome-jekyll-theme` with the name of your theme:
+
+    ```
+    gem build my-awesome-jekyll-theme.gemspec
+    ```
+
+2. Next, push your packaged theme up to the RubyGems service, by running the following command, again replacing `my-awesome-jekyll-theme` with the name of your theme:
+
+    ```
+    gem push my-awesome-jekyll-theme-*.gem
+    ```