Merge branch 'master' into release-3-4-0

* master: (39 commits)
  Update history to reflect merge of #5798 [ci skip]
  Update history to reflect merge of #5822 [ci skip]
  use logger.info
  run codeclimate after success
  Update history to reflect merge of #5819 [ci skip]
  Fixed inaccuracy in "Built-in permalink styles" docs [skip ci]
  Update history to reflect merge of #5802 [ci skip]
  Update history to reflect merge of #5811 [ci skip]
  Update history to reflect merge of #5690 [ci skip]
  Update history to reflect merge of #5815 [ci skip]
  Review CI pages
  Rework CI doc to include multiple providers.
  Update history to reflect merge of #5812 [ci skip]
  Add jekyll-ga plug-in
  Update configuration.md
  Add mention of classifier-reborn for LSI
  Update history to reflect merge of #5810 [ci skip]
  Got that diaper money?
  Added note about --blank flag
  Update history to reflect merge of #5797 [ci skip]
  ...

.codeclimate.yml

@@ -23,7 +23,7 @@ exclude_paths:
 
   - features/**/*
   - script/**/*
-  - site/**/*
+  - docs/**/*
   - spec/**/*
   - test/**/*
   - vendor/**/*

.travis.yml

@@ -45,3 +45,6 @@ addons:
         DA4vsRURfABU0fIhwYkQuZqEcA3d8TL36BZcGEshG6MQ2AmnYsmFiTcxqV5bmlElHEqQuT\
         5SUFXLafgZPBnL0qDwujQcHukID41sE=\
       "
+# regular test configuration
+after_success:
+  - bundle exec codeclimate-test-reporter

Gemfile

@@ -18,7 +18,7 @@ end
 #
 
 group :test do
-  gem "codeclimate-test-reporter", "~> 0.6.0"
+  gem "codeclimate-test-reporter", "~> 1.0.5"
   gem "cucumber", "~> 2.1"
   gem "jekyll_test_plugin"
   gem "jekyll_test_plugin_malicious"
@@ -69,7 +69,7 @@ group :jekyll_optional_dependencies do
   gem "jekyll-redirect-from"
   gem "kramdown", "~> 1.9"
   gem "mime-types", "~> 3.0"
-  gem "rdoc", "~> 4.2"
+  gem "rdoc", "~> 5.0"
   gem "toml", "~> 0.1.0"
 
   platform :ruby, :mswin, :mingw, :x64_mingw do

History.markdown

