jekyll-docs 3.1.6 → 3.2.0

data/site/_docs/deployment-methods.md

@@ -1,213 +0,0 @@
----
-layout: docs
-title: Deployment methods
-permalink: /docs/deployment-methods/
----
-
-Sites built using Jekyll can be deployed in a large number of ways due to the static nature of the generated output. A few of the most common deployment techniques are described below.
-
-## Web hosting providers (FTP)
-
-Just about any traditional web hosting provider will let you upload files to their servers over FTP. To upload a Jekyll site to a web host using FTP, simply run the `jekyll` command and copy the generated `_site` folder to the root folder of your hosting account. This is most likely to be the `httpdocs` or `public_html` folder on most hosting providers.
-
-### FTP using Glynn
-
-There is a project called [Glynn](https://github.com/dmathieu/glynn), which lets you easily generate your Jekyll powered website’s static files and
-send them to your host through FTP.
-
-## Self-managed web server
-
-If you have direct access yourself to the deployment web server yourself, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Just remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server.
-
-## Automated methods
-
-There are also a number of ways to easily automate the deployment of a Jekyll site. If you’ve got another method that isn’t listed below, we’d love it if you [contributed](../contributing/) so that everyone else can benefit too.
-
-### Git post-update hook
-
-If you store your Jekyll site in [Git](http://git-scm.com/) (you are using version control, right?), it’s pretty easy to automate the
-deployment process by setting up a post-update hook in your Git
-repository, [like
-this](http://web.archive.org/web/20091223025644/http://www.taknado.com/en/2009/03/26/deploying-a-jekyll-generated-site/).
-
-### Git post-receive hook
-
-To have a remote server handle the deploy for you every time you push changes using Git, you can create a user account which has all the public keys that are authorized to deploy in its `authorized_keys` file. With that in place, setting up the post-receive hook is done as follows:
-
-{% highlight bash %}
-laptop$ ssh deployer@example.com
-server$ mkdir myrepo.git
-server$ cd myrepo.git
-server$ git --bare init
-server$ cp hooks/post-receive.sample hooks/post-receive
-server$ mkdir /var/www/myrepo
-{% endhighlight %}
-
-Next, add the following lines to hooks/post-receive and be sure Jekyll is
-installed on the server:
-
-{% highlight bash %}
-GIT_REPO=$HOME/myrepo.git
-TMP_GIT_CLONE=$HOME/tmp/myrepo
-PUBLIC_WWW=/var/www/myrepo
-
-git clone $GIT_REPO $TMP_GIT_CLONE
-jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW
-rm -Rf $TMP_GIT_CLONE
-exit
-{% endhighlight %}
-
-Finally, run the following command on any users laptop that needs to be able to
-deploy using this hook:
-
-{% highlight bash %}
-laptops$ git remote add deploy deployer@example.com:~/myrepo.git
-{% endhighlight %}
-
-Deploying is now as easy as telling nginx or Apache to look at
-`/var/www/myrepo` and running the following:
-
-{% highlight bash %}
-laptops$ git push deploy master
-{% endhighlight %}
-
-### Jekyll-hook
-
-You can also use jekyll-hook, a server that listens for webhook posts from
-GitHub, generates a website with Jekyll, and moves it somewhere to be
-published. Use this to run your own GitHub Pages-style web server.
-
-This method is useful if you need to serve your websites behind a firewall,
-need extra server-level features like HTTP basic authentication or want to
-host your site directly on a CDN or file host like S3.
-
-Setup steps are fully documented
-[in the `jekyll-hook` repo](https://github.com/developmentseed/jekyll-hook).
-
-### Static Publisher
-
-[Static Publisher](https://github.com/static-publisher/static-publisher) is another automated deployment option with a server listening for webhook posts, though it's not tied to GitHub specifically. It has a one-click deploy to Heroku, it can watch multiple projects from one server, it has an easy to user admin interface and can publish to either S3 or to a git repository (e.g. gh-pages).
-
-### Rake
-
-Another way to deploy your Jekyll site is to use [Rake](https://github.com/ruby/rake), [HighLine](https://github.com/JEG2/highline), and
-[Net::SSH](https://github.com/net-ssh/net-ssh). A more complex example of deploying Jekyll with Rake that deals with multiple branches can be found in [Git Ready](https://github.com/gitready/gitready/blob/cdfbc4ec5321ff8d18c3ce936e9c749dbbc4f190/Rakefile).
-
-
-### scp
-
-Once you’ve generated the `_site` directory, you can easily scp it using a `tasks/deploy` shell script similar to [this deploy script here](https://github.com/henrik/henrik.nyh.se/blob/master/script/deploy). You’d obviously need to change the values to reflect your site’s details. There is even [a matching TextMate command](http://gist.github.com/214959) that will help you run this script from within Textmate.
-
-### rsync
-
-Once you’ve generated the `_site` directory, you can easily rsync it using a `tasks/deploy` shell script similar to [this deploy script here](https://github.com/vitalyrepin/vrepinblog/blob/master/transfer.sh). You’d obviously need to change the values to reflect your site’s details.
-
-Certificate-based authorization is another way to simplify the publishing
-process. It makes sense to restrict rsync access only to the directory which it is supposed to sync. This can be done using rrsync.
-
-#### Step 1: Install rrsync to your home folder (server-side)
-
-If it is not already installed by your host, you can do it yourself:
-
-- [Download rrsync](http://ftp.samba.org/pub/unpacked/rsync/support/rrsync)
-- Place it in the `bin` subdirectory of your home folder  (`~/bin`)
-- Make it executable (`chmod +x`)
-
-#### Step 2: Set up certificate-based SSH access (server side)
-
-This [process](https://wiki.gentoo.org/wiki/SSH#Passwordless_Authentication) is
-described in several places online. What is different from the typical approach
-is to put the restriction to certificate-based authorization in
-`~/.ssh/authorized_keys`. Then, launch `rrsync` and supply
-it with the folder it shall have read-write access to:
-
-{% highlight bash %}
-command="$HOME/bin/rrsync <folder>",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa <cert>
-{% endhighlight %}
-
-`<folder>` is the path to your site. E.g., `~/public_html/you.org/blog-html/`.
-
-#### Step 3: Rsync (client-side)
-
-Add the `deploy` script to the site source folder:
-
-{% highlight bash %}
-#!/bin/sh
-
-rsync -crvz --rsh=ssh -p2222' --delete-after --delete-excluded   <folder> <user>@<site>:
-{% endhighlight %}
-
-Command line parameters are:
-
-- `--rsh=ssh -p2222` &mdash; The port for SSH access. It is required if
-your host uses a different port than the default (e.g, HostGator)
-- `<folder>` &mdash; The name of the local output folder (defaults to `_site`)
-- `<user>` &mdash; The username for your hosting account
-- `<site>` &mdash; Your hosting server
-
-Using this setup, you might run the following command:
-
-{% highlight bash %}
-rsync -crvz --rsh='ssh -p2222' --delete-after --delete-excluded   _site/ hostuser@example.org:
-{% endhighlight %}
-
-Don't forget the column `:` after server name!
-
-#### Step 4 (Optional): Exclude the transfer script from being copied to the output folder.
-
-This step is recommended if you use these instructions to deploy your site. If
-you put the `deploy` script in the root folder of your project, Jekyll will
-copy it to the output folder. This behavior can be changed in `_config.yml`.
-
-Just add the following line:
-
-{% highlight yaml %}
-# Do not copy these files to the output directory
-exclude: ["deploy"]
-{% endhighlight %}
-
-Alternatively, you can use an `rsync-exclude.txt` file to control which files will be transferred to your server.
-
-#### Done!
-
-Now it's possible to publish your website simply by running the  `deploy` 
-script. If your SSH certificate  is [passphrase-protected](https://martin.kleppmann.com/2013/05/24/improving-security-of-ssh-private-keys.html), you will be asked to enter it when the
-script executes.
-
-## Rack-Jekyll
-
-[Rack-Jekyll](https://github.com/adaoraul/rack-jekyll/) is an easy way to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](https://github.com/rtomayko/shotgun/), [rackup](https://github.com/rack/rack), [mongrel](https://github.com/mongrel/mongrel), [unicorn](https://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
-
-Read [this post](http://blog.crowdint.com/2010/08/02/instant-blog-using-jekyll-and-heroku.html) on how to deploy to Heroku using Rack-Jekyll.
-
-## Jekyll-Admin for Rails
-
-If you want to maintain Jekyll inside your existing Rails app, [Jekyll-Admin](https://github.com/zkarpinski/Jekyll-Admin) contains drop in code to make this possible. See Jekyll-Admin’s [README](https://github.com/zkarpinski/Jekyll-Admin/blob/master/README) for more details.
-
-## Amazon S3
-
-If you want to host your site in Amazon S3, you can do so by
-using the [s3_website](https://github.com/laurilehmijoki/s3_website)
-application. It will push your site to Amazon S3 where it can be served like
-any web server,
-dynamically scaling to almost unlimited traffic. This approach has the
-benefit of being about the cheapest hosting option available for
-low-volume blogs as you only pay for what you use.
-
-## OpenShift
-
-If you'd like to deploy your site to an OpenShift gear, there's [a cartridge
-for that](https://github.com/openshift-cartridges/openshift-jekyll-cartridge).
-
-<div class="note">
-  <h5>ProTip™: Use GitHub Pages for zero-hassle Jekyll hosting</h5>
-  <p>GitHub Pages are powered by Jekyll behind the scenes, so if you’re looking for a zero-hassle, zero-cost solution, GitHub Pages are a great way to <a href="../github-pages/">host your Jekyll-powered website for free</a>.</p>
-</div>
-
-## Kickster
-
-Use [Kickster](http://kickster.nielsenramon.com/) for easy (automated) deploys to GitHub Pages when using unsupported plugins on GitHub Pages.
-
-Kickster provides a basic Jekyll project setup packed with web best practises and useful optimization tools increasing your overall project quality. Kickster ships with automated and worry-free deployment scripts for GitHub Pages.
-
-Setting up Kickster is very easy, just install the gem and you are good to go. More documentation can here found [here](https://github.com/nielsenramon/kickster#kickster). If you do not want to use the gem or start a new project you can just copy paste the deployment scripts for [Travis CI](https://github.com/nielsenramon/kickster/tree/master/snippets/travis) or [Circle CI](https://github.com/nielsenramon/kickster#automated-deployment-with-circle-ci).

data/site/_docs/drafts.md

@@ -1,20 +0,0 @@
----
-layout: docs
-title: Working with drafts
-permalink: /docs/drafts/
----
-
-Drafts are posts without a date. They're posts you're still working on and
-don't want to publish yet. To get up and running with drafts, create a
-`_drafts` folder in your site's root (as described in the [site structure](/docs/structure/) section) and create your
-first draft:
-
-{% highlight text %}
-|-- _drafts/
-|   |-- a-draft-post.md
-{% endhighlight %}
-
-To preview your site with drafts, simply run `jekyll serve` or `jekyll build`
-with the `--drafts` switch. Each will be assigned the value modification time
-of the draft file for its date, and thus you will see currently edited drafts
-as the latest posts.

data/site/_docs/extras.md

@@ -1,22 +0,0 @@
----
-layout: docs
-title: Extras
-permalink: /docs/extras/
----
-
-There are a number of (optional) extra features that Jekyll supports that you
-may want to install, depending on how you plan to use Jekyll.
-
-## Math Support
-
-Kramdown comes with optional support for LaTeX to PNG rendering via [MathJax](http://www.mathjax.org/) within math blocks. See the Kramdown documentation on [math blocks](http://kramdown.gettalong.org/syntax.html#math-blocks) and [math support](http://kramdown.gettalong.org/converter/html.html#math-support) for more details. MathJax requires you to include JavaScript or CSS to render the LaTeX, e.g.
-
-{% highlight html %}
-<script src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
-{% endhighlight %}
-
-For more information about getting started, check out [this excellent blog post](http://gastonsanchez.com/opinion/2014/02/16/Mathjax-with-jekyll/).
-
-## Alternative Markdown Processors
-
-See the Markdown section on the [configuration page](/docs/configuration/#markdown-options) for instructions on how to use and configure alternative Markdown processors, as well as how to create [custom processors](/docs/configuration/#custom-markdown-processors).

data/site/_docs/frontmatter.md

@@ -1,191 +0,0 @@
----
-layout: docs
-title: Front Matter
-permalink: /docs/frontmatter/
----
-
-The front matter is where Jekyll starts to get really cool. Any file that
-contains a [YAML](http://yaml.org/) front matter block will be processed by
-Jekyll as a special file. The front matter must be the first thing in the file
-and must take the form of valid YAML set between triple-dashed lines. Here is a
-basic example:
-
-{% highlight yaml %}
----
-layout: post
-title: Blogging Like a Hacker
----
-{% endhighlight %}
-
-Between these triple-dashed lines, you can set predefined variables (see below
-for a reference) or even create custom ones of your own. These variables will
-then be available to you to access using Liquid tags both further down in the
-file and also in any layouts or includes that the page or post in question
-relies on.
-
-<div class="note warning">
-  <h5>UTF-8 Character Encoding Warning</h5>
-  <p>
-    If you use UTF-8 encoding, make sure that no <code>BOM</code> header
-    characters exist in your files or very, very bad things will happen to
-    Jekyll. This is especially relevant if you’re running
-    <a href="../windows/">Jekyll on Windows</a>.
-  </p>
-</div>
-
-<div class="note">
-  <h5>ProTip™: Front Matter Variables Are Optional</h5>
-  <p>
-    If you want to use <a href="../variables/">Liquid tags and variables</a>
-    but don’t need anything in your front matter, just leave it empty! The set
-    of triple-dashed lines with nothing in between will still get Jekyll to
-    process your file. (This is useful for things like CSS and RSS feeds!)
-  </p>
-</div>
-
-## Predefined Global Variables
-
-There are a number of predefined global variables that you can set in the
-front matter of a page or post.
-
-<div class="mobile-side-scroller">
-<table>
-  <thead>
-    <tr>
-      <th>Variable</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <p><code>layout</code></p>
-      </td>
-      <td>
-        <p>
-
-          If set, this specifies the layout file to use. Use the layout file
-          name without the file extension. Layout files must be placed in the
-          <code>_layouts</code> directory.
-
-        </p>
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <p><code>permalink</code></p>
-      </td>
-      <td>
-        <p>
-
-          If you need your processed blog post URLs to be something other than
-          the site-wide style (default <code>/year/month/day/title.html</code>), then you can set
-          this variable and it will be used as the final URL.
-
-        </p>
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <p><code>published</code></p>
-      </td>
-      <td>
-        <p>
-          Set to false if you don’t want a specific post to show up when the
-          site is generated.
-        </p>
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <p style="margin-bottom: 5px;"><code>category</code></p>
-        <p><code>categories</code></p>
-      </td>
-      <td>
-        <p>
-
-          Instead of placing posts inside of folders, you can specify one or
-          more categories that the post belongs to. When the site is generated
-          the post will act as though it had been set with these categories
-          normally. Categories (plural key) can be specified as a <a
-          href="http://en.wikipedia.org/wiki/YAML#Lists">YAML list</a> or a
-          comma-separated string.
-
-        </p>
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <p><code>tags</code></p>
-      </td>
-      <td>
-        <p>
-
-          Similar to categories, one or multiple tags can be added to a post.
-          Also like categories, tags can be specified as a YAML list or a
-          comma-separated string.
-
-        </p>
-      </td>
-    </tr>
-  </tbody>
-</table>
-</div>
-
-
-## Custom Variables
-
-Any variables in the front matter that are not predefined are mixed into the
-data that is sent to the Liquid templating engine during the conversion. For
-instance, if you set a title, you can use that in your layout to set the page
-title:
-
-{% highlight html %}
-<!DOCTYPE HTML>
-<html>
-  <head>
-    <title>{% raw %}{{ page.title }}{% endraw %}</title>
-  </head>
-  <body>
-    ...
-{% endhighlight %}
-
-## Predefined Variables for Posts
-
-These are available out-of-the-box to be used in the front matter for a post.
-
-<div class="mobile-side-scroller">
-<table>
-  <thead>
-    <tr>
-      <th>Variable</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <p><code>date</code></p>
-      </td>
-      <td>
-        <p>
-          A date here overrides the date from the name of the post. This can be
-          used to ensure correct sorting of posts. A date is specified in the
-          format <code>YYYY-MM-DD HH:MM:SS +/-TTTT</code>; hours, minutes, seconds, and timezone offset
-          are optional.
-        </p>
-      </td>
-    </tr>
-  </tbody>
-</table>
-</div>
-
-<div class="note">
-  <h5>ProTip™: Don't repeat yourself</h5>
-  <p>
-    If you don't want to repeat your frequently used front matter variables
-    over and over, just define <a href="../configuration/#front-matter-defaults" title="Front Matter defaults">defaults</a>
-    for them and only override them where necessary (or not at all). This works
-    both for predefined and custom variables.
-  </p>
-</div>

data/site/_docs/github-pages.md

@@ -1,133 +0,0 @@
----
-layout: docs
-title: GitHub Pages
-permalink: /docs/github-pages/
----
-
-[GitHub Pages](http://pages.github.com) are public web pages for users,
-organizations, and repositories, that are freely hosted on GitHub's
-`github.io` domain or on a custom domain name of your choice. GitHub Pages are
-powered by Jekyll behind the scenes, so in addition to supporting regular HTML
-content, they’re also a great way to host your Jekyll-powered website for free.
-
-Never built a website with GitHub Pages before? [See this marvelous guide by
-Jonathan McGlone to get you up and running](http://jmcglone.com/guides/github-pages/).
-This guide will teach you what you need to know about Git, GitHub, and Jekyll to
-create your very own website on GitHub Pages.
-
-### Project Page URL Structure
-
-Sometimes it's nice to preview your Jekyll site before you push your `gh-pages`
-branch to GitHub. However, the subdirectory-like URL structure GitHub uses for
-Project Pages complicates the proper resolution of URLs. In order to assure your
-site builds properly, use `site.github.url` in your URL's.
-
-{% highlight html %}
-{% raw %}
-<!-- Useful for styles with static names... -->
-<link href="{{ site.github.url }}/path/to/css.css" rel="stylesheet">
-<!-- and for documents/pages whose URL's can change... -->
-<a href="{{ page.url | prepend: site.github.url }}">{{ page.title }}</a>
-{% endraw %}
-{% endhighlight %}
-
-This way you can preview your site locally from the site root on localhost,
-but when GitHub generates your pages from the gh-pages branch all the URLs
-will resolve properly.
-
-## Deploying Jekyll to GitHub Pages
-
-GitHub Pages work by looking at certain branches of repositories on GitHub.
-There are two basic types available: user/organization pages and project pages.
-The way to deploy these two types of sites are nearly identical, except for a
-few minor details.
-
-<div class="note protip">
-  <h5>Use the <code>github-pages</code> gem</h5>
-  <p>
-    Our friends at GitHub have provided the
-    <a href="https://github.com/github/pages-gem">github-pages</a>
-    gem which is used to manage Jekyll and its dependencies on
-    GitHub Pages. Using it in your projects means that when you deploy
-    your site to GitHub Pages, you will not be caught by unexpected
-    differences between various versions of the gems. To use the
-    currently-deployed version of the gem in your project, add the
-    following to your <code>Gemfile</code>:
-
-{% highlight ruby %}
-source 'https://rubygems.org'
-
-require 'json'
-require 'open-uri'
-versions = JSON.parse(open('https://pages.github.com/versions.json').read)
-
-gem 'github-pages', versions['github-pages']
-{% endhighlight %}
-
-    This will ensure that when you run <code>bundle install</code>, you
-    have the correct version of the <code>github-pages</code> gem.
-
-    If that fails, simplify it:
-
-{% highlight ruby %}
-source 'https://rubygems.org'
-
-gem 'github-pages'
-{% endhighlight %}
-
-    And be sure to run <code>bundle update</code> often.
-  </p>
-</div>
-
-### User and Organization Pages
-
-User and organization pages live in a special GitHub repository dedicated to
-only the GitHub Pages files. This repository must be named after the account
-name. For example, [@mojombo’s user page
-repository](https://github.com/mojombo/mojombo.github.io) has the name
-`mojombo.github.io`.
-
-Content from the `master` branch of your repository will be used to build and
-publish the GitHub Pages site, so make sure your Jekyll site is stored there.
-
-<div class="note info">
-  <h5>Custom domains do not affect repository names</h5>
-  <p>
-    GitHub Pages are initially configured to live under the
-    <code>username.github.io</code> subdomain, which is why repositories must
-    be named this way <strong>even if a custom domain is being used</strong>.
-  </p>
-</div>
-
-### Project Pages
-
-Unlike user and organization Pages, Project Pages are kept in the same
-repository as the project they are for, except that the website content is
-stored in a specially named `gh-pages` branch. The content of this branch will
-be rendered using Jekyll, and the output will become available under a subpath
-of your user pages subdomain, such as `username.github.io/project` (unless a
-custom domain is specified—see below).
-
-The Jekyll project repository itself is a perfect example of this branch
-structure—the [master branch]({{ site.repository }}) contains the
-actual software project for Jekyll, however the Jekyll website (that you’re
-looking at right now) is contained in the [gh-pages
-branch]({{ site.repository }}/tree/gh-pages) of the same repository.
-
-<div class="note warning">
-  <h5>Source Files Must be in the Root Directory</h5>
-  <p>
-GitHub Pages <a href="https://help.github.com/articles/troubleshooting-github-pages-build-failures#source-setting">overrides</a> the <a href="http://jekyllrb.com/docs/configuration/#global-configuration">“Site Source”</a> configuration value, so if you locate your files anywhere other than the root directory, your site may not build correctly.
-  </p>
-</div>
-
-<div class="note">
-  <h5>GitHub Pages Documentation, Help, and Support</h5>
-  <p>
-    For more information about what you can do with GitHub Pages, as well as for
-    troubleshooting guides, you should check out <a
-    href="https://help.github.com/categories/github-pages-basics/">GitHub’s Pages Help
-    section</a>. If all else fails, you should contact <a
-    href="https://github.com/contact">GitHub Support</a>.
-  </p>
-</div>