jekyll-docs 2.5.3 → 3.0.3

data/site/_docs/continuous-integration.md

@@ -0,0 +1,221 @@
+---
+layout: docs
+title: Continuous Integration
+permalink: /docs/continuous-integration/
+---
+
+You can easily test your website build against one or more versions of Ruby.
+The following guide will show you how to set up a free build environment on
+[Travis][0], with [GitHub][1] integration for pull requests. Paid
+alternatives exist for private repositories.
+
+[0]: https://travis-ci.org/
+[1]: https://github.com/
+
+## 1. Enabling Travis and GitHub
+
+Enabling Travis builds for your GitHub repository is pretty simple:
+
+1. Go to your profile on travis-ci.org: https://travis-ci.org/profile/username
+2. Find the repository for which you're interested in enabling builds.
+3. Click the slider on the right so it says "ON" and is a dark grey.
+4. Optionally configure the build by clicking on the wrench icon. Further
+   configuration happens in your `.travis.yml` file. More details on that
+   below.
+
+## 2. The Test Script
+
+The simplest test script simply runs `jekyll build` and ensures that Jekyll
+doesn't fail to build the site. It doesn't check the resulting site, but it
+does ensure things are built properly.
+
+When testing Jekyll output, there is no better tool than [html-proofer][2].
+This tool checks your resulting site to ensure all links and images exist.
+Utilize it either with the convenient `htmlproof` command-line executable,
+or write a Ruby script which utilizes the gem.
+
+Save the commands you want to run and succeed in a file: `./script/cibuild`
+
+### The HTML Proofer Executable
+
+{% highlight bash %}
+#!/usr/bin/env bash
+set -e # halt script on error
+
+bundle exec jekyll build
+bundle exec htmlproof ./_site
+{% endhighlight %}
+
+Some options can be specified via command-line switches. Check out the
+`html-proofer` README for more information about these switches, or run
+`htmlproof --help` locally.
+
+For example to avoid testing external sites, use this command:
+
+{% highlight bash %}
+$ bundle exec htmlproof ./_site --disable-external
+{% endhighlight %}
+
+### The HTML Proofer Library
+
+You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile):
+
+{% highlight ruby %}
+#!/usr/bin/env ruby
+
+require 'html/proofer'
+HTML::Proofer.new("./_site").run
+{% endhighlight %}
+
+Options are given as a second argument to `.new`, and are encoded in a
+symbol-keyed Ruby Hash. For more information about the configuration options,
+check out `html-proofer`'s README file.
+
+[2]: https://github.com/gjtorikian/html-proofer
+
+## 3. Configuring Your Travis Builds
+
+This file is used to configure your Travis builds. Because Jekyll is built
+with Ruby and requires RubyGems to install, we use the Ruby language build
+environment. Below is a sample `.travis.yml` file, followed by
+an explanation of each line.
+
+**Note:** You will need a Gemfile as well, [Travis will automatically install](http://docs.travis-ci.com/user/languages/ruby/#Dependency-Management) the dependencies based on the referenced gems:
+
+{% highlight ruby %}
+source "https://rubygems.org"
+
+gem "jekyll"
+gem "html-proofer"
+{% endhighlight %}
+
+Your `.travis.yml` file should look like this:
+
+{% highlight yaml %}
+language: ruby
+rvm:
+- 2.1
+
+before_script:
+ - chmod +x ./script/cibuild # or do this locally and commit
+
+# Assume bundler is being used, therefore
+# the `install` step will run `bundle install` by default.
+script: ./script/cibuild
+
+# branch whitelist, only for GitHub Pages
+branches:
+  only:
+  - gh-pages     # test the gh-pages branch
+  - /pages-(.*)/ # test every branch which starts with "pages-"
+
+env:
+  global:
+  - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
+{% endhighlight %}
+
+Ok, now for an explanation of each line:
+
+{% highlight yaml %}
+language: ruby
+{% endhighlight %}
+
+This line tells Travis to use a Ruby build container. It gives your script
+access to Bundler, RubyGems, and a Ruby runtime.
+
+{% highlight yaml %}
+rvm:
+- 2.1
+{% endhighlight %}
+
+RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This
+directive tells Travis the Ruby version to use when running your test
+script.
+
+{% highlight yaml %}
+before_script:
+ - chmod +x ./script/cibuild
+{% endhighlight %}
+
+The build script file needs to have the *executable* attribute set or
+Travis will fail with a permission denied error. You can also run this
+locally and commit the permissions directly, thus rendering this step
+irrelevant.
+
+{% highlight yaml %}
+script: ./script/cibuild
+{% endhighlight %}
+
+Travis allows you to run any arbitrary shell script to test your site. One
+convention is to put all scripts for your project in the `script`
+directory, and to call your test script `cibuild`. This line is completely
+customizable. If your script won't change much, you can write your test
+incantation here directly:
+
+{% highlight yaml %}
+install: gem install jekyll html-proofer
+script: jekyll build && htmlproof ./_site
+{% endhighlight %}
+
+The `script` directive can be absolutely any valid shell command.
+
+{% highlight yaml %}
+# branch whitelist, only for GitHub Pages
+branches:
+  only:
+  - gh-pages     # test the gh-pages branch
+  - /pages-(.*)/ # test every branch which starts with "pages-"
+{% endhighlight %}
+
+You want to ensure the Travis builds for your site are being run only on
+the branch or branches which contain your site. One means of ensuring this
+isolation is including a branch whitelist in your Travis configuration
+file. By specifying the `gh-pages` branch, you will ensure the associated
+test script (discussed above) is only executed on site branches. If you use
+a pull request flow for proposing changes, you may wish to enforce a
+convention for your builds such that all branches containing edits are
+prefixed, exemplified above with the `/pages-(.*)/` regular expression.
+
+The `branches` directive is completely optional. Travis will build from every
+push to any branch of your repo if leave it out.
+
+{% highlight yaml %}
+env:
+  global:
+  - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
+{% endhighlight %}
+
+Using `html-proofer`? You'll want this environment variable. Nokogiri, used
+to parse HTML files in your compiled site, comes bundled with libraries
+which it must compile each time it is installed. Luckily, you can
+dramatically decrease the install time of Nokogiri by setting the
+environment variable `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true`.
+
+<div class="note warning">
+  <h5>Be sure to exclude <code>vendor</code> from your
+   <code>_config.yml</code></h5>
+  <p>Travis bundles all gems in the <code>vendor</code> directory on its build
+   servers, which Jekyll will mistakenly read and explode on.</p>
+</div>
+
+{% highlight yaml %}
+exclude: [vendor]
+{% endhighlight %}
+
+### Troubleshooting
+
+**Travis error:** *"You are trying to install in deployment mode after changing
+your Gemfile. Run bundle install elsewhere and add the updated Gemfile.lock
+to version control."*
+
+**Workaround:** Either run `bundle install` locally and commit your changes to
+`Gemfile.lock`, or remove the `Gemfile.lock` file from your repository and add
+an entry in the `.gitignore` file to avoid it from being checked in again.
+
+### Questions?
+
+This entire guide is open-source. Go ahead and [edit it][3] if you have a
+fix or [ask for help][4] if you run into trouble and need some help.
+
+[3]: https://github.com/jekyll/jekyll/edit/master/site/_docs/continuous-integration.md
+[4]: http://jekyllrb.com/help/

data/site/_docs/contributing.md

@@ -0,0 +1,124 @@
+---
+layout: docs
+title: Contributing
+permalink: /docs/contributing/
+---
+
+So you've got an awesome idea to throw into Jekyll. Great! Please keep the
+following in mind:
+
+* **Use https://talk.jekyllrb.com for non-technical or indirect Jekyll questions that are not bugs.**
+* **Contributions will not be accepted without tests or necessary documentation updates.**
+* If you're creating a small fix or patch to an existing feature, just a simple
+  test will do. Please stay in the confines of the current test suite and use
+  [Shoulda](https://github.com/thoughtbot/shoulda/tree/master) and
+  [RSpec-Mocks](https://github.com/rspec/rspec-mocks).
+* If it's a brand new feature, make sure to create a new
+  [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps
+  where appropriate. Also, whipping up some documentation in your fork's `site`
+  would be appreciated, and once merged it will be transferred over to the main
+  `site`, jekyllrb.com.
+* If your contribution changes any Jekyll behavior, make sure to update the
+  documentation. It lives in `site/_docs`. If the docs are missing information,
+  please feel free to add it in. Great docs make a great project!
+* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby)
+  when modifying Ruby code.
+* Please do your best to submit **small pull requests**. The easier the proposed
+  change is to review, the more likely it will be merged.
+* When submitting a pull request, please make judicious use of the pull request
+  body. A description of what changes were made, the motivations behind the
+  changes and [any tasks completed or left to complete](http://git.io/gfm-tasks)
+  will also speed up review time.
+
+<div class="note warning">
+  <h5>Contributions will not be accepted without tests</h5>
+  <p>
+    If you’re creating a small fix or patch to an existing feature, just
+    a simple test will do.
+  </p>
+</div>
+
+
+Test Dependencies
+-----------------
+
+To run the test suite and build the gem you'll need to install Jekyll's
+dependencies. Simply run this command to get all setup:
+
+<figure class="highlight"><pre><code>$ script/bootstrap</code></pre></figure>
+
+Before you start, run the tests and make sure that they pass (to confirm your
+environment is configured properly):
+
+<figure class="highlight"><pre><code>$ script/cibuild</code></pre></figure>
+
+If you are only updating a file in `test/`, you can use the command:
+
+<figure class="highlight"><pre><code>$ script/test test/blah_test.rb</code></pre></figure>
+
+If you are only updating a `.feature` file, you can use the command:
+
+<figure class="highlight"><pre><code>$ script/cucumber features/blah.feature</code></pre></figure>
+
+Both `script/test` and `script/cucumber` can be run without arguments to
+run its entire respective suite.
+
+Workflow
+--------
+
+Here's the most direct way to get your work merged into the project:
+
+* Fork the project.
+* Clone down your fork ( `git clone git@github.com:[username]/jekyll.git` ).
+* Create a topic branch to contain your change ( `git checkout -b my_awesome_feature` ).
+* Hack away, add tests. Not necessarily in that order.
+* Make sure everything still passes by running `script/cibuild`.
+* If necessary, rebase your commits into logical chunks, without errors.
+* Push the branch up ( `git push origin my_awesome_feature` ).
+* Create a pull request against jekyll/jekyll and describe what your change
+  does and the why you think it should be merged.
+
+Updating Documentation
+----------------------
+
+We want the Jekyll documentation to be the best it can be. We've
+open-sourced our docs and we welcome any pull requests if you find it
+lacking.
+
+You can find the documentation for jekyllrb.com in the
+[site]({{ site.repository }}/tree/master/site) directory of
+Jekyll's repo on GitHub.com.
+
+All documentation pull requests should be directed at `master`. Pull
+requests directed at another branch will not be accepted.
+
+The [Jekyll wiki]({{ site.repository }}/wiki) on GitHub
+can be freely updated without a pull request as all GitHub users have access.
+
+If you want to add your plugin to the [list of plugins](/docs/plugins/#available-plugins),
+please submit a pull request modifying the [plugins page source
+file]({{ site.repository }}/blob/master/site/_docs/plugins.md) by adding a
+link to your plugin under the proper subheading depending upon its type.
+
+Gotchas
+-------
+
+* Please do not bump the gem version in your pull requests.
+* Try to keep your patch(es) based from the latest commit on jekyll/jekyll.
+  The easier it is to apply your work, the less work the maintainers have to do,
+  which is always a good thing.
+* Please don't tag your GitHub issue with [fix], [feature], etc. The maintainers
+  actively read the issues and will label it once they come across it.
+
+Finally...
+----------
+
+<div class="note">
+  <h5>Let us know what could be better!</h5>
+  <p>
+    Both using and hacking on Jekyll should be fun, simple, and easy, so if for
+    some reason you find it’s a pain, please <a
+    href="{{ site.repository }}/issues/new">create an issue</a> on
+    GitHub describing your experience so we can make it better.
+  </p>
+</div>

data/site/_docs/datafiles.md

@@ -0,0 +1,151 @@
+---
+layout: docs
+title: Data Files
+permalink: /docs/datafiles/
+---
+
+In addition to the [built-in variables](../variables/) available from Jekyll,
+you can specify your own custom data that can be accessed via the [Liquid
+templating system](https://wiki.github.com/shopify/liquid/liquid-for-designers).
+
+Jekyll supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/),
+and [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) files located in the `_data` directory.
+Note that CSV files *must* contain a header row.
+
+This powerful feature allows you to avoid repetition in your templates and to
+set site specific options without changing `_config.yml`.
+
+Plugins/themes can also leverage Data Files to set configuration variables.
+
+## The Data Folder
+
+As explained on the [directory structure](../structure/) page, the `_data`
+folder is where you can store additional data for Jekyll to use when generating
+your site. These files must be YAML files
+(using either the `.yml`, `.yaml`, `.json` or `csv` extension) and they will be
+accessible via `site.data`.
+
+## Example: List of members
+
+Here is a basic example of using Data Files to avoid copy-pasting large chunks
+of code in your Jekyll templates:
+
+In `_data/members.yml`:
+
+{% highlight yaml %}
+- name: Tom Preston-Werner
+  github: mojombo
+
+- name: Parker Moore
+  github: parkr
+
+- name: Liu Fengyun
+  github: liufengyun
+{% endhighlight %}
+
+Or `_data/members.csv`:
+
+{% highlight text %}
+name,github
+Tom Preston-Werner,mojombo
+Parker Moore,parkr
+Liu Fengyun,liufengyun
+{% endhighlight %}
+
+This data can be accessed via `site.data.members` (notice that the filename
+determines the variable name).
+
+You can now render the list of members in a template:
+
+{% highlight html %}
+{% raw %}
+<ul>
+{% for member in site.data.members %}
+  <li>
+    <a href="https://github.com/{{ member.github }}">
+      {{ member.name }}
+    </a>
+  </li>
+{% endfor %}
+</ul>
+{% endraw %}
+{% endhighlight %}
+
+## Example: Organizations
+
+Data files can also be placed in sub-folders of the `_data` folder. Each folder
+level will be added to a variable's namespace. The example below shows how
+GitHub organizations could be defined separately in a file under the `orgs`
+folder:
+
+In `_data/orgs/jekyll.yml`:
+
+{% highlight yaml %}
+username: jekyll
+name: Jekyll
+members:
+  - name: Tom Preston-Werner
+    github: mojombo
+
+  - name: Parker Moore
+    github: parkr
+{% endhighlight %}
+
+In `_data/orgs/doeorg.yml`:
+
+{% highlight yaml %}
+username: doeorg
+name: Doe Org
+members:
+  - name: John Doe
+    github: jdoe
+{% endhighlight %}
+
+The organizations can then be accessed via `site.data.orgs`, followed by the
+file name:
+
+{% highlight html %}
+{% raw %}
+<ul>
+{% for org_hash in site.data.orgs %}
+{% assign org = org_hash[1] %}
+  <li>
+    <a href="https://github.com/{{ org.username }}">
+      {{ org.name }}
+    </a>
+    ({{ org.members | size }} members)
+  </li>
+{% endfor %}
+</ul>
+{% endraw %}
+{% endhighlight %}
+
+## Example: Accessing a specific author
+
+Pages and posts can also access a specific data item. The example below shows how to access a specific item:
+
+`_data/people.yml`:
+{% highlight yaml %}
+dave:
+    name: David Smith
+    twitter: DavidSilvaSmith
+{% endhighlight %}
+
+The author can then be specified as a page variable in a post's frontmatter:
+
+{% highlight html %}
+{% raw %}
+---
+title: sample post
+author: dave
+---
+
+{% assign author = site.data.people[page.author] %}
+<a rel="author"
+  href="{{ author.twitter }}"
+  title="{{ author.name }}">
+    {{ author.name }}
+</a>
+
+{% endraw %}
+{% endhighlight %}