jekyll-docs 2.5.3 → 3.0.3

data/site/_docs/templates.md

@@ -0,0 +1,425 @@
+---
+layout: docs
+title: Templates
+permalink: /docs/templates/
+---
+
+Jekyll uses the [Liquid](https://github.com/Shopify/liquid/wiki) templating language to
+process templates. All of the standard Liquid [tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#tags) and
+[filters](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#standard-filters) are
+supported. Jekyll even adds a few handy filters and tags of its own to make
+common tasks easier.
+
+## Filters
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Description</th>
+      <th><span class="filter">Filter</span> and <span class="output">Output</span></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p class="name"><strong>Date to XML Schema</strong></p>
+        <p>Convert a Date into XML Schema (ISO 8601) format.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.time | date_to_xmlschema }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">2008-11-07T13:07:54-08:00</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Date to RFC-822 Format</strong></p>
+        <p>Convert a Date into the RFC-822 format used for RSS feeds.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.time | date_to_rfc822 }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">Mon, 07 Nov 2008 13:07:54 -0800</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Date to String</strong></p>
+        <p>Convert a date to short format.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.time | date_to_string }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">07 Nov 2008</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Date to Long String</strong></p>
+        <p>Format a date to long format.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.time | date_to_long_string }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">07 November 2008</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Where</strong></p>
+        <p>Select all the objects in an array where the key has the given value.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.members | where:"graduation_year","2014" }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Group By</strong></p>
+        <p>Group an array's items by a given property.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.members | group_by:"graduation_year" }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">[{"name"=>"2013", "items"=>[...]},
+{"name"=>"2014", "items"=>[...]}]</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>XML Escape</strong></p>
+        <p>Escape some text for use in XML.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ page.content | xml_escape }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>CGI Escape</strong></p>
+        <p>
+          CGI escape a string for use in a URL. Replaces any special characters
+          with appropriate %XX replacements.
+        </p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ "foo,bar;baz?" | cgi_escape }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">foo%2Cbar%3Bbaz%3F</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>URI Escape</strong></p>
+        <p>
+          URI escape a string.
+        </p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ "foo, bar \baz?" | uri_escape }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">foo,%20bar%20%5Cbaz?</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Number of Words</strong></p>
+        <p>Count the number of words in some text.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ page.content | number_of_words }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">1337</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Array to Sentence</strong></p>
+        <p>Convert an array into a sentence. Useful for listing tags.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ page.tags | array_to_sentence_string }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">foo, bar, and baz</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Markdownify</strong></p>
+        <p>Convert a Markdown-formatted string into HTML.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ page.excerpt | markdownify }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Converting Sass/SCSS</strong></p>
+        <p>Convert a Sass- or SCSS-formatted string into CSS.</p>
+      </td>
+      <td class="align-center">
+        <p>
+          <code class="filter">{% raw %}{{ some_scss | scssify }}{% endraw %}</code>
+          <code class="filter">{% raw %}{{ some_sass | sassify }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Slugify</strong></p>
+        <p>Convert a string into a lowercase URL "slug". See below for options.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ "The _config.yml file" | slugify }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">the-config-yml-file</code>
+        </p>
+        <p>
+         <code class="filter">{% raw %}{{ "The _config.yml file" | slugify: 'pretty' }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class="output">the-_config.yml-file</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Data To JSON</strong></p>
+        <p>Convert Hash or Array to JSON.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.data.projects | jsonify }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Sort</strong></p>
+        <p>Sort an array. Optional arguments for hashes: 1.&nbsp;property name 2.&nbsp;nils order (<em>first</em> or <em>last</em>).</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ page.tags | sort }}{% endraw %}</code>
+        </p>
+        <p>
+         <code class="filter">{% raw %}{{ site.posts | sort: 'author' }}{% endraw %}</code>
+        </p>
+        <p>
+         <code class="filter">{% raw %}{{ site.pages | sort: 'title', 'last' }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+### Options for the `slugify` filter
+
+The `slugify` filter accepts an option, each specifying what to filter.
+The default is `default`. They are as follows (with what they filter):
+
+- `none`: no characters
+- `raw`: spaces
+- `default`: spaces and non-alphanumeric characters
+- `pretty`: spaces and non-alphanumeric characters except for `._~!$&'()+,;=@`
+
+## Tags
+
+### Includes
+
+If you have small page fragments that you wish to include in multiple places on
+your site, you can use the `include` tag.
+
+{% highlight ruby %}
+{% raw %}{% include footer.html %}{% endraw %}
+{% endhighlight %}
+
+Jekyll expects all include files to be placed in an `_includes` directory at the
+root of your source directory. This will embed the contents of
+`<source>/_includes/footer.html` into the calling file.
+
+<div class="note">
+  <h5>ProTip™: Use variables as file name</h5>
+  <p>
+
+    The name of the file you wish to embed can be literal (as in the example above),
+    or you can use a variable, using liquid-like variable syntax as in
+    <code>{% raw %}{% include {{my_variable}} %}{% endraw %}</code>.
+
+  </p>
+</div>
+
+You can also pass parameters to an include. Omit the quotation marks to send a variable's value. Liquid curly brackets should not be used here:
+
+{% highlight ruby %}
+{% raw %}{% include footer.html param="value" variable-param=page.variable %}{% endraw %}
+{% endhighlight %}
+
+These parameters are available via Liquid in the include:
+
+{% highlight ruby %}
+{% raw %}{{ include.param }}{% endraw %}
+{% endhighlight %}
+
+#### Including files relative to another file
+
+You can also choose to include file fragments relative to the current file:
+
+{% highlight ruby %}
+{% raw %}{% include_relative somedir/footer.html %}{% endraw %}
+{% endhighlight %}
+
+You won't need to place your included content within the `_includes` directory. Instead,
+the inclusion is specifically relative to the file where the tag is being used. For example,
+if `_posts/2014-09-03-my-file.markdown` uses the `include_relative` tag, the included file
+must be within the `_posts` directory, or one of its subdirectories. You cannot include
+files in other locations.
+
+All the other capabilities of the `include` tag are available to the `include_relative` tag,
+such as using variables.
+
+### Code snippet highlighting
+
+Jekyll has built in support for syntax highlighting of [over 100
+languages](http://pygments.org/languages/) thanks to
+[Pygments](http://pygments.org/). To use Pygments, you must have Python installed
+on your system and set `highlighter` to `pygments` in your site's configuration
+file.
+
+Alternatively, you can use [Rouge](https://github.com/jayferd/rouge) to highlight
+your code snippets. It doesn't support as many languages as Pygments, however it
+should suit most use cases. Also, since [Rouge](https://github.com/jayferd/rouge)
+is written in pure Ruby, you don't need Python on your system!
+
+To render a code block with syntax highlighting, surround your code as follows:
+
+{% highlight text %}
+{% raw %}
+{% highlight ruby %}
+def foo
+  puts 'foo'
+end
+{% endhighlight %}
+{% endraw %}
+{% endhighlight %}
+
+The argument to the `highlight` tag (`ruby` in the example above) is the
+language identifier. To find the appropriate identifier to use for the language
+you want to highlight, look for the “short name” on the [Pygments' Lexers
+page](http://pygments.org/docs/lexers/) or the [Rouge
+wiki](https://github.com/jayferd/rouge/wiki/List-of-supported-languages-and-lexers).
+
+#### Line numbers
+
+There is a second argument to `highlight` called `linenos` that is optional.
+Including the `linenos` argument will force the highlighted code to include line
+numbers. For instance, the following code block would include line numbers next
+to each line:
+
+{% highlight text %}
+{% raw %}
+{% highlight ruby linenos %}
+def foo
+  puts 'foo'
+end
+{% endhighlight %}
+{% endraw %}
+{% endhighlight %}
+
+#### Stylesheets for syntax highlighting
+
+In order for the highlighting to show up, you’ll need to include a highlighting
+stylesheet. For an example stylesheet you can look at
+[syntax.css](https://github.com/mojombo/tpw/tree/master/css/syntax.css). These
+are the same styles as used by GitHub and you are free to use them for your own
+site. If you use `linenos`, you might want to include an additional CSS class
+definition for the `.lineno` class in `syntax.css` to distinguish the line
+numbers from the highlighted code.
+
+### Post URL
+
+If you would like to include a link to a post on your site, the `post_url` tag
+will generate the correct permalink URL for the post you specify.
+
+{% highlight text %}
+{% raw %}
+{% post_url 2010-07-21-name-of-post %}
+{% endraw %}
+{% endhighlight %}
+
+If you organize your posts in subdirectories, you need to include subdirectory
+path to the post:
+
+{% highlight text %}
+{% raw %}
+{% post_url /subdir/2010-07-21-name-of-post %}
+{% endraw %}
+{% endhighlight %}
+
+There is no need to include the file extension when using the `post_url` tag.
+
+You can also use this tag to create a link to a post in Markdown as follows:
+
+{% highlight text %}
+{% raw %}
+[Name of Link]({% post_url 2010-07-21-name-of-post %})
+{% endraw %}
+{% endhighlight %}
+
+### Gist
+
+Use the `gist` tag to easily embed a GitHub Gist onto your site. This works
+with public or secret gists:
+
+{% highlight text %}
+{% raw %}
+{% gist parkr/931c1c8d465a04042403 %}
+{% endraw %}
+{% endhighlight %}
+
+You may also optionally specify the filename in the gist to display:
+
+{% highlight text %}
+{% raw %}
+{% gist parkr/931c1c8d465a04042403 jekyll-private-gist.markdown %}
+{% endraw %}
+{% endhighlight %}
+
+To use the `gist` tag, you'll need to add the [jekyll-gist](https://github.com/jekyll/jekyll-gist) gem to your project. 

data/site/_docs/troubleshooting.md

@@ -0,0 +1,207 @@
+---
+layout: docs
+title: Troubleshooting
+permalink: /docs/troubleshooting/
+---
+
+If you ever run into problems installing or using Jekyll, here are a few tips
+that might be of help. If the problem you’re experiencing isn’t covered below,
+**please [check out our other help resources](/help/)** as well.
+
+- [Installation Problems](#installation-problems)
+- [Problems running Jekyll](#problems-running-jekyll)
+- [Base-URL Problems](#base-url-problems)
+- [Configuration problems](#configuration-problems)
+- [Markup Problems](#markup-problems)
+
+## Installation Problems
+
+If you encounter errors during gem installation, you may need to install
+the header files for compiling extension modules for Ruby 2.0.0. This
+can be done on Ubuntu or Debian by running:
+
+{% highlight bash %}
+sudo apt-get install ruby2.0.0-dev
+{% endhighlight %}
+
+On Red Hat, CentOS, and Fedora systems you can do this by running:
+
+{% highlight bash %}
+sudo yum install ruby-devel
+{% endhighlight %}
+
+On [NearlyFreeSpeech](https://www.nearlyfreespeech.net/) you need to run the
+following commands before installing Jekyll:
+
+{% highlight bash %}
+export GEM_HOME=/home/private/gems
+export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/
+export PATH=$PATH:/home/private/gems/bin
+export RB_USER_INSTALL='true'
+{% endhighlight %}
+
+To install RubyGems on Gentoo:
+
+{% highlight bash %}
+sudo emerge -av dev-ruby/rubygems
+{% endhighlight %}
+
+On Windows, you may need to install [RubyInstaller
+DevKit](https://wiki.github.com/oneclick/rubyinstaller/development-kit).
+
+On Mac OS X, you may need to update RubyGems (using `sudo` only if necessary):
+
+{% highlight bash %}
+sudo gem update --system
+{% endhighlight %}
+
+If you still have issues, you can download and install new Command Line
+Tools (such as `gcc`) using the command
+
+{% highlight bash %}
+xcode-select --install
+{% endhighlight %}
+
+which may allow you to install native gems using this command (again using
+`sudo` only if necessary):
+
+{% highlight bash %}
+sudo gem install jekyll
+{% endhighlight %}
+
+Note that upgrading Mac OS X does not automatically upgrade Xcode itself
+(that can be done separately via the App Store), and having an out-of-date
+Xcode.app can interfere with the command line tools downloaded above. If
+you run into this issue, upgrade Xcode and install the upgraded Command
+Line Tools.
+
+### Jekyll & Mac OS X 10.11
+
+With the introduction of System Integrity Protection, several directories
+that were previously writable are now considered system locations and are no
+longer available. Given these changes, there are a couple of simple ways to get
+up and running. One option is to change the location where the gem will be
+installed (again using `sudo` only if necessary):
+
+{% highlight bash %}
+sudo gem install -n /usr/local/bin jekyll
+{% endhighlight %}
+
+Alternatively, Homebrew can be installed and used to set up Ruby. This can be
+done as follows:
+
+{% highlight bash %}
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+{% endhighlight %}
+
+Once Homebrew is installed, the second step is easy:
+
+{% highlight bash %}
+brew install ruby
+{% endhighlight %}
+
+Advanced users (with more complex needs) may find it helpful to choose one of a
+number of Ruby version managers ([RVM][], [rbenv][], [chruby][], [etc][].) in
+which to install Jekyll.
+
+[RVM]: https://rvm.io
+[rbenv]: http://rbenv.org
+[chruby]: https://github.com/postmodern/chruby
+[etc]: https://github.com/rvm/rvm/blob/master/docs/alt.md
+
+If you elect to use one of the above methods to install Ruby, it might be
+necessary to modify your `$PATH` variable using the following command:
+
+{% highlight bash %}
+export PATH=/usr/local/bin:$PATH
+{% endhighlight %}
+
+GUI apps can modify the `$PATH` as follows:
+
+{% highlight bash %}
+launchctl setenv PATH "/usr/local/bin:$PATH"
+{% endhighlight %}
+
+Either of these approaches are useful because `/usr/local` is considered a
+"safe" location on systems which have SIP enabled, they avoid potential
+conflicts with the version of Ruby included by Apple, and it keeps Jekyll and
+its dependencies in a sandboxed environment. This also has the added
+benefit of not requiring `sudo` when you want to add or remove a gem.
+
+### Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)
+
+This error can occur during the installation of `jekyll-coffeescript` when
+you don't have a proper JavaScript runtime. To solve this, either install
+`execjs` and `therubyracer` gems, or install `nodejs`. Check out
+[issue #2327](https://github.com/jekyll/jekyll/issues/2327) for more info.
+
+## Problems running Jekyll
+
+On Debian or Ubuntu, you may need to add `/var/lib/gems/1.8/bin/` to your path
+in order to have the `jekyll` executable be available in your Terminal.
+
+## Base-URL Problems
+
+If you are using base-url option like:
+
+{% highlight bash %}
+jekyll serve --baseurl '/blog'
+{% endhighlight %}
+
+… then make sure that you access the site at:
+
+{% highlight bash %}
+http://localhost:4000/blog/index.html
+{% endhighlight %}
+
+It won’t work to just access:
+
+{% highlight bash %}
+http://localhost:4000/blog
+{% endhighlight %}
+
+## Configuration problems
+
+The order of precedence for conflicting [configuration settings](../configuration/)
+is as follows:
+
+1. Command-line flags
+2. Configuration file settings
+3. Defaults
+
+That is: defaults are overridden by options specified in `_config.yml`,
+and flags specified at the command-line will override all other settings
+specified elsewhere.
+
+## Markup Problems
+
+The various markup engines that Jekyll uses may have some issues. This
+page will document them to help others who may run into the same
+problems.
+
+### Liquid
+
+The latest version, version 2.0, seems to break the use of `{{ "{{" }}` in
+templates. Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the
+following error:
+
+{% highlight bash %}
+'{{ "{{" }}' was not properly terminated with regexp: /\}\}/  (Liquid::SyntaxError)
+{% endhighlight %}
+
+### Excerpts
+
+Since v1.0.0, Jekyll has had automatically-generated post excerpts. Since
+v1.1.0, Jekyll also passes these excerpts through Liquid, which can cause
+strange errors where references don't exist or a tag hasn't been closed. If you
+run into these errors, try setting `excerpt_separator: ""` in your
+`_config.yml`, or set it to some nonsense string.
+
+<div class="note">
+  <h5>Please report issues you encounter!</h5>
+  <p>
+  If you come across a bug, please <a href="{{ site.help_url }}/issues/new">create an issue</a>
+  on GitHub describing the problem and any work-arounds you find so we can
+  document it here for others.
+  </p>
+</div>