@@ -19,6 +19,7 @@
   * include: fix 'no implicit conversion of nil to String' (#5750)
   * Don't include the theme's includes_path if it is nil. (#5780)
   * test double slash when input = '/' (#5542)
+  * use logger.info for related posts (#5822)
 
 ### Site Enhancements
 
@@ -29,6 +30,7 @@
   * [site] Use defaults for docs and news-items (#5744)
   * Sort gems in `docs/_config.yml` (#5746)
   * Add missing class (#5791)
+  * Improve template docs (#5694)
 
 ### Development Fixes
 
@@ -49,6 +51,8 @@
   * Use latest jemoji gem (#5782)
   * Bump htmlproofer (#5781)
   * Bump rubies we test against (#5784)
+  * Bump rdoc to v5.0 (#5797)
+  * Bump codeclimate-test-reporter to v1.0.5 (#5798)
 
 ### Documentation
 
@@ -86,6 +90,15 @@
   * Fix a markdown link to look properly on the web (#5769)
   * [docs] Info about the help command usage (#5312)
   * Add missing merge labels for jekyllbot (#5753)
+  * Fix broken links in documentation (#5736)
+  * Docs: add `match_regex` and `replace_regex` filters (#5799)
+  * Got that diaper money? (#5810)
+  * Sort content by popularity using Google Analytics (#5812)
+  * Rework CI doc to include multiple providers. (#5815)
+  * Improve theme docs (#5690)
+  * Add mention of classifier-reborn for LSI (#5811)
+  * Added note about --blank flag (#5802)
+  * Fixed inaccuracy in "Built-in permalink styles" docs (#5819)
 
 ## 3.3.1 / 2016-11-14
 

docs/_docs/configuration.md

@@ -233,7 +233,7 @@ class="flag">flags</code> (specified on the command-line) that control them.
     <tr class="setting">
       <td>
         <p class="name"><strong>LSI</strong></p>
-        <p class="description">Produce an index for related posts.</p>
+        <p class="description">Produce an index for related posts. Requires the <a href="http://www.classifier-reborn.com/">classifier-reborn</a> plugin.</p>
       </td>
       <td class="align-center">
         <p><code class="option">lsi: BOOL</code></p>

docs/_docs/continuous-integration/circleci.md

@@ -0,0 +1,92 @@
+---
+title: "CircleCI"
+---
+
+Building, testing, and deploying your Jekyll-generated website can quickly be done with [CircleCI][0], a continuous integration & delivery tool. CircleCI supports [GitHub][1] and [Bitbucket][2], and you can get started for free using an open-source or private repository.
+
+[0]: https://circleci.com/
+[1]: https://github.com/
+[2]: https://bitbucket.org/
+
+## 1. Follow Your Project on CircleCI
+
+To start building your project on CircleCI, all you need to do is 'follow' your project from CircleCI's website:
+
+1. Visit the 'Add Projects' page: <https://circleci.com/add-projects>
+1. From the GitHub or Bitbucket tab on the left, choose a user or organization.
+1. Find your project in the list and click 'Build project' on the right.
+1. The first build will start on its own. You can start telling CircleCI how to build your project by creating a [circle.yml][3] file in the root of your repository.
+
+[3]: https://circleci.com/docs/configuration/
+
+## 2. Dependencies
+
+The easiest way to manage dependencies for a Jekyll project (with or without CircleCI) is via a [Gemfile][4]. You'd want to have Jekyll, any Jekyll plugins, [HTML Proofer](#html-proofer), and any other gems that you are using in the `Gemfile`. Don't forget to version `Gemfile.lock` as well. Here's an example `Gemfile`:
+
+[4]: http://bundler.io/gemfile.html
+
+```yaml
+source 'https://rubygems.org'
+
+ruby '2.4.0'
+
+gem 'jekyll'
+gem 'html-proofer'
+```
+
+CircleCI detects when `Gemfile` is present is will automatically run `bundle install` for you in the `dependencies` phase.
+
+## 3. Testing
+
+The most basic test that can be run is simply seeing if `jekyll build` actually works. This is a blocker, a dependency if you will,  for other tests you might run on the generate site. So we'll run Jekyll, via Bundler, in the `dependencies` phase.
+
+```
+dependencies:
+  post:
+    - bundle exec jekyll build
+```
+
+### HTML Proofer
+
+With your site built, it's useful to run tests to check for valid HTML, broken links, etc. There's a few tools out there but [HTML Proofer][5] is popular amongst Jekyll users. We'll run it in the `test` phase with a few preferred flags. Check out the `html-proofer` [README][6] for all available flags, or run `htmlproofer --help` locally.
+
+[5]: https://github.com/gjtorikian/html-proofer
+[6]: https://github.com/gjtorikian/html-proofer/blob/master/README.md#configuration
+
+```yaml
+test:
+  post:
+    - bundle exec htmlproofer ./_site --check-html --disable-external
+```
+
+## Complete Example circle.yml File
+
+When you put it all together, here's an example of what that `circle.yml` file could look like:
+
+```
+machine:
+  environment:
+    NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up installation of html-proofer
+
+dependencies:
+  post:
+    - bundle exec jekyll build
+
+test:
+  post:
+    - bundle exec htmlproofer ./_site --allow-hash-href --check-favicon --check-html --disable-external
+
+deployment:
+  prod:
+    branch: master
+    commands:
+      - rsync -va --delete ./_site username@my-website:/var/html
+```
+
+## Questions?
+
+This entire guide is open-source. Go ahead and [edit it][7] if you have a fix or [ask for help][8] if you run into trouble and need some help. CircleCI also has an [online community][9] for help.
+
+[7]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration/circleci.md
+[8]: https://jekyllrb.com/help/
+[9]: https://discuss.circleci.com

docs/_docs/continuous-integration/index.md

@@ -0,0 +1,9 @@
+---
+title: Continuous Integration
+permalink: /docs/continuous-integration/
+---
+
+Continuous Integration (CI) enables you to publish your Jekyll generated website with confidence by automating the quality assurance and deployment processes. You can quickly get started using CI with one of the providers below:
+
+* [Travis CI](travis-ci)
+* [CircleCI](circleci)

docs/_docs/continuous-integration/travis-ci.md

@@ -1,15 +1,13 @@
 ---
-title: Continuous Integration
+title: "Travis CI"
-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
+[Travis][travis], with [GitHub][github] integration for pull requests.
-alternatives exist for private repositories.
 
-[0]: https://travis-ci.org/
+[travis]: https://travis-ci.org/
-[1]: https://github.com/
+[github]: https://github.com/
 
 ## 1. Enabling Travis and GitHub
 
@@ -28,7 +26,7 @@ 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].
+When testing Jekyll output, there is no better tool than [html-proofer][html-proofer].
 This tool checks your resulting site to ensure all links and images exist.
 Utilize it either with the convenient `htmlproofer` command-line executable,
 or write a Ruby script which utilizes the gem.
@@ -70,7 +68,7 @@ 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
+[html-proofer]: https://github.com/gjtorikian/html-proofer
 
 ## 3. Configuring Your Travis Builds
 
@@ -93,7 +91,7 @@ Your `.travis.yml` file should look like this:
 ```yaml
 language: ruby
 rvm:
-- 2.2.5
+- 2.3.3
 
 before_script:
  - chmod +x ./script/cibuild # or do this locally and commit
@@ -126,7 +124,7 @@ access to Bundler, RubyGems, and a Ruby runtime.
 
 ```yaml
 rvm:
-- 2.2.5
+- 2.3.3
 ```
 
 RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This
@@ -228,5 +226,5 @@ an entry in the `.gitignore` file to avoid it from being checked in again.
 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/docs/_docs/continuous-integration.md
+[3]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration/travis-ci.md
 [4]: https://jekyllrb.com/help/

docs/_docs/deployment-methods.md

@@ -167,7 +167,7 @@ script executes.
 
 [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://andycroll.com/ruby/serving-a-jekyll-blog-using-heroku) on how to deploy to Heroku using Rack-Jekyll.
+Read [this post](http://andycroll.com/ruby/serving-a-jekyll-blog-using-heroku/) on how to deploy to Heroku using Rack-Jekyll.
 
 ## Jekyll-Admin for Rails
 
@@ -206,4 +206,3 @@ Setting up Kickster is very easy, just install the gem and you are good to go. M
 [Aerobatic](https://www.aerobatic.com) is an add-on for Bitbucket that brings GitHub Pages style functionality to Bitbucket users. It includes continuous deployment, custom domains with a wildcard SSL cert, CDN, basic auth, and staging branches all in the box.
 
 Automating the build and deployment of a Jekyll site is just as simple as GitHub Pages - push your changes to your repo (excluding the `_site` directory) and within seconds a build will be triggered and your built site deployed to our highly- available, globally distributed hosting service. The build process will even install and execute custom Ruby plugins. See our [Jekyll docs](https://www.aerobatic.com/docs/static-generators#jekyll) for more details.
-

docs/_docs/extras.md

@@ -14,7 +14,7 @@ Kramdown comes with optional support for LaTeX to PNG rendering via [MathJax](ht
 <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
 ```
 
-For more information about getting started, check out [this excellent blog post](https://web.archive.org/web/20160522225559/http://gastonsanchez.com/opinion/2014/02/16/Mathjax-with-jekyll).
+For more information about getting started, check out [this excellent blog post](http://gastonsanchez.com/visually-enforced/opinion/2014/02/16/Mathjax-with-jekyll/).
 
 ## Alternative Markdown Processors
 

docs/_docs/github-pages.md

@@ -11,15 +11,13 @@ 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
+This guide will teach you what you need to know about Git, GitHub, and Jekyll to create your very own website on GitHub Pages.
-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
+Project Pages complicates the proper resolution of URLs. In order to assure your site builds properly, use `site.github.url` in your URL's.
-site builds properly, use `site.github.url` in your URL's.
 
 ```html
 {% raw %}
@@ -90,7 +88,7 @@ gem 'github-pages'
 And be sure to run `bundle update` often.
 
 If you like to install `pages-gem` on Windows you can find instructions by Jens Willmer on
-[how to install github-pages gem on Windows (x64)]("https://jwillmer.de/blog/tutorial/how-to-install-jekyll-and-pages-gem-on-windows-10-x46#github-pages-and-plugins").
+[how to install github-pages gem on Windows (x64)](https://jwillmer.de/blog/tutorial/how-to-install-jekyll-and-pages-gem-on-windows-10-x46#github-pages-and-plugins).
 </div>
 
 <div class="note info">

docs/_docs/permalinks.md

@@ -230,7 +230,7 @@ Although you can specify a custom permalink pattern using [template variables](#
 </table>
 </div>
 
-Rather than typing `permalink: /:categories/:year/:month/:day/:title/`, you can just type `permalink: date`.
+Rather than typing `permalink: /:categories/:year/:month/:day/:title/`, you can just type `permalink: pretty`.
 
 <div class="note info">
 <h5>Specifying permalinks through the YAML Front Matter</h5>
@@ -327,7 +327,7 @@ As with posts, if you use a permalink style that omits the `.html` file extensio
 
 By default, collections follow a similar structure in the `_site` folder as pages, except that the path is prefaced by the collection name. For example: `collectionname/mypage.html`. For permalink settings that omit the file extension, the path would be `collection_name/mypage/index.html`.
 
-Collections have their own way of setting permalinks. Additionally, collections have unique template variables available available (such as `path` and `output_ext`). See the [Configuring permalinks for collections]( ../collections#permalinks ) in Collections for more information.
+Collections have their own way of setting permalinks. Additionally, collections have unique template variables available available (such as `path` and `output_ext`). See the [Configuring permalinks for collections](../collections/#permalinks) in Collections for more information.
 
 ## Flattening pages in \_site on build
 

docs/_docs/plugins.md

@@ -753,6 +753,7 @@ LESS.js files during generation.
 - [Jekyll::Paginate::Category](https://github.com/midnightSuyama/jekyll-paginate-category): Pagination Generator for Jekyll Category.
 - [AMP-Jekyll by Juuso Mikkonen](https://github.com/juusaw/amp-jekyll): Generate [Accelerated Mobile Pages](https://www.ampproject.org) of Jekyll posts.
 - [Jekyll Art Gallery plugin](https://github.com/alexivkin/Jekyll-Art-Gallery-Plugin): An advanced art/photo gallery generation plugin for creating galleries from a set of image folders. Supports image tagging, thumbnails, sorting, image rotation, post-processing (remove EXIF, add watermark), multiple collections and much more.
+- [jekyll-ga](https://github.com/developmentseed/jekyll-ga): A Jekyll plugin that downloads Google Analytics data and adds it to posts. Useful for making a site that lists "most popular" content. [Read the introduction](https://developmentseed.org/blog/google-analytics-jekyll-plugin/) post on the developmentSEED blog.
 
 #### Converters
 
@@ -803,6 +804,9 @@ LESS.js files during generation.
 - [jekyll-typogrify](https://github.com/myles/jekyll-typogrify): A Jekyll plugin that brings the functions of [typogruby](http://avdgaag.github.io/typogruby/).
 - [Jekyll Email Protect](https://github.com/vwochnik/jekyll-email-protect): Email protection liquid filter for Jekyll
 - [Jekyll Uglify Filter](https://github.com/mattg/jekyll-uglify-filter): A Liquid filter that runs your JavaScript through UglifyJS.
+- [match_regex](https://github.com/sparanoid/match_regex): A Liquid filter to perform regex match.
+- [replace_regex](https://github.com/sparanoid/replace_regex): A Liquid filter to perform regex replace.
+- [Jekyll Money](https://rubygems.org/gems/jekyll-money): A Jekyll plugin for dealing with money. Because we all have to at some point.
 
 #### Tags
 

docs/_docs/quickstart.md

@@ -3,8 +3,8 @@ title: Quick-start guide
 permalink: /docs/quickstart/
 ---
 
-If you already have a full [Ruby](https://www.ruby-lang.org/en/downloads/) development environment with all headers and [RubyGems](https://rubygems.org/pages/download) installed (see Jekyll's [requirements](/docs/installation/#requirements/)), you can create a new Jekyll site by doing the following:
 
+If you already have a full [Ruby](https://www.ruby-lang.org/en/downloads/) development environment with all headers and [RubyGems](https://rubygems.org/pages/download) installed (see Jekyll's [requirements](/docs/installation/#requirements/)), you can create a new Jekyll site by doing the following:
 
 ```sh
 # Install Jekyll and Bundler gems through RubyGems
@@ -40,6 +40,7 @@ If you encounter any unexpected errors during the above, please refer to the alr
 * To install the Jekyll site into the directory you're currently in, run `jekyll new .` If the existing directory isn't empty, you can pass the `--force` option with `jekyll new . --force`.
 * `jekyll new` automatically initiates `bundle install` to install the dependencies required. (If you don't want Bundler to install the gems, use `jekyll new myblog --skip-bundle`.)
 * By default, the Jekyll site installed by `jekyll new` uses a gem-based theme called [Minima](https://github.com/jekyll/minima). With [gem-based themes](../themes), some of the directories and files are stored in the theme-gem, hidden from your immediate view.
+* We recommend setting up Jekyll with a gem-based theme but if you want to start with a blank slate, use `jekyll new myblog --blank`
 * To learn about other parameters you can include with `jekyll new`, type `jekyll new --help`.
 
 When in doubt, use the <code>help</code> command to remind you of all available options and usage, it also works with the <code>new</code>, <code>build</code> and <code>serve</code> subcommands, e.g. <code>jekyll help new</code> or <code>jekyll help build</code>.

docs/_docs/templates.md

@@ -420,56 +420,15 @@ The default is `default`. They are as follows (with what they filter):
 
 ### Includes
 
-If you have small page fragments that you wish to include in multiple places on
+If you have small page snippets that you want to include in multiple places on your site, save the snippets as *include files* and insert them where required, by using the `include` tag:
-your site, you can use the `include` tag.
 
 ```liquid
 {% raw %}{% include footer.html %}{% endraw %}
 ```
 
-Jekyll expects all include files to be placed in an `_includes` directory at the
+Jekyll expects all *include files* to be placed in an `_includes` directory at the root of your source directory. In the above example, this will embed the contents of `_includes/footer.html` into the calling file.
-root of your source directory. This will embed the contents of
-`<source>/_includes/footer.html` into the calling file.
 
-<div class="note">
+For more advanced information on using includes, see [Includes](../includes).
-  <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:
-
-```liquid
-{% raw %}{% include footer.html param="value" variable-param=page.variable %}{% endraw %}
-```
-
-These parameters are available via Liquid in the include:
-
-```liquid
-{% raw %}{{ include.param }}{% endraw %}
-```
-
-#### Including files relative to another file
-
-You can also choose to include file fragments relative to the current file:
-
-```liquid
-{% raw %}{% include_relative somedir/footer.html %}{% endraw %}
-```
-
-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
 
@@ -529,64 +488,6 @@ 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.
 
-### Link
-
-If you want to include a link to a collection's document, a post, a page
-or a file the `link` tag will generate the correct permalink URL for the path
-you specify.
-
-You must include the file extension when using the `link` tag.
-
-```liquid
-{% raw %}
-{{ site.baseurl }}{% link _collection/name-of-document.md %}
-{{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %}
-{{ site.baseurl }}{% link news/index.html %}
-{{ site.baseurl }}{% link /assets/files/doc.pdf %}
-{% endraw %}
-```
-
-You can also use this tag to create a link in Markdown as follows:
-
-```liquid
-{% raw %}
-[Link to a document]({{ site.baseurl }}{% link _collection/name-of-document.md %})
-[Link to a post]({{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %})
-[Link to a page]({{ site.baseurl }}{% link news/index.html %})
-[Link to a file]({{ site.baseurl }}{% link /assets/files/doc.pdf %})
-{% endraw %}
-```
-
-### 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.
-
-```liquid
-{% raw %}
-{{ site.baseurl }}{% post_url 2010-07-21-name-of-post %}
-{% endraw %}
-```
-
-If you organize your posts in subdirectories, you need to include subdirectory
-path to the post:
-
-```liquid
-{% raw %}
-{{ site.baseurl }}{% post_url /subdir/2010-07-21-name-of-post %}
-{% endraw %}
-```
-
-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:
-
-```liquid
-{% raw %}
-[Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
-{% endraw %}
-```
-
 ### Gist
 
 Use the `gist` tag to easily embed a GitHub Gist onto your site. This works
@@ -608,3 +509,71 @@ You may also optionally specify the filename in the gist to display:
 
 To use the `gist` tag, you'll need to add the
 [jekyll-gist](https://github.com/jekyll/jekyll-gist) gem to your project.
+
+## Links
+
+### Linking to pages {#link}
+
+To link to a post, a page, collection item, or file, the `link` tag will generate the correct permalink URL for the path you specify. For example, if you use the `link` tag to link to `mypage.html`, even if you change your permalink style to include the file extension or omit it, the URL formed by the `link` tag will always be valid.
+
+You must include the file's original extension when using the `link` tag. Here are some examples:
+
+```liquid
+{% raw %}
+{{ site.baseurl }}{% link _collection/name-of-document.md %}
+{{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %}
+{{ site.baseurl }}{% link news/index.html %}
+{{ site.baseurl }}{% link /assets/files/doc.pdf %}
+{% endraw %}
+```
+
+You can also use the `link` tag to create a link in Markdown as follows:
+
+```liquid
+{% raw %}
+[Link to a document]({{ site.baseurl }}{% link _collection/name-of-document.md %})
+[Link to a post]({{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %})
+[Link to a page]({{ site.baseurl }}{% link news/index.html %})
+[Link to a file]({{ site.baseurl }}{% link /assets/files/doc.pdf %})
+{% endraw %}
+```
+
+(Including `{% raw %}{{ site.baseurl }}{% endraw %}` is optional &mdash; it depends on whether you want to preface the page URL with the `baseurl` value.)
+
+The path to the post, page, or collection is defined as the path relative to the root directory (where your config file is) to the file, not the path from your existing page to the other page.
+
+For example, suppose you're creating a link `page_a.md` (stored in `pages/folder1/folder2`) to `page_b.md` (stored in  `pages/folder1`). Your path in the link would not be `../page_b.html`. Instead, it would be `/pages/folder1/page_b.md`.
+
+If you're unsure of the path, add `{% raw %}{{ page.path }}{% endraw %}` to the page and it will display the path.
+
+One major benefit of using the `link` tag is link validation. If the link doesn't exist, Jekyll won't build your site. This is a good thing, as it will alert you to a broken link so you can fix it (rather than allowing you to build and deploy a site with broken links).
+
+Note you cannot add filters to `link` tags. For example, you cannot append a string using Liquid filters, such as `{% raw %}{% link mypage.html | append: "#section1" %} {% endraw %}`. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques.
+
+### Linking to posts
+
+If you want 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.
+
+```liquid
+{% raw %}
+{{ site.baseurl }}{% post_url 2010-07-21-name-of-post %}
+{% endraw %}
+```
+
+If you organize your posts in subdirectories, you need to include subdirectory path to the post:
+
+```liquid
+{% raw %}
+{{ site.baseurl }}{% post_url /subdir/2010-07-21-name-of-post %}
+{% endraw %}
+```
+
+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:
+
+```liquid
+{% raw %}
+[Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
+{% endraw %}
+```

docs/_docs/themes.md

@@ -3,64 +3,175 @@ 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, and stylesheets in a way that can be overridden by your site's content.
+Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site's content.
 
-## Installing a theme
+## Understanding gem-based themes
 
-1. To install a theme, first, add the theme to your site's `Gemfile`:
+When you [create a new Jekyll site](/docs/quickstart) (by running the `jekyll new <PATH>` command), Jekyll installs a site that uses a gem-based theme called [Minima](https://github.com/jekyll/minima).
 
-        gem 'my-awesome-jekyll-theme'
+With gem-based themes, some of the site's directories (such as the `assets`, `_layouts`, `_includes`, and `_sass` directories) are stored in the theme's gem, hidden from your immediate view. Yet all of the necessary directories will be read and processed during Jekyll's build process.
 
-2. Save the changes to your `Gemfile`
+In the case of Minima, you see only the following files in your Jekyll site directory:
-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`:
 
-        theme: my-awesome-jekyll-theme
+```
+├── Gemfile
+├── Gemfile.lock
+├── _config.yml
+├── _posts
+│   └── 2016-12-04-welcome-to-jekyll.markdown
+├── about.md
+└── index.md
+```
 
-You can have multiple themes listed in your site's Gemfile, but only one theme can be selected in your site's `_config.yml`.
+The `Gemfile` and `Gemfile.lock` files are used by Bundler to keep track of the required gems and gem versions you need to build your Jekyll site.
-{: .note .info }
+
+Gem-based themes make it easy for theme developers to make updates available to anyone who has the theme gem. When there's an update, theme developers push the update to RubyGems.
+
+If you have the theme gem, you can (if you desire) run `bundle update` to update all gems in your project. Or you can run `bundle update <THEME>`, replacing `<THEME>` with the theme name, such as `minima`, to just update the theme gem. Any new files or updates the theme developer has made (such as to stylesheets or includes) will be pulled into your project automatically.
+
+The goal of gem-based themes is to allow you to get all the benefits of a robust, continually updated theme without having all the theme's files getting in your way and over-complicating what might be your primary focus: creating content.
 
 ## Overriding theme defaults
 
-Jekyll themes set default layouts, includes, and stylesheets, 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 themes set default layouts, includes, and stylesheets. However, you can override any of the theme defaults with your own site content.
 
-Jekyll will look first to your site's content, before looking to the theme's defaults, for any requested file in the following folders:
+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` directory (that is, `_layouts/page.html`).
 
-* `/assets`
+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`
+- `/assets`
-* `/_sass`
+- `/_layouts`
+- `/_includes`
+- `/_sass`
 
 Refer to your selected theme's documentation and source repository for more information on what files you can override.
 {: .note .info}
 
-To locate theme's files on your computer, run `bundle show` followed by
+To locate theme's files on your computer:
-the name of the theme's gem, e.g. `bundle show minima` for default Jekyll's
-theme. Then copy the files you want to override, from the returned path to your root folder.
 
-## Creating a theme
+1. Run `bundle show` followed by the name of the theme's gem, e.g., `bundle show minima` for default Jekyll's theme.
 
-Jekyll themes are distributed as Ruby gems. Don't worry, Jekyll will help you scaffold a new theme with the `new-theme` command. Just run `jekyll new-theme` with the theme name as an argument:
+   This returns the location of the gem-based theme files. For example, Minima theme's files are located in `/usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0` on macOS.
+
+2. Open the theme's directory in Finder or Explorer:
+
+   ```shell
+   # On MacOS
+   open $(bundle show minima)
+   # On Windows
+   explorer /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0
+   ```
+
+   A Finder or Explorer window opens showing the theme's files and directories. The Minima theme gem contains these files:
+
+    ```
+    ├── LICENSE.txt
+    ├── README.md
+    ├── _includes
+    │   ├── disqus_comments.html
+    │   ├── footer.html
+    │   ├── google-analytics.html
+    │   ├── head.html
+    │   ├── header.html
+    │   ├── icon-github.html
+    │   ├── icon-github.svg
+    │   ├── icon-twitter.html
+    │   └── icon-twitter.svg
+    ├── _layouts
+    │   ├── default.html
+    │   ├── home.html
+    │   ├── page.html
+    │   └── post.html
+    ├── _sass
+    │   ├── minima
+    │   │   ├── _base.scss
+    │   │   ├── _layout.scss
+    │   │   └── _syntax-highlighting.scss
+    │   └── minima.scss
+    └── assets
+        └── main.scss
+     ```
+
+     With a clear understanding of the theme's files, you can now override any theme file by creating a similarly named file in your Jekyll site directory.
+
+     Let's say you want to override Minima's footer. In your Jekyll site, create an `_includes` folder and add a file in it called `footer.html`. Jekyll will now use your site's `footer.html` file instead of the `footer.html` file from the Minima theme gem.
+
+## Converting gem-based themes to regular themes
+
+Suppose you want to get rid of the gem-based theme and convert it to a regular theme, where all files are present in your Jekyll site directory, with nothing stored in the theme gem.
+
+To do this, copy the files from the theme gem's directory into your Jekyll site directory. (For example, copy them to `/myblog` if you created your Jekyll site at `/myblog`. See the previous section for details.)
+
+Then remove references to the theme gem in `Gemfile` and configuration. For example, to remove `minima`:
+
+- Open `Gemfile` and remove `gem "minima", "~> 2.0"`.
+- Open `_config.yml` and remove `theme: minima`.
+
+Now `bundle update` will no longer get updates for the theme gem.
+
+## Installing a gem-based theme {#installing-a-theme}
+
+The `jekyll new <PATH>` command isn't the only way to create a new Jekyll site with a gem-based theme. You can also find gem-based themes online and incorporate them into your Jekyll project.
+
+For example, search for [jekyll theme on RubyGems](https://rubygems.org/search?utf8=%E2%9C%93&query=jekyll-theme) to find other gem-based themes. (Note that not all themes are using `jekyll-theme` as a convention in the theme name.)
+
+To install a gem-based theme:
+
+1. Add the theme to your site's `Gemfile`:
+
+   ```sh
+   gem "jekyll-theme-awesome"
+   ```
+
+2. Install the theme:
+
+   ```sh
+   bundle install
+   ```
+
+3. Add the following to your site's `_config.yml` to activate the theme:
+
+   ```sh
+   theme: jekyll-theme-awesome
+   ```
+
+4. Build your site:
+
+   ```sh
+   bundle exec jekyll serve
+   ```
+
+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 }
+
+If you're publishing your Jekyll site on [GitHub Pages](https://pages.github.com/), note that GitHub Pages supports only some gem-based themes. See [Supported Themes](https://pages.github.com/themes/) in GitHub's documentation to see which themes are supported.
+
+## Creating a gem-based theme
+
+If you're a Jekyll theme developer (rather than just a consumer of themes), you can package up your theme in RubyGems and allow users to install it through Bundler.
+
+If you're unfamiliar with creating Ruby gems, don't worry. Jekyll will help you scaffold a new theme with the `new-theme` command. Run `jekyll new-theme` with the theme name as an argument.
+
+Here is an example:
 
 ```sh
-jekyll new-theme my-awesome-theme
+jekyll new-theme jekyll-theme-awesome
-             create /path/to/my-awesome-theme/_layouts
+    create /path/to/jekyll-theme-awesome/_layouts
-             create /path/to/my-awesome-theme/_includes
+    create /path/to/jekyll-theme-awesome/_includes
-             create /path/to/my-awesome-theme/_sass
+    create /path/to/jekyll-theme-awesome/_sass
-             create /path/to/my-awesome-theme/_layouts/page.html
+    create /path/to/jekyll-theme-awesome/_layouts/page.html
-             create /path/to/my-awesome-theme/_layouts/post.html
+    create /path/to/jekyll-theme-awesome/_layouts/post.html
-             create /path/to/my-awesome-theme/_layouts/default.html
+    create /path/to/jekyll-theme-awesome/_layouts/default.html
-             create /path/to/my-awesome-theme/Gemfile
+    create /path/to/jekyll-theme-awesome/Gemfile
-             create /path/to/my-awesome-theme/my-awesome-theme.gemspec
+    create /path/to/jekyll-theme-awesome/jekyll-theme-awesome.gemspec
-             create /path/to/my-awesome-theme/README.md
+    create /path/to/jekyll-theme-awesome/README.md
-             create /path/to/my-awesome-theme/LICENSE.txt
+    create /path/to/jekyll-theme-awesome/LICENSE.txt
-         initialize /path/to/my-awesome-theme/.git
+    initialize /path/to/jekyll-theme-awesome/.git
-             create /path/to/my-awesome-theme/.gitignore
+    create /path/to/jekyll-theme-awesome/.gitignore
-Your new Jekyll theme, my-awesome-theme, is ready for you in /path/to/my-awesome-theme!
+Your new Jekyll theme, jekyll-theme-awesome, is ready for you in /path/to/jekyll-theme-awesome!
-For help getting started, read /path/to/my-awesome-theme/README.md.
+For help getting started, read /path/to/jekyll-theme-awesome/README.md.
 ```
 
-Add your template files in the corresponding folders, complete the `.gemspec` and the README files according to your needs.
+Add your template files in the corresponding folders. Then complete the `.gemspec` and the README files according to your needs.
 
 ### Layouts and includes
 
@@ -70,13 +181,29 @@ For example, if your theme has a `/_layouts/page.html` file, and a page has `lay
 
 ### Assets
 
-Any file in `/assets` will be copied over to the user's site upon build unless they have a file with the same relative path. You may ship any kind of asset here: SCSS, an image, a webfont, etc. These files behave just like pages and static files in Jekyll: if the file has [YAML front matter]({{ site.baseurl }}/docs/frontmatter/) at the top, then it will be rendered. If it does not have YAML front matter, it will simply be copied over into the resulting site. This allows theme creators to ship a default `/assets/styles.scss` file which their layouts can depend on as `/assets/styles.css`.
+Any file in `/assets` will be copied over to the user's site upon build unless they have a file with the same relative path. You can ship any kind of asset here: SCSS, an image, a webfont, etc. These files behave like pages and static files in Jekyll:
+
+- If the file has [YAML front matter](../docs/frontmatter/) at the top, it will be rendered.
+- If the file does not have YAML front matter, it will simply be copied over into the resulting site.
+
+This allows theme creators to ship a default `/assets/styles.scss` file which their layouts can depend on as `/assets/styles.css`.
 
 All files in `/assets` will be output into the compiled site in the `/assets` folder just as you'd expect from using Jekyll on your sites.
 
 ### 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.
+Your theme's stylesheets should be placed in your theme's `_sass` folder, again, just as you would when authoring a Jekyll site.
+
+```
+_sass
+├── jekyll-theme-awesome.scss
+```
+
+Your theme's styles can be included in the user's stylesheet using the `@import` directive.
+
+```css
+{% raw %}@import "{{ site.theme }}";{% endraw %}
+```
 
 ### Documenting your theme
 
@@ -90,20 +217,22 @@ Themes are visual. Show users what your theme looks like by including a screensh
 
 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.
+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}
-{: .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).
+Themes are published via [RubyGems.org](https://rubygems.org). You will 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:
+1. First, package your theme, by running the following command, replacing `jekyll-theme-awesome` with the name of your theme:
 
-        gem build my-awesome-jekyll-theme.gemspec
+   ```sh
+   gem build jekyll-theme-awesome.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:
+2. Next, push your packaged theme up to the RubyGems service, by running the following command, again replacing `jekyll-theme-awesome` with the name of your theme:
 
-        gem push my-awesome-jekyll-theme-*.gem
+   ```sh
+   gem push jekyll-theme-awesome-*.gem
+   ```
 
-3. To release a new version of your theme, simply update the version number in the gemspec file, ( `my-awesome-jekyll-theme.gemspec` in this example ), and then repeat Steps 1 & 2 above.
+3. To release a new version of your theme, update the version number in the gemspec file, ( `jekyll-theme-awesome.gemspec` in this example ), and then repeat Steps 1 & 2 above. We recommend that you follow [Semantic Versioning](http://semver.org/) while bumping your theme-version.
-We recommend that you follow [Semantic Versioning](http://semver.org/) while bumping your theme-version.

lib/jekyll/related_posts.rb

@@ -26,15 +26,15 @@ module Jekyll
     def build_index
       self.class.lsi ||= begin
         lsi = ClassifierReborn::LSI.new(:auto_rebuild => false)
-        display("Populating LSI...")
+        Jekyll.logger.info("Populating LSI...")
 
         site.posts.docs.each do |x|
           lsi.add_item(x)
         end
 
-        display("Rebuilding index...")
+        Jekyll.logger.info("Rebuilding index...")
         lsi.build_index
-        display("")
+        Jekyll.logger.info("")
         lsi
       end
     end
@@ -46,11 +46,5 @@ module Jekyll
     def most_recent_posts
       @most_recent_posts ||= (site.posts.docs.reverse - [post]).first(10)
     end
-
-    def display(output)
-      $stdout.print("\n")
-      $stdout.print(Jekyll.logger.formatted_topic(output))
-      $stdout.flush
-    end
   end
 end

test/helper.rb

@@ -10,8 +10,8 @@ def jruby?
 end
 
 if ENV["CI"]
-  require "codeclimate-test-reporter"
+  require "simplecov"
-  CodeClimate::TestReporter.start
+  SimpleCov.start
 else
   require File.expand_path("../simplecov_custom_profile", __FILE__)
   SimpleCov.start "gem" do