jekyll-docs 3.0.3 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8f516971da8b5173528c10ffc951a3ab53986576
-  data.tar.gz: 2577f66a33d3402bdd832c1d8961fe725a22ec18
+  metadata.gz: 424f6c916ec8bdc438ccc930df293f89d1857c96
+  data.tar.gz: 19bc4169b6274f56ab0f7b0a60d84d2ed1ad96fe
 SHA512:
-  metadata.gz: 3a4d59816c59bb0ab3f9d6e8af7cd576de38d55aa1af058049d3b8f9cc0cf5f1a30194983a0eb3fbb22af740d13948a9460149d7350e5fc417a59fffd5d52177
-  data.tar.gz: b73b89b5ff1589ccc268c5dc3780c60dca889a74e55262173b05630cc1d83bdda7688052acd895305859fcb0ce6ac598c0c6260c49aa4f5da4482124de07f2e5
+  metadata.gz: 46206c8fdc04f3f8ab0852cbac4b66f74d0ba86619329a01c663321f1d8b021a9069e3aacca3e015681c580b7e5604cea9ec378421e733072fa5aae9d1353e56
+  data.tar.gz: f9d1f3f20808fe0001aadae5707ecc563eadc14455baf76cd3c677962e73a25a3797bbd1e08d4ff31f7859f1aa8b605863b0dcbd2609e2ff10deec51773c919b

data/site/_config.yml

@@ -9,6 +9,8 @@ google_analytics_id: UA-50755011-1
 repository: https://github.com/jekyll/jekyll
 help_url: https://github.com/jekyll/jekyll-help
 
+timezone: America/Los_Angeles
+
 collections:
   docs:
     output: true
@@ -19,3 +21,5 @@ url: http://jekyllrb.com
 
 gems:
   - jekyll-feed
+  - jekyll-redirect-from
+  - jemoji

data/site/_data/docs.yml

@@ -39,9 +39,11 @@
   - troubleshooting
   - sites
   - resources
-  - upgrading
+  - upgrading/0-to-2
+  - upgrading/2-to-3
 
 - title: Meta
   docs:
   - contributing
+  - conduct
   - history

data/site/_docs/assets.md

@@ -83,9 +83,10 @@ here, too.
 
 ## Coffeescript
 
-To enable Coffeescript in Jekyll 3.0 and up you must 
- * Install the `jekyll-coffeescript` gem
- * Ensure that your `_config.yml` is up-to-date and includes the following
+To enable Coffeescript in Jekyll 3.0 and up you must
+
+* Install the `jekyll-coffeescript` gem
+* Ensure that your `_config.yml` is up-to-date and includes the following:
 
 {% highlight yaml %}
 gems:

data/site/_docs/conduct.md

@@ -0,0 +1,55 @@
+---
+layout: docs
+title: Code of Conduct
+permalink: "/docs/conduct/"
+redirect_from: "/conduct/index.html"
+editable: false
+---
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting a project maintainer. All complaints
+will be reviewed and investigated and will result in a response that is deemed
+necessary and appropriate to the circumstances. Maintainers are obligated to
+maintain confidentiality with regard to the reporter of an incident.
+
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/site/_docs/configuration.md

@@ -120,7 +120,7 @@ class="flag">flags</code> (specified on the command-line) that control them.
       <td>
         <p class="name"><strong>Encoding</strong></p>
         <p class="description">
-            Set the encoding of files by name. Only available for Ruby
+            Set the encoding of files by name (only available for Ruby
             1.9 or later).
             The default value is <code>utf-8</code> starting in 2.0.0,
             and <code>nil</code> before 2.0.0, which will yield the Ruby
@@ -198,6 +198,7 @@ class="flag">flags</code> (specified on the command-line) that control them.
         <p class="description">Process and render draft posts.</p>
       </td>
       <td class="align-center">
+        <p><code class="option">show_drafts: BOOL</code></p>
         <p><code class="flag">--drafts</code></p>
       </td>
     </tr>
@@ -352,6 +353,24 @@ before your site is served.
         <p><code class="flag">--skip-initial-build</code></p>
       </td>
     </tr>
+    <tr class="setting">
+      <td>
+        <p class="name"><strong>X.509 (SSL) Private Key</strong></p>
+        <p class="description">SSL Private Key.</p>
+      </td>
+      <td class="align-center">
+        <p><code class="flag">--ssl-key</code></p>
+      </td>
+    </tr>
+    <tr class="setting">
+      <td>
+        <p class="name"><strong>X.509 (SSL) Certificate</strong></p>
+        <p class="description">SSL Public certificate.</p>
+      </td>
+      <td class="align-center">
+        <p><code class="flag">--ssl-cert</code></p>
+      </td>
+    </tr>
   </tbody>
 </table>
 </div>
@@ -364,6 +383,24 @@ before your site is served.
   </p>
 </div>
 
+## Custom WEBRick Headers
+
+You can provide custom headers for your site by adding them to `_config.yml`
+
+{% highlight yaml %}
+# File: _config.yml
+webrick:
+  headers:
+    My-Header: My-Value
+    My-Other-Header: My-Other-Value
+{% endhighlight %}
+
+### Defaults
+
+We only provide one default and that's a Content-Type header that disables
+caching in development so that you don't have to fight with Chrome's aggressive
+caching when you are in development mode.
+
 ## Specifying a Jekyll environment at build time
 
 In the build (or serve) arguments, you can specify a Jekyll environment and value. The build will then apply this value in any conditional statements in your content.
@@ -452,7 +489,7 @@ With these defaults, all posts would use the `my-site` layout. Any html files th
 {% highlight yaml %}
 collections:
   - my_collection:
-    output: true
+      output: true
 
 defaults:
   -
@@ -463,13 +500,14 @@ defaults:
       layout: "default"
 {% endhighlight %}
 
-In this example the `layout` is set to `default` inside the [collection](../collections/) with the name `my_collection`.
+In this example, the `layout` is set to `default` inside the
+[collection](../collections/) with the name `my_collection`.
 
 ### Precedence
 
 Jekyll will apply all of the configuration settings you specify in the `defaults` section of your `_config.yml` file. However, you can choose to override settings from other scope/values pair by specifying a more specific path for the scope.
 
-You can see that in the last example above. First, we set the default layout to `my-site`. Then, using a more specific path, we set the default layout for files in the `projects/` path to `project`. This can be done with any value that you would set in the page or post front matter.
+You can see that in the second to last example above. First, we set the default layout to `my-site`. Then, using a more specific path, we set the default layout for files in the `projects/` path to `project`. This can be done with any value that you would set in the page or post front matter.
 
 Finally, if you set defaults in the site configuration by adding a `defaults` section to your `_config.yml` file, you can override those settings in a post or page file. All you need to do is specify the settings in the post or page front matter. For example:
 
@@ -641,7 +679,7 @@ extensions are:
 ### Kramdown
 
 In addition to the defaults mentioned above, you can also turn on recognition
-of Github Flavored Markdown by passing an `input` option with a value of "GFM".
+of GitHub Flavored Markdown by passing an `input` option with a value of "GFM".
 
 For example, in your `_config.yml`:
 
@@ -669,9 +707,41 @@ class Jekyll::Converters::Markdown::MyCustomProcessor
 end
 {% endhighlight %}
 
-Once you've created your class and have it properly setup either as a plugin in
-the `_plugins` folder or as a gem, specify it in your `_config.yml`:
+Once you've created your class and have it properly set up either as a plugin
+in the `_plugins` folder or as a gem, specify it in your `_config.yml`:
 
 {% highlight yaml %}
 markdown: MyCustomProcessor
 {% endhighlight %}
+
+## Incremental Regeneration
+<div class="note warning">
+  <h5>Incremental regeneration is still an experimental feature</h5>
+  <p>
+    While incremental regeneration will work for the most common cases, it will
+    not work correctly in every scenario. Please be extremely cautious when
+    using the feature, and report any problems not listed below by
+    <a href="https://github.com/jekyll/jekyll/issues/new">opening an issue on GitHub</a>.
+  </p>
+</div>
+
+Incremental regeneration helps shorten build times by only generating documents
+and pages that were updated since the previous build. It does this by keeping
+track of both file modification times and inter-document dependencies in the
+`.jekyll-metadata` file.
+
+Under the current implementation, incremental regeneration will only generate a
+document or page if either it, or one of its dependencies, is modified. Currently,
+the only types of dependencies tracked are includes (using the
+{% raw %}`{% include %}`{% endraw %} tag) and layouts. This means that plain
+references to other documents (for example, the common case of iterating over
+`site.posts` in a post listings page) will not be detected as a dependency.
+
+To remedy some of these shortfalls, putting `regenerate: true` in the front-matter
+of a document will force Jekyll to regenerate it regardless of whether it has been
+modified. Note that this will generate the specified document only; references
+to other documents' contents will not work since they won't be re-rendered.
+
+Incremental regeneration can be enabled via the `--incremental` flag (`-I` for
+short) from the command-line or by setting `incremental: true` in your
+configuration file.

data/site/_docs/contributing.md

@@ -43,7 +43,7 @@ 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:
+dependencies. Simply run this command to get all set up:
 
 <figure class="highlight"><pre><code>$ script/bootstrap</code></pre></figure>
 

data/site/_docs/datafiles.md

@@ -33,8 +33,8 @@ of code in your Jekyll templates:
 In `_data/members.yml`:
 
 {% highlight yaml %}
-- name: Tom Preston-Werner
-  github: mojombo
+- name: Eric Mill
+  github: konklone
 
 - name: Parker Moore
   github: parkr
@@ -47,7 +47,7 @@ Or `_data/members.csv`:
 
 {% highlight text %}
 name,github
-Tom Preston-Werner,mojombo
+Eric Mill,konklone
 Parker Moore,parkr
 Liu Fengyun,liufengyun
 {% endhighlight %}

data/site/_docs/deployment-methods.md

@@ -90,7 +90,7 @@ Setup steps are fully documented
 
 ### Rake
 
-Another way to deploy your Jekyll site is to use [Rake](https://github.com/jimweirich/rake), [HighLine](https://github.com/JEG2/highline), and
+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).
 
 
@@ -102,64 +102,77 @@ Once you’ve generated the `_site` directory, you can easily scp it using a `ta
 
 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.
 
-#### Step 1: Install rrsync to your home folder (server-side)
+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.
 
-We will use certificate-based authorization to simplify the publishing process. It makes sense to restrict rsync access only to the directory which it is supposed to sync.
+#### Step 1: Install rrsync to your home folder (server-side)
 
-That's why rrsync wrapper shall be installed. If it is not already installed by your hoster you can do it yourself:
+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)
-- Put it to the bin subdirectory of your home folder  (```~/bin```)
-- Make it executable (```chmod +x```)
+- [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: Setup certificate-based ssh access (server side)
+#### Step 2: Set up certificate-based SSH access (server side)
 
-[This process is described in a lot of places in the net](https://wiki.gentoo.org/wiki/SSH#Passwordless_Authentication). We will not cover it here. What is different from usual approach is to put the restriction to certificate-based authorization in ```~/.ssh/authorized_keys```). We will launch ```rrsync``` utility and supply it with the folder it shall have read-write access to:
+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/```.
+`<folder>` is the path to your site. E.g., `~/public_html/you.org/blog-html/`.
 
-#### Step 3: Rsync! (client-side)
+#### Step 3: Rsync (client-side)
 
-Add the script ```deploy``` to the web site source folder:
+Add the `deploy` script to the site source folder:
 
 {% highlight bash %}
 #!/bin/sh
 
-rsync -avr --rsh='ssh -p2222' --delete-after --delete-excluded   <folder> <user>@<site>:
+rsync -crvz --rsh=ssh -p2222' --delete-after --delete-excluded   <folder> <user>@<site>:
 {% endhighlight %}
 
 Command line parameters are:
 
-- ```--rsh='ssh -p2222'``` It is needed if your hoster provides ssh access using ssh port different from default one (e.g., this is what hostgator is doing)
-- ```<folder>``` is the name of the local folder with generated web content. By default it is ```_site/``` for Jekyll
-- ```<user>``` &mdash; ssh user name for your hosting account
-- ```<site>``` &mdash; your hosting server
+- `--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
 
-Example command line is:
+Using this setup, you might run the following command:
 
 {% highlight bash %}
-rsync -avr --rsh='ssh -p2222' --delete-after --delete-excluded   _site/ hostuser@vrepin.org:
+rsync -crvz --rsh='ssh -p2222' --delete-after --delete-excluded   _site/ hostuser@example.org:
 {% endhighlight %}
 
-Don't forget column ':' after server name!
+Don't forget the column `:` after server name!
+
+#### Step 4 (Optional): Exclude the transfer script from being copied to the output folder.
 
-#### Optional step 4: exclude transfer.sh from being copied to the output folder by Jekyll
+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`.
 
-This step is recommended if you use this how-to to deploy Jekyll-based web site. If you put ```deploy``` script to the root folder of your project, Jekyll copies it to the output folder.
-This behavior can be changed in ```_config.yml```. Just add the following line there:
+Just add the following line:
 
 {% highlight yaml %}
-# Do not copy these file to the output directory
+# Do not copy these files to the output directory
 exclude: ["deploy"]
 {% endhighlight %}
 
-#### We are done!
+Alternatively, you can use an `rsync-exclude.txt` file to control which files will be transferred to your server.
 
-Now it's possible to publish your web site by launching ```deploy``` script. If your ssh certificate  is [passphrase-protected](https://martin.kleppmann.com/2013/05/24/improving-security-of-ssh-private-keys.html), you are asked to enter the password.
+#### 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
 
@@ -190,3 +203,11 @@ for that](https://github.com/openshift-cartridges/openshift-jekyll-cartridge).
   <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/extras.md

@@ -15,7 +15,7 @@ Kramdown comes with optional support for LaTeX to PNG rendering via [MathJax](ht
 <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/blog/opinion/2014/02/16/Mathjax-with-jekyll.html).
+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
 

data/site/_docs/github-pages.md

@@ -10,6 +10,31 @@ organizations, and repositories, that are freely hosted on GitHub's
 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.
@@ -92,42 +117,16 @@ 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.
+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>
 
-
-### 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. Here is an approach to
-utilizing the GitHub Project Page URL structure (`username.github.io/project-name/`)
-whilst maintaining the ability to preview your Jekyll site locally.
-
-1. In `_config.yml`, set the `baseurl` option to `/project-name` -- note the
-   leading slash and the **absence** of a trailing slash.
-2. When referencing JS or CSS files, do it like this:
-   `{% raw %}{{ site.baseurl }}/path/to/css.css{% endraw %}` -- note the slash
-   immediately following the variable (just before "path").
-3. When doing permalinks or internal links, do it like this:
-   `{% raw %}{{ site.baseurl }}{{ post.url }}{% endraw %}` -- note that there
-   is **no** slash between the two variables.
-4. Finally, if you'd like to preview your site before committing/deploying
-   using `jekyll serve`, be sure to pass an **empty string** to the `--baseurl`
-   option, so that you can view everything at `localhost:4000` normally
-   (without `/project-name` at the beginning): `jekyll serve --baseurl ''`
-
-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 start with `/project-name` and resolve properly.
-
 <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/20/articles">GitHub’s Pages Help
+    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>