Release 💎 4.0.1

Update item_property to recognize integers
This backports eb81dc0 to 4.0-stable

Co-authored-by: Ivan Gromov <summer.is.gone@gmail.com>

.codeclimate.yml

@@ -1,36 +1,53 @@
-engines:
+version: "2"
+checks:
+  argument-count:
+    enabled: true
+    config:
+      threshold: 5
+  file-lines:
+    enabled: true
+    config:
+      threshold: 300
+  method-complexity:
+    enabled: true
+    config:
+      threshold: 15
+  method-count:
+    enabled: true
+    config:
+      threshold: 50
+  method-lines:
+    enabled: true
+    config:
+      threshold: 30
+plugins:
   fixme:
     enabled: false
   rubocop:
     enabled: true
-    channel: rubocop-0-54
+    channel: rubocop-0-60
 
-exclude_paths:
-  - .codeclimate.yml
-  - .gitignore
-  - .rspec
-  - .rubocop.yml
-  - .travis.yml
+exclude_patterns:
+  - "*.*"
+  - ".*"
 
-  - Gemfile.lock
-  - CHANGELOG.{md,markdown,txt,textile}
-  - CONTRIBUTING.{md,markdown,txt,textile}
-  - readme.{md,markdown,txt,textile}
-  - README.{md,markdown,txt,textile}
-  - Readme.{md,markdown,txt,textile}
-  - ReadMe.{md,markdown,txt,textile}
-  - COPYING
+  - Gemfile
   - LICENSE
+  - Rakefile
 
-  - features/**/*
-  - script/**/*
-  - docs/**/*
-  - spec/**/*
-  - test/**/*
-  - vendor/**/*
+  - benchmark/
+  - docs/
+  - exe/
+  - features/
+  - rake/
+  - rubocop/
+  - script/
+  - spec/
+  - test/
+  - vendor/
 
+  - lib/blank_template/
+  - lib/site_template/
+  - lib/theme_template/
+  - lib/jekyll/mime.types
   - lib/jekyll/commands/serve/livereload_assets/livereload.js
-
-ratings:
-  paths:
-    - lib/**/*.rb

.github/CONTRIBUTING.markdown

@@ -4,7 +4,7 @@ Hi there! Interested in contributing to Jekyll? We'd love your help. Jekyll is a
 
 ## Where to get help or report a problem
 
-See [the support guidelines](https://jekyllrb.com/docs/support/)
+See the [support guidelines](https://jekyllrb.com/docs/support/)
 
 ## Ways to contribute
 
@@ -12,9 +12,9 @@ Whether you're a developer, a designer, or just a Jekyll devotee, there are lots
 
 * [Install Jekyll on your computer](https://jekyllrb.com/docs/installation/) and kick the tires. Does it work? Does it do what you'd expect? If not, [open an issue](https://github.com/jekyll/jekyll/issues/new) and let us know.
 * Comment on some of the project's [open issues](https://github.com/jekyll/jekyll/issues). Have you experienced the same problem? Know a work around? Do you have a suggestion for how the feature could be better?
-* Read through [the documentation](https://jekyllrb.com/docs/home/), and click the "improve this page" button, any time you see something confusing, or have a suggestion for something that could be improved.
-* Browse through [the Jekyll discussion forum](https://talk.jekyllrb.com/), and lend a hand answering questions. There's a good chance you've already experienced what another user is experiencing.
-* Find [an open issue](https://github.com/jekyll/jekyll/issues) (especially [those labeled `help-wanted`](https://github.com/jekyll/jekyll/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)), and submit a proposed fix. If it's your first pull request, we promise we won't bite, and are glad to answer any questions.
+* Read through the [documentation](https://jekyllrb.com/docs/home/), and click the "improve this page" button, any time you see something confusing, or have a suggestion for something that could be improved.
+* Browse through the [Jekyll discussion forum](https://talk.jekyllrb.com/), and lend a hand answering questions. There's a good chance you've already experienced what another user is experiencing.
+* Find an [open issue](https://github.com/jekyll/jekyll/issues) (especially [those labeled `help-wanted`](https://github.com/jekyll/jekyll/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)), and submit a proposed fix. If it's your first pull request, we promise we won't bite, and are glad to answer any questions.
 * Help evaluate [open pull requests](https://github.com/jekyll/jekyll/pulls), by testing the changes locally and reviewing what's proposed.
 
 ## Submitting a pull request
@@ -49,7 +49,7 @@ That's it! You'll be automatically subscribed to receive updates as others revie
 2. Clone the repository locally `git clone https://github.com/<you-username>/jekyll`.
 3. Create a new, descriptively named branch to contain your change ( `git checkout -b my-awesome-feature` ).
 4. Hack away, add tests. Not necessarily in that order.
-5. Make sure everything still passes by running `script/cibuild` (see [the tests section](#running-tests-locally) below)
+5. Make sure everything still passes by running `script/cibuild` (see the [tests section](#running-tests-locally) below)
 6. Push the branch up ( `git push origin my-awesome-feature` ).
 7. Create a pull request by visiting `https://github.com/<your-username>/jekyll` and following the instructions at the top of the screen.
 
@@ -89,7 +89,7 @@ If you want to add your plugin to the [list of plugins](https://jekyllrb.com/doc
 
 ## Code Contributions
 
-Interesting in submitting a pull request? Awesome. Read on. There's a few common gotchas that we'd love to help you avoid.
+Interested in submitting a pull request? Awesome. Read on. There's a few common gotchas that we'd love to help you avoid.
 
 ### Tests and documentation
 
@@ -115,6 +115,8 @@ If your contribution changes any Jekyll behavior, make sure to update the docume
 Jekyll's methods. It also provides you with helpful methods to quickly create a
 site or configuration. [Feel free to check it out!](https://github.com/jekyll/jekyll/blob/master/script/console)
 
+* Previously, we've used the WIP Probot app to help contributors determine whether their pull request is ready for review. Please use a [draft pull request](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests) instead. When you're ready, [mark the pull request as ready for review](https://help.github.com/en/articles/changing-the-stage-of-a-pull-request)
+
 ## Running tests locally
 
 ### Test Dependencies

.github/FUNDING.yml

@@ -0,0 +1,5 @@
+# These are supported funding model platforms
+
+github: [ashmaroli, DirtyF, mattr-]
+open_collective: jekyll
+tidelift: rubygems/jekyll

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,10 @@
 ---
 name: Bug Report
 about: Is something not working as expected?
+title: ''
+labels: ''
+assignees: ''
+
 ---
 
 <!--

.github/ISSUE_TEMPLATE/documentation.md

@@ -1,6 +1,10 @@
 ---
 name: Documentation
 about: Found a typo or something that isn't crystal clear in our docs?
+title: 'docs: '
+labels: documentation
+assignees: DirtyF
+
 ---
 
 <!-- Thanks for taking the time to open an issue and help us make Jekyll better! -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,6 +1,10 @@
 ---
 name: Feature Request
 about: Want us to add any features to Jekyll?
+title: 'feat: '
+labels: feature
+assignees: ''
+
 ---
 
 <!--

.github/ISSUE_TEMPLATE/question.md

@@ -1,6 +1,10 @@
 ---
 name: Question
 about: Have any questions about how Jekyll works?
+title: ''
+labels: ''
+assignees: ''
+
 ---
 
 <!--

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,7 +20,7 @@
 
   - I've added tests (if it's a bug, feature or enhancement)
   - I've adjusted the documentation (if it's a feature or enhancement)
-  - The test suite passes (run `script/cibuild` to verify this)
+  - The test suite passes locally (run `script/cibuild` to verify this)
 -->
 
 ## Summary
@@ -33,11 +33,13 @@
 
 <!--
   Is this related to any GitHub issue(s)?
--->
 
-## Semver Changes
+  You can use keywords to automatically close the related issue.
+  For example, (all of) the following will close issue #4567 when your PR is merged.
 
-<!--
-  Which semantic version change would you recommend?
-  If you don't know, feel free to omit it.
+  Closes #4567
+  Fixes #4567
+  Resolves #4567
+
+  Use any one of the above as applicable.
 -->

.github/config.yml

@@ -0,0 +1,15 @@
+updateDocsComment: >
+  Thanks for opening this pull request! The maintainers of this repository would appreciate it if you would update some of our documentation based on your changes.
+
+updateDocsWhiteList:
+  - bug
+  - fix
+  - Backport
+  - dev
+  - Update
+  - WIP
+  - chore
+
+updateDocsTargetFiles:
+  - README
+  - docs/

.rubocop.yml

@@ -1,6 +1,7 @@
 ---
 
 require:
+  - rubocop-performance
   - ./rubocop/jekyll
 
 Jekyll/NoPutsAllowed:
@@ -8,7 +9,7 @@ Jekyll/NoPutsAllowed:
     - rake/*.rake
 
 AllCops:
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.4
   Include:
     - lib/**/*.rb
     - test/**/*.rb
@@ -23,9 +24,9 @@ Layout/AlignHash:
   EnforcedHashRocketStyle: table
 Layout/IndentationWidth:
   Severity: error
-Layout/IndentArray:
+Layout/IndentFirstArrayElement:
   EnforcedStyle: consistent
-Layout/IndentHash:
+Layout/IndentFirstHashElement:
   EnforcedStyle: consistent
 Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
@@ -92,9 +93,6 @@ Naming/MemoizedInstanceVariableName:
     - lib/jekyll/drops/site_drop.rb
     - lib/jekyll/drops/unified_payload_drop.rb
     - lib/jekyll/page_without_a_file.rb
-Naming/UncommunicativeMethodParamName:
-  AllowedNames:
-    - _
 Security/MarshalLoad:
   Exclude:
     - !ruby/regexp /test\/.*.rb$/
@@ -109,6 +107,8 @@ Style/Alias:
   EnforcedStyle: prefer_alias_method
 Style/AndOr:
   Severity: error
+Style/BracesAroundHashParameters:
+  Enabled: false
 Style/ClassAndModuleChildren:
   Exclude:
     - test/**/*.rb

.travis.yml

@@ -1,14 +1,14 @@
-bundler_args: --without benchmark:site:development
+bundler_args: --without benchmark:development
 script: script/cibuild
 cache: bundler
 language: ruby
-sudo: false
 
 rvm:
-  - &ruby1 2.5.1
-  - &ruby2 2.4.4
-  - &ruby3 2.3.7
-  - &jruby jruby-9.1.16.0
+  - &ruby1 2.7.1
+  - &ruby2 2.6.6
+  - &ruby3 2.5.8
+  - &ruby4 2.4.10
+  - &jruby jruby-9.2.11.1
 
 matrix:
   include:
@@ -18,6 +18,12 @@ matrix:
     - rvm: *ruby1
       env: TEST_SUITE=default-site
       name: "🏠️ Default Site"
+    - rvm: *ruby1
+      env: TEST_SUITE=profile-docs
+      name: "Profile Docs"
+    - rvm: *ruby4
+      env: TEST_SUITE=memprof
+      name: "Profile Memory Allocation"
   exclude:
     - rvm: *jruby
       env: TEST_SUITE=cucumber
@@ -30,10 +36,18 @@ branches:
   only:
     - master
     - themes
-    - /^.*-stable/
-    - /.*backport.*/
+    - /.*-stable/
+
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
 
 notifications:
+  email: false
   slack:
     secure: "\
       dNdKk6nahNURIUbO3ULhA09/vTEQjK0fNbgjVjeYPEvROHgQBP1cIP3AJy8aWs8rl5Yyow4Y\
@@ -41,18 +55,6 @@ notifications:
       O1AanCUbJSEyJTju347xCBGzESU=\
     "
 
-addons:
-  code_climate:
-    repo_token:
-      secure: "\
-        mAuvDu+nrzB8dOaLqsublDGt423mGRyZYM3vsrXh4Tf1sT+L1PxsRzU4gLmcV27HtX2Oq9\
-        DA4vsRURfABU0fIhwYkQuZqEcA3d8TL36BZcGEshG6MQ2AmnYsmFiTcxqV5bmlElHEqQuT\
-        5SUFXLafgZPBnL0qDwujQcHukID41sE=\
-      "
-# regular test configuration
-after_success:
-  - bundle exec codeclimate-test-reporter
-
 before_install:
-  - gem update --system
-  - gem install bundler
+  - gem update --system --no-document
+  - gem install bundler --no-document

CODE_OF_CONDUCT.markdown

@@ -2,11 +2,17 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment include:
+Examples of behavior that contributes to creating a positive environment
+include:
 
 * Using welcoming and inclusive language
 * Being respectful of differing viewpoints and experiences
@@ -16,31 +22,55 @@ Examples of behavior that contributes to creating a positive environment include
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
 
-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.
+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.
 
 ## Scope
 
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting a project maintainer. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [olivia@jekyllrb.com](mailto:olivia@jekyllrb.com). All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
 
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html][version]
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)
 
-[homepage]: https://www.contributor-covenant.org/
-[version]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)

Gemfile

@@ -3,31 +3,36 @@
 source "https://rubygems.org"
 gemspec :name => "jekyll"
 
+# Temporarily lock JRuby builds on Travis CI to i18n-1.2.x until JRuby is able to handle
+# refinements introduced in i18n-1.3.0
+gem "i18n", "~> 1.2.0" if RUBY_ENGINE == "jruby"
+
 gem "rake", "~> 12.0"
 
 group :development do
   gem "launchy", "~> 2.3"
   gem "pry"
 
-  unless RUBY_ENGINE == "jruby"
-    gem "pry-byebug"
-  end
+  gem "pry-byebug" unless RUBY_ENGINE == "jruby"
 end
 
 #
 
 group :test do
-  gem "codeclimate-test-reporter", "~> 1.0.5"
   gem "cucumber", "~> 3.0"
   gem "httpclient"
   gem "jekyll_test_plugin"
   gem "jekyll_test_plugin_malicious"
+  gem "memory_profiler"
   gem "nokogiri", "~> 1.7"
   gem "rspec"
   gem "rspec-mocks"
-  gem "rubocop", "~> 0.60.0"
+  gem "rubocop", "~> 0.72.0"
+  gem "rubocop-performance"
   gem "test-dependency-theme", :path => File.expand_path("test/fixtures/test-dependency-theme", __dir__)
   gem "test-theme", :path => File.expand_path("test/fixtures/test-theme", __dir__)
+  gem "test-theme-skinny", :path => File.expand_path("test/fixtures/test-theme-skinny", __dir__)
+  gem "test-theme-symlink", :path => File.expand_path("test/fixtures/test-theme-symlink", __dir__)
 
   gem "jruby-openssl" if RUBY_ENGINE == "jruby"
 end
@@ -35,9 +40,7 @@ end
 #
 
 group :test_legacy do
-  if RUBY_PLATFORM =~ %r!cygwin!
-    gem "test-unit"
-  end
+  gem "test-unit" if RUBY_PLATFORM =~ %r!cygwin!
 
   gem "minitest"
   gem "minitest-profile"
@@ -60,34 +63,35 @@ end
 #
 
 group :jekyll_optional_dependencies do
-  gem "coderay", "~> 1.1.0"
   gem "jekyll-coffeescript"
   gem "jekyll-docs", :path => "../docs" if Dir.exist?("../docs") && ENV["JEKYLL_VERSION"]
   gem "jekyll-feed", "~> 0.9"
   gem "jekyll-gist"
   gem "jekyll-paginate"
   gem "jekyll-redirect-from"
-  gem "kramdown", "~> 1.14"
+  gem "kramdown-syntax-coderay"
   gem "mime-types", "~> 3.0"
   gem "rdoc", "~> 6.0"
   gem "tomlrb", "~> 1.2"
 
   platform :ruby, :mswin, :mingw, :x64_mingw do
-    gem "classifier-reborn", "~> 2.2.0"
-    gem "liquid-c", "~> 3.0"
+    gem "classifier-reborn", "~> 2.2"
+    gem "liquid-c", "~> 4.0"
     gem "yajl-ruby", "~> 1.4"
   end
 
-  # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
-  gem "tzinfo-data", :platforms => [:mingw, :mswin, :x64_mingw, :jruby]
+  # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+  # and associated library
+  install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
+    gem "tzinfo", "~> 1.2"
+    gem "tzinfo-data"
+  end
 end
 
 #
 
 group :site do
-  if ENV["PROOF"]
-    gem "html-proofer", "~> 3.4"
-  end
+  gem "html-proofer", "~> 3.4" if ENV["PROOF"]
 
   gem "jekyll-avatar"
   gem "jekyll-mentions"

History.markdown

@@ -1,172 +1,328 @@
-## HEAD
-
-  * Textile is only supported through a converter plugin (#7003)
-  * Add info how to deploy using pre-push git hook (#7179)
-  * chore(release): reflect latest patched releases (#7262)
-
-### Documentation
-
-  * Release post for v3.8.0 (#6849)
-  * Add Installation Instructions for Ubuntu (#6925)
-  * add liquid tag jekyll-flickr (#6946)
-  * Add 4.0 development post (#6934)
-  * Updated copy - fixed casing of SaaS on resources page. (#6949)
-  * WIP: Do not advise users to install Jekyll outside of Bundler (#6927)
-  * Don't prompt for sudo when installing with Ubuntu WSL (#6781)
-  * Fix typo (#6969)
-  * Add version number for group_by_exp doc (#6956)
-  * Update Windows install docs (#6926)
-  * Remove documentation for using Redcarpet (#6990)
-  * Updated nginx configuration for custom-404-page documentation (#6994)
-  * List all static files variables (#7002)
-  * Document that _drafts need to be contained within the custom collection directory (#6985)
-  * proposed change for passive voice. (#7005)
-  * added the CAT plugin to the plugin list (#7011)
-  * Updated to supported version (#7031)
-  * Clarify definition of 'draft' (#7037)
-  * Listed the jekyll-target-blank plugin in plugins list. (#7046)
-  * Typo (#7058)
-  * Add Hints for some Improved Travis Config in Doc (#7049)
-  * Added plugin json-get. (#7086)
-  * Update travis-ci.md to point out "this is an example Gemfile" (#7089)
-  * Adding `jekyll-info` plugin (#7091)
-  * GitHub enables you to use themes from other repos (#7112)
-  * Updates to CODE OF CONDUCT  (v1.4.0) (#7105)
-  * Instructions to view theme’s files under Linux (#7095)
-  * add jekyll-xml-source (#7114)
-  * Add the jekyll-firstimage filter plugin (#7127)
-  * Use a real theme in the example (#7125)
-  * Update docs about post creation (#7138)
-  * Add DEV Community's Jekyll tag to community page (#7139)
-  * Initialize upgrading doc for v4.0 (#7140)
-  * Add version badge for date filters with ordinal (#7162)
-  * Add closing tags for <a> (#7163)
-  * Add TSV to list of supported _data files. (#7168)
-  * Corrected sample usage of postfiles (#7181)
-  * Add missing html end tag for code example in section 'For loops' (#7199)
-  * Resolve "Unable to locate package ruby2.4" error (#7196)
-  * installation instructions for Fedora (#7198)
-  * New docs (#7205)
-  * Correct stylesheet url in tutorial step 7 (#7210)
-  * Add some minor improvements to image loading in Showcase page (#7214)
-  * Fix minor grammatical error (#7215)
-  * Add developer.spotify.com to the Jekyll Showcase (#7217)
-  * removes quotes from markdown for assets (#7223)
-  * clarified front matter requirement (#7234)
-  * Minor whitespace fixes (#7238)
-  * explicit location of where to create blog.html (#7241)
-  * Fix a small grammar error/typo in the docs (#7260)
-  * environments.md: reference the build command options that allows multiple config files (#7266)
-  * Update 10-deployment.md (#7268)
-  * Add more issue template(s) and pull request template (#7269)
-  * Suggest sites use OpenSSL instead of GnuTLS for their site's CI (#7010)
-  * Fix broken Contributors link in README.markdown (#7200)
-  * Docs: Add title tag to item in RSS template (#7282)
-  * Docs: more inclusive writing (#7283)
-  * Document converter methods (#7289)
-  * Docs: Add link tag to item in RSS template (#7291)
-  * Add Isomer to showcase (#7300)
-  * Added missing semicolon (#7306)
-  * "This restricts you..." to "This restricts your" (#7307)
-  * Add a link to Giraffe Academy's tutorial (#7325)
-  * grammar correction (#7327)
-  * docs: list all standard liquid filters (#7333)
-  * Document Jekyll Filters with YAML data (#7335)
-  * Remove redundant instruction comment (#7342)
-  * docs: minimize rendering count (#7343)
-
-### Minor Enhancements
-
-  * use jekyll-compose if installed (#6932)
-  * Memoize computing excerpt's relative_path (#6951)
-  * Liquefied link tag (#6269)
-  * Suggest re-running command with --trace on fail (#6551)
-  * Update item_property to return numbers as numbers instead of strings (#6608)
-  * Use .markdown for page templates (#7126)
-  * Fix custom 404 page for GitHub pages (#7132)
-  * Add support for `*.xhtml` files (#6854)
-  * Cache matched defaults sets for given parameters (#6888)
-  * Ignore permission error of /proc/version (#7267)
-  * Strip extra slashes via `Jekyll.sanitized_path` (#7182)
-  * Site template: remove default config for markdown (#7285)
-  * Cache: Do not dump undumpable objects (#7190)
-  * Optimize rendering Liquid templates (#7136)
-  * Automatically load _config.toml (#7299)
-  * feat: enhance --blank scaffolding (#7310)
-  * Skip processing posts that can not be read (#7302)
-  * Memoize Site#post_attr_hash (#7276)
-  * Load config file from within current theme-gem (#7304)
-  * Memoize the return value of Site#documents (#7273)
-
-### Major Enhancements
-
-  * Remove unused error class (#6511)
-  * Drop support for Ruby 2.1 and 2.2 (#6560)
-  * Add vendor folder to a newly installed site's .gitignore (#6968)
-  * bump i18n (#6931)
-  * We are not using Ruby 2.2 anymore (#6977)
-  * Drop support for older versions of Rouge (#6978)
-  * Remove support for Redcarpet (#6987)
-  * Remove support for rdiscount (#6988)
-  * Remove 'cache_dir' during `jekyll clean` (#7158)
-  * Output Jekyll Version while debugging (#7173)
-  * Drop support for pygments as syntax-highlighter (#7118)
-  * Add Cache class (#7169)
-  * Cache converted markdown (#7159)
-  * Ignore cache directory (#7184)
-  * Incorporate `relative_url` filter in `link` tag (#6727)
-
-### Development Fixes
-
-  * Remove unnecessary Jekyll::Page constant (#6770)
-  * Loggers should accept both numbers and symbols (#6967)
-  * Update instructions for releasing docs Gem (#6975)
-  * yajl-ruby update to v1.4.0 (#6976)
-  * Load Rouge for TestKramdown (#7007)
-  * Useless privates removed (#6768)
-  * Allow i18n v0.9.5 and higher (#7044)
-  * Update Rubocop's config (#7050)
-  * Remember to release docs gem (#7066)
-  * Use assert_include (#7093)
-  * Update rubocop version to 0.57.x ### -docs (#7078)
-  * Example of CircleCI deployment through CircleCI v2 (#7024)
-  * Fix Rubocop offences in test files (#7128)
-  * fix up refute_equal call (#7133)
-  * Fix incorrectly passed arguments to assert_equal (#7134)
-  * Lock Travis to Bundler-1.16.2 (#7144)
-  * Replace regex arg to :gsub with a string arg (#7189)
-  * Interpolate Jekyll::Page subclass on inspection (#7203)
-  * Small benchmark refactoring (#7211)
-  * Add cucumber feature to test include_relative tag (#7213)
-  * Bump Rubocop to v0.59.0 (#7237)
-  * update yajl-ruby (#7278)
-  * Drop support for `jekyll-watch-1.4.0` and older (#7287)
-  * CI(Appveyor): shallow clone with 5 last commits (#7312)
-  * Bump RuboCop to v0.60.x (#7338)
+## 4.0.1 / 2020-05-08
+
+### Bug Fixes
+
+  * Prevent console warning with Ruby 2.7 (#8124)
+  * Clear cached Liquid template scope before render (#8141)
+  * Add static file's basename to its url_placeholder (#8142)
+  * Update item_property to recognize integers (#8160)
+
+### Development Fixes
+
+  * Fix Kramdown converter based tests for v4.0.x (#8143)
+
+## 4.0.0 / 2019-08-19
+
+### Major Enhancements
+
+  * Drop ruby 2.3 (#7454)
+  * Drop support for Ruby 2.1 and 2.2 (#6560)
+  * Drop support for older versions of Rouge (#6978)
+  * Drop support for pygments as syntax-highlighter (#7118)
+  * Drop support for Redcarpet (#6987)
+  * Drop support for rdiscount (#6988)
+  * Drop support for `jekyll-watch-1.4.0` and older (#7287)
+  * Incorporate `relative_url` filter in `link` tag (#6727)
+  * Upgrade kramdown dependency to v2.x (#7492)
+  * Upgrade jekyll-sass-converter to v2.x - Sassc + sourcemaps (#7778)
+  * Upgrade i18n to v1.x (#6931)
+  * Add `Jekyll::Cache` class to handle caching on disk (#7169)
+  * Cache converted markdown (#7159)
+  * Cache: Do not dump undumpable objects (#7190)
+  * Cache matched defaults sets for given parameters (#6888)
+  * Ignore cache directory (#7184)
+  * Add `Site#in_cache_dir` helper method (#7160)
+  * Remove 'cache_dir' during `jekyll clean` (#7158)
+  * Cache parsed Liquid templates in memory (#7136)
+  * Only read layouts from source_dir or theme_dir (#6788)
+  * Allow custom sorting of collection documents (#7427)
+  * Always exclude certain paths from being processed (#7188)
+  * Remove Jekyll::Utils#strip_heredoc in favor of a Ruby > 2.3 built in (#7584)
+  * Incorporate `relative_url` within `post_url` tag (#7589)
+  * Remove patch to modify config for kramdown (#7699)
+
+### Minor Enhancements
+
+  * Enhance `--blank` scaffolding (#7310)
+  * Use `jekyll-compose` if installed (#6932)
+  * Disable Liquid via front matter (#6824)
+  * Configure cache_dir (#7232)
+  * ISO week date drops (#5981)
+  * Fix custom 404 page for GitHub pages (#7132)
+  * Load config file from within current theme-gem (#7304)
+  * Suggest re-running command with `--trace` on fail (#6551)
+  * Support for binary operators in where_exp filter (#6998)
+  * Automatically load `_config.toml` (#7299)
+  * Add vendor folder to a newly installed site's .gitignore (#6968)
+  * Output Jekyll Version while debugging (#7173)
+  * Memoize computing excerpt's relative_path (#6951)
+  * Skip processing posts that can not be read (#7302)
+  * Memoize the return value of Site#documents (#7273)
+  * Cache globbed paths in front matter defaults (#7345)
+  * Cache computed item property (#7301)
+  * Cleanup Markdown converter (#7519)
+  * Do not process Liquid in post excerpt when disabled in front matter (#7146)
+  * Liquefied link tag (#6269)
+  * Update item_property to return numbers as numbers instead of strings (#6608)
+  * Use `.markdown` extension for page templates (#7126)
+  * Add support for `*.xhtml` files (#6854)
+  * Allow i18n v0.9.5 and higher (#7044)
+  * Ignore permission error of /proc/version (#7267)
+  * Strip extra slashes via `Jekyll.sanitized_path` (#7182)
+  * Site template: remove default config for markdown (#7285)
+  * Add a custom inspect string for StaticFile objects (#7422)
+  * Remind user to include gem in the Gemfile on error (#7476)
+  * Search Front matter defaults for Page objects with relative_path (#7261)
+  * Lock use of `tzinfo` gem to v1.x (#7521, #7562)
+  * Utilize absolute paths of user-provided file paths (#7450)
+  * Detect `nil` and empty values in objects with `where` filter (#7580)
+  * Initialize mutations for Drops only if necessary (#7657)
+  * Reduce Array allocations via Jekyll::Cleaner (#7659)
+  * Encode and unencode urls only as required (#7654)
+  * Reduce string allocations with better alternatives (#7643)
+  * Reduce allocations from Jekyll::Document instances (#7625)
+  * Add `type` attribute to Document instances (#7406)
+  * Reduce allocations from where-filter (#7653)
+  * Memoize SiteDrop#documents to reduce allocations (#7697)
+  * Add PathManager class to cache interim paths (#7732)
+  * Remove warnings and fixes for deprecated config (#7440)
+  * Delegate --profile tabulation to `terminal-table` (#7627)
 
 ### Bug Fixes
 
-  * Add call to unused method `validate_options` in `commands/serve.rb` (#7122)
   * Security: fix `include` bypass of `EntryFilter#filter` symlink check (#7226)
+  * Theme gems: ensure directories aren't symlinks (#7419)
+  * Add call to unused method `validate_options` in `commands/serve.rb` (#7122)
   * Check if scope applies to type before given path (#7263)
   * Document two methods, simplify one of the methods (#7270)
   * Check key in collections only if it isn't "posts" (#7277)
-  * Revert "Cache converter in renderer" (#7326)
+  * Interpolate Jekyll::Page subclass on inspection (#7203)
   * Measure the no. of times a template gets rendered (#7316)
+  * Reduce array traversal in Jekyll::Reader (#7157)
   * Re-implement handling Liquid blocks in excerpts (#7250)
+  * Documents should be able to render their date (#7404)
+  * Fix Interpreter warning from Jekyll::Renderer (#7448)
+  * Loggers should accept both numbers and symbols (#6967)
+  * Replace regex arg to :gsub with a string arg (#7189)
+  * Dont write static files from unrendered collection (#7410)
+  * Excerpt handling of custom and intermediate tags (#7382)
+  * Change future post loglevel to warn to help user narrow down issues (#7527)
+  * Handle files with trailing dots in their basename (#7315)
+  * Fix unnecessary allocations via StaticFileReader (#7572)
+  * Don't check if site URL is absolute if it is nil (#7498)
+  * Avoid unnecessary duplication of pages array (#7272)
+  * Memoize Site#post_attr_hash (#7276)
+  * Memoize Document#excerpt_separator (#7569)
+  * Optimize Document::DATE_FILENAME_MATCHER to match valid filenames (#7292)
+  * Escape valid special chars in a site's path name (#7568)
+  * Replace `name` in Page#inspect with relative_path (#7434)
+  * Log a warning when the slug is empty (#7357)
+  * Push Markdown link refs to excerpt only as required (#7577)
+  * Fix broken include_relative usage in excerpt (#7633)
+  * Initialize and reset glob_cache only as necessary (#7658)
+  * Revert memoizing Site#docs_to_write and #documents (#7684)
+  * Backport #7684 for v3.8.x: Revert memoizing Site#docs_to_write and refactor #documents (#7689)
+  * Backport #7213 and #7633 for v3.8.x: Fix broken include_relative usage in excerpt (#7690)
+  * Don't read symlinks in site.include in safe mode (#7711)
+  * Replace `String#=~` with `String#match?` (#7723)
+  * Update log output for an invalid theme directory (#7679)
+  * Remove configuration of theme sass files from Core (#7290)
+  * Actually conditionally include liquid-c (#7792)
+  * Test number_like regex on stringified property (#7788)
 
-### feature
+### Development Fixes
 
-  * Disable Liquid via front matter (#6824)
-  * Do not process Liquid in post excerpt when disabled in front matter (#7146)
+  * Upgrade liquid-c to v4.0 (#7375)
+  * Bump RuboCop to v0.71.0 (#7687)
+  * Target Ruby 2.4 syntax (#7583)
+  * Fix: RuboCop offenses (#7769)
+  * Use communicative method parameters (#7566)
+  * Scan `assert_equal` methods and rectify any offenses with a custom RuboCop cop (#7130)
+  * CI: Test with Ruby 2.6 (#7438)
+  * CI: Test with Ruby 2.6 on AppVeyor (#7518)
+  * CI: Update RuboCop config (#7050)
+  * CI: Add a script to profile docs (#7540)
+  * CI(Appveyor): shallow clone with 5 last commits (#7312)
+  * CI: Test with oldest and latest Ruby only (#7412)
+  * CI: Update excludes for CodeClimate Analyses (#7365)
+  * CI: Lock Travis to Bundler-1.16.2 (#7144)
+  * CI: Bump tested version of JRuby to 9.2.7.0 (#7612)
+  * CI: Do not install docs on updating gems on Travis (#7706)
+  * Update gemspec (#7425)
+  * deps: relax version constraint on classifier-reborn gem (#7471)
+  * deps: update yajl-ruby (#7278)
+  * deps: bump yajl-ruby to v1.4.0 (#6976)
+  * Create symlink only if target is accessible (#7429)
+  * Switch to `:install_if` for wdm gem (#7372)
+  * Add cucumber feature to test include_relative tag (#7213)
+  * Small benchmark refactoring (#7211)
+  * Fix incorrectly passed arguments to assert_equal (#7134)
+  * fix up refute_equal call (#7133)
+  * Fix RuboCop offences in test files (#7128)
+  * Use assert_include (#7093)
+  * Remember to release docs gem (#7066)
+  * Useless privates removed (#6768)
+  * Load Rouge for TestKramdown (#7007)
+  * Update instructions for releasing docs Gem (#6975)
+  * We are not using Ruby 2.2 anymore (#6977)
+  * Remove unnecessary Jekyll::Page constant (#6770)
+  * Remove unused error class (#6511)
+  * Add a Cucumber feature for post_url tag (#7586)
+  * Generate a "TOTAL" row for build-profile table (#7614)
+  * Refactor Jekyll::Cache (#7532)
+  * Store list of expected extnames in a constant (#7638)
+  * Profile allocations from a build session (#7646)
+  * Update small typo in contributing.md (#7671)
+  * Remove override to Jekyll::Document#respond_to? (#7695)
+  * Update TestTags in sync with Rouge v3.4 (#7709)
+  * Use regexp to filter special entries (#7702)
+  * Reduce Array objects generated from utility method (#7749)
+  * Update mime.types (#7756)
+  * Replace redundant Array#map with Array#each (#7761)
+  * Reduce allocations by using #each_with_object (#7758)
+  * Memoize fallback_data for Drop (#7728)
+  * Use String#end_with? to check if entry is a backup (#7701)
+
+### Documentation
+
+  * Refactor docs (#7205)
+  * Add a link to Giraffe Academy's tutorial (#7325)
+  * Do not advise users to install Jekyll outside of Bundler (#6927)
+  * Remove documentation for using Redcarpet (#6990)
+  * Install Docs that Work on MacOS 10.14 (#7561)
+  * Add Installation Instructions for Ubuntu (#6925)
+  * Don't prompt for sudo when installing with Ubuntu WSL (#6781)
+  * Installation instructions for Fedora (#7198)
+  * Update Windows install docs (#6926)
+  * List all standard liquid filters (#7333)
+  * List all static files variables (#7002)
+  * Improve how to include Rouge stylesheets (#7752)
+  * Mention CommonMark plugins (#7418)
+  * Add TSV to list of supported _data files. (#7168)
+  * How to deploy using pre-push git hook (#7179)
+  * Hosting with AWS Amplify (#7510)
+  * CircleCI deployment through CircleCI v2 (#7024)
+  * GitHub Pages: use themes from other repos (#7112)
+  * Document page.dir and page.name (#7373)
+  * Document custom tag blocks (#7359)
+  * Document converter methods (#7289)
+  * Document `{{ page.collection }}` (#7430)
+  * Document Jekyll Filters with YAML data (#7335)
+  * Document where Jekyll looks for layouts in a site (#7564)
+  * plugin: liquid tag jekyll-flickr (#6946)
+  * plugin: jekyll-target-blank (#7046)
+  * plugin: json-get. (#7086)
+  * plugin: `jekyll-info` (#7091)
+  * plugin: jekyll-xml-source (#7114)
+  * plugin: jekyll-firstimage filter (#7127)
+  * plugin: CAT (#7011)
+  * Resources: Statictastic (#7593)
+  * Resources: Bonsai Search (#7543)
+  * Resources: Formspark (#7601)
+  * Resources: Jekpack(#7598)
+  * Resources: formX (#7536)
+  * Resources: 99inbound's Jekyll post (#7348)
+  * Resources: CloudSh (#7497)
+  * Community:  DEV Community's Jekyll tag (#7139)
+  * Showcase: developer.spotify.com (#7217)
+  * Showcase: Isomer (#7300)
+  * Add version number for group_by_exp doc (#6956)
+  * Updated nginx configuration for custom-404-page documentation (#6994)
+  * Clarify definition of 'draft' (#7037)
+  * _drafts need to be contained within the custom collection directory (#6985)
+  * Updated to supported version (#7031)
+  * Add Hints for some Improved Travis Config in Doc (#7049)
+  * Update travis-ci.md to point out "this is an example Gemfile" (#7089)
+  * Instructions to view theme’s files under Linux (#7095)
+  * Use a real theme in the example (#7125)
+  * Update docs about post creation (#7138)
+  * Initialize upgrading doc for v4.0 (#7140)
+  * Add version badge for date filters with ordinal (#7162)
+  * Corrected sample usage of postfiles (#7181)
+  * Resolve "Unable to locate package ruby2.4" error (#7196)
+  * Correct stylesheet url in tutorial step 7 (#7210)
+  * Removes quotes from markdown for assets (#7223)
+  * Clarified front matter requirement (#7234)
+  * Explicit location of where to create blog.html (#7241)
+  * Reference the build command options that allows multiple config files (#7266)
+  * Add more issue template(s) and pull request template (#7269)
+  * Suggest sites use OpenSSL instead of GnuTLS for their site's CI (#7010)
+  * Fix broken Contributors link in README.markdown (#7200)
+  * Add title tag to item in RSS template (#7282)
+  * Add link tag to item in RSS template (#7291)
+  * Remove redundant instruction comment (#7342)
+  * Textile is only supported through a converter plugin (#7003)
+  * Add recursive navigation tutorial (#7720)
+  * Remove installation instructions with Homebrew (#7381)
+  * Fix dead link and misleading prose (#7383)
+  * Fix content management section (#7385)
+  * Apply ruby official guide documents (#7393)
+  * Fix group_by_exp filter example (#7394)
+  * Remove alt attribute from a tags (#7407)
+  * Fix BASH code-block in ubuntu.md (#7420)
+  * zlib is missing (#7428)
+  * Fixed unnecessary aticles and pronouns (#7466)
+  * Store SSL key and cert in site source (#7473)
+  * Fix typo in tutorial for converting existing site (#7524)
+  * Check if var exists before include tag (#7530)
+  * Clarify docs on collections regarding the need for front matter (#7538)
+  * Fix incorrect Windows path in themes.md (#7525)
+  * Addresses bundle not found. (#7351)
+  * Update the contribution docs for draft pull requests (#7619)
+  * Data file section adds TSV (#7640)
+  * Indicate where the _sass folder is by default (#7644)
+  * Docs: add version tags to new placeholders (#5981) for permalinks (#7647)
+  * Solve "GitHub Page build failure" in 10-deployment.md (#7648)
+  * fix link to Site Source config (#7708)
+  * Introduce frontmatter in step 2 (#7704)
+  * Add @ashmaroli to Core Team listing (#7398)
+  * Lnk to Tidelift in site's footer (#7377)
+  * Link to OpenCollective backing (#7378
+  * Link to sponsor listing in README (#7405)
+  * Adjust team page listings (#7395)
+  * Updates to CODE OF CONDUCT (v1.4.0) (#7105)
+  * More inclusive writing (#7283)
+  * Update Ruby version used in Travis-CI example (#7783)
+  * Documentation for binary operators in where_exp (#7786)
+  * Adding SmartForms as Forms service (#7794)
 
 ### Site Enhancements
 
-  * Add Release Post for v3.6.3, v3.7.4 and v3.8.4 (#7259)
+  * Better Performance (#7388)
+  * Add some minor improvements to image loading in Showcase page (#7214)
+  * Simplify assigning classname to docs' aside-links (#7609)
+  * Simplify couple of includes in the docs site (#7607)
+  * Avoid generating empty classnames (#7610)
+  * Minimize rendering count (#7343)
+
+### Release
+
+  * Release post for v4.0.0 beta1 (#7716)
+  * Release post for v4.0.0.pre.alpha1 (#7574)
+  * Release post for v3.8.0 (#6849)
+  * Release post for v3.6.3, v3.7.4 and v3.8.4 (#7259)
+  * Post: v4.0 development (#6934)
+
+## 3.8.6 / 2019-07-02
+
+### Bug Fixes
+
+  * Update log output for an invalid theme directory (#7734)
+  * Memoize `SiteDrop#documents` to reduce allocations (#7722)
+  * Excerpt handling of custom and intermediate tags (#7467)
+  * Escape valid special chars in a site's path name (#7573)
+  * Revert memoizing `Site#docs_to_write` and refactor `#documents` (#7689)
+  * Fix broken `include_relative` usage in excerpt (#7690)
+  * Install platform-specific gems as required (3c06609406)
+
+### Security Fixes
+
+  * Theme gems: ensure directories aren't symlinks (#7424)
 
 ## 3.8.5 / 2018-11-04
 
 ### Bug Fixes
+
   * Re-implement handling Liquid blocks in excerpts (#7250)
 
 ## 3.8.4 / 2018-09-18
@@ -218,10 +374,10 @@
   * Minimize array allocations in the `where` filter (#6860)
   * Bump JRuby (#6878)
   * Assert existence of <collection>.files (#6907)
-  * Bump Rubocop to 0.54.x (#6915)
+  * Bump RuboCop to 0.54.x (#6915)
   * Regenerate unconditionally unless its an incremental build (#6917)
   * Centralize require statements (#6910)
-  * Bump to Rubocop 0.55 (#6929)
+  * Bump to RuboCop 0.55 (#6929)
   * Refactor private method `HighlightBlock#parse_options` (#6822)
 
 ### Minor Enhancements

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2008-2018 Tom Preston-Werner and Jekyll contributors
+Copyright (c) 2008-present Tom Preston-Werner and Jekyll contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.markdown

@@ -28,7 +28,7 @@ See: https://jekyllrb.com/philosophy
 
 * [Install](https://jekyllrb.com/docs/installation/) the gem
 * Read up about its [Usage](https://jekyllrb.com/docs/usage/) and [Configuration](https://jekyllrb.com/docs/configuration/)
-* Take a gander at some existing [Sites](https://wiki.github.com/jekyll/jekyll/sites)
+* Take a gander at some existing [Sites](https://github.com/jekyll/jekyll/wiki/sites)
 * [Fork](https://github.com/jekyll/jekyll/fork) and [Contribute](https://jekyllrb.com/docs/contributing/) your own modifications
 * Have questions? Check out our official forum community [Jekyll Talk](https://talk.jekyllrb.com/) or [`#jekyll` on irc.freenode.net](https://botbot.me/freenode/jekyll/)
 
@@ -59,6 +59,21 @@ these terms, please let one of our [core team members](https://jekyllrb.com/team
 
 ## Credits
 
+### Sponsors
+
+Support this project by becoming a sponsor. Your logo will show up in this README with a link to your website. [Become a sponsor!](https://opencollective.com/jekyll#sponsor)
+
+<a href="https://opencollective.com/jekyll/sponsor/0/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/0/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/1/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/1/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/2/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/2/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/3/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/3/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/4/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/4/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/5/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/5/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/6/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/6/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/7/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/7/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/8/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/8/avatar.svg" /></a>
+<a href="https://opencollective.com/jekyll/sponsor/9/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/9/avatar.svg" /></a>
+
 ### Contributors
 
 This project exists thanks to all the people who contribute.
@@ -70,14 +85,6 @@ Thank you to all our backers! 🙏 [Become a backer](https://opencollective.com/
 
 <a href="https://opencollective.com/jekyll#backers" target="_blank"><img src="https://opencollective.com/jekyll/backers.svg?width=890" /></a>
 
-### Sponsors
-
-Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor!](https://opencollective.com/jekyll#sponsor)
-
-<a href="https://opencollective.com/jekyll/sponsor/0/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/0/avatar.svg" /></a>
-<a href="https://opencollective.com/jekyll/sponsor/1/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/1/avatar.svg" /></a>
-<a href="https://opencollective.com/jekyll/sponsor/2/website" target="_blank"><img src="https://opencollective.com/jekyll/sponsor/2/avatar.svg" /></a>
-
 ## License
 
 See the [LICENSE](https://github.com/jekyll/jekyll/blob/master/LICENSE) file.

appveyor.yml

@@ -6,27 +6,28 @@ branches:
   only:
     - master
     - themes
+    - /.*-stable/
 
 build: off
 
 environment:
-  BUNDLE_WITHOUT: "benchmark:site:development"
+  BUNDLE_WITHOUT: "benchmark:development"
   matrix:
-    - RUBY_FOLDER_VER: "25"
-      TEST_SUITE: "test"
-    - RUBY_FOLDER_VER: "25"
-      TEST_SUITE: "cucumber"
-    - RUBY_FOLDER_VER: "25"
-      TEST_SUITE: "default-site"
-    - RUBY_FOLDER_VER: "25-x64"
-      TEST_SUITE: "test"
     - RUBY_FOLDER_VER: "24"
       TEST_SUITE: "test"
-    - RUBY_FOLDER_VER: "23"
+    - RUBY_FOLDER_VER: "26"
       TEST_SUITE: "test"
+    - RUBY_FOLDER_VER: "26"
+      TEST_SUITE: "default-site"
+    - RUBY_FOLDER_VER: "26"
+      TEST_SUITE: "profile-docs"
+    - RUBY_FOLDER_VER: "26"
+      TEST_SUITE: "memprof"
+    - RUBY_FOLDER_VER: "26"
+      TEST_SUITE: "cucumber"
 
 install:
-  - SET PATH=C:\Ruby%RUBY_FOLDER_VER%\bin;%PATH%
+  - SET PATH=C:\Ruby%RUBY_FOLDER_VER%-x64\bin;%PATH%
   - bundle install --retry 5 --jobs=%NUMBER_OF_PROCESSORS% --clean --path vendor\bundle
 
 test_script:

docs/_config.yml

@@ -1,5 +1,5 @@
 ---
-version: 3.8.5
+version: 4.0.1
 name: Jekyll • Simple, blog-aware, static sites
 description: Transform your plain text into static websites and blogs
 url: https://jekyllrb.com
@@ -29,8 +29,12 @@ defaults:
     path: _posts
     type: posts
   values:
-    layout: post
-    image: "/img/twitter-card.png"
+    layout: news_item
+- scope:
+    path: ''
+  values:
+    image: "/img/jekyll-og.png"
+future: true
 plugins:
 - jekyll-avatar
 - jekyll-feed
@@ -39,10 +43,15 @@ plugins:
 - jekyll-seo-tag
 - jekyll-sitemap
 - jemoji
+feed:
+  categories:
+  - release
 sass:
   style: compressed
+strict_front_matter: true
 exclude:
-- .gitignore
-- .jekyll-cache
+- ".gitignore"
+- ".jekyll-cache"
 - CNAME
+- icomoon-selection.json
 - readme.md

docs/_data/docs_nav.yml

@@ -1,16 +1,16 @@
 - title: Getting Started
-  items:
+  docs:
     - link: /docs/
     - link: /docs/ruby-101/
     - link: /docs/installation/
     - link: /docs/community/
     - link: /docs/step-by-step/01-setup/
 - title: Build
-  items:
+  docs:
     - link: /docs/usage/
     - link: /docs/configuration/
 - title: Content
-  items:
+  docs:
     - link: /docs/pages/
     - link: /docs/posts/
     - link: /docs/front-matter/
@@ -19,7 +19,7 @@
     - link: /docs/assets/
     - link: /docs/static-files/
 - title: Site Structure
-  items:
+  docs:
     - link: /docs/structure/
     - link: /docs/liquid/
     - link: /docs/variables/
@@ -29,7 +29,7 @@
     - link: /docs/themes/
     - link: /docs/pagination/
 - title: Guides
-  items:
+  docs:
     - link: /docs/plugins/
     - link: /docs/migrations/
     - link: /docs/upgrading/

docs/_data/jekyll_filters.yml

@@ -127,10 +127,10 @@
   examples:
     - input: |-
         {{ site.members | group_by_exp: "item",
-        "item.graduation_year | truncate 3, ''" }}
+        "item.graduation_year | truncate: 3, ''" }}
       output: |-
-        [{"name"=>"201...", "items"=>[...]},
-        {"name"=>"200...", "items"=>[...]}]
+        [{"name"=>"201", "items"=>[...]},
+        {"name"=>"200", "items"=>[...]}]
 
 #
 

docs/_data/jekyll_variables.yml

@@ -120,10 +120,23 @@ page:
       <code>/work/code/_posts/2008-12-24-closures.md</code> would have this field set to
       <code>['work', 'code']</code>. These can also be specified in the
       <a href="/docs/front-matter/">front matter</a>.
+  - name: page.collection
+    description: >-
+      The label of the collection to which this document belongs. e.g. <code>posts</code> for a post, or
+      <code>puppies</code> for a document at path <code>_puppies/rover.md</code>. If not part of a
+      collection, an empty string is returned.
   - name: page.tags
     description: >-
       The list of tags to which this post belongs. These can be specified in the
       <a href="/docs/front-matter/">front matter</a>.
+  - name: page.dir
+    description: >-
+      The path between the source directory and the file of the post or page,  e.g.
+      <code>/pages/</code>.
+      This can be overridden by <code>permalink</code> in the <a href="/docs/front-matter/">front matter</a>.
+  - name: page.name
+    description: >-
+      The filename of the post or page, e.g. <code>about.md</code>
   - name: page.path
     description: >-
       The path to the raw post or page. Example usage: Linking back to the page or post’s source

docs/_data/ruby.yml

@@ -0,0 +1,3 @@
+min_version: 2.4.0
+current_version: 2.6.3
+current_version_output: ruby 2.6.3p62 (2019-04-16 revision 67580)

docs/_data/sponsors.yml

@@ -1,9 +0,0 @@
-- name: Forestry.io
-  image: /img/forestry.svg
-  url: https://forestry.io/?utm_campaign=jekyllsponsor&utm_medium=banner&utm_source=jekyllrb.com
-- name: CloudCannon
-  image: /img/cloudcannon.svg
-  url: https://cloudcannon.com
-- name: Siteleaf
-  image: /img/siteleaf.svg
-  url: https://siteleaf.com

docs/_data/tutorials.yml

@@ -0,0 +1,13 @@
+- title: Tutorials
+  tutorials:
+  - home
+  - video-walkthroughs
+  - navigation
+  - orderofinterpretation
+  - custom-404-page
+  - convert-site-to-jekyll
+  - using-jekyll-with-bundler
+
+#- title: Another section
+#  tutorials:
+#  - sample

docs/_data/tutorials_nav.yml

@@ -1,9 +0,0 @@
-- title: Tutorials
-  items:
-    - link: /tutorials/
-    - link: /tutorials/video-walkthroughs/
-    - link: /tutorials/navigation/
-    - link: /tutorials/order-of-interpretation/
-    - link: /tutorials/custom-404-page/
-    - link: /tutorials/convert-site-to-jekyll/
-    - link: /tutorials/using-jekyll-with-bundler/

docs/_docs/assets.md

@@ -24,11 +24,14 @@ have a file named `css/styles.scss` in your site's source folder, Jekyll
 will process it and put it in your site's destination folder under
 `css/styles.css`.
 
-If you are using [Mustache](https://mustache.github.io)
-or another JavaScript templating language that conflicts with
-the [Liquid template syntax](/docs/templates/), you
-will need to place <code>{&#37; raw &#37;}</code> and
-<code>{&#37; endraw &#37;}</code> tags around your code.
+<div class="note info">
+  <h5>Jekyll processes all Liquid filters and tags in asset files</h5>
+  <p>If you are using <a href="https://mustache.github.io">Mustache</a>
+     or another JavaScript templating language that conflicts with
+     the <a href="/docs/templates/">Liquid template syntax</a>, you
+     will need to place <code>{&#37; raw &#37;}</code> and
+     <code>{&#37; endraw &#37;}</code> tags around your code.</p>
+</div>
 
 ## Sass/SCSS
 
@@ -52,12 +55,18 @@ The Sass converter will default the `sass_dir` configuration option to
 
 [example-sass]: https://github.com/jekyll/jekyll-sass-converter/tree/master/docs
 
-Note that the `sass_dir` becomes the load path for Sass imports,
-nothing more. This means that Jekyll does not know about these files
-directly, so any files here should not contain the front matter as
-described above nor will they be transformed as described above. This
-folder should only contain imports.
-{: .warning }
+<div class="note info">
+  <h5>The <code>sass_dir</code> is only used by Sass</h5>
+  <p>
+
+    Note that the <code>sass_dir</code> becomes the load path for Sass imports,
+    nothing more. This means that Jekyll does not know about these files
+    directly. Any files here should not contain the empty front matter as
+    described above. If they do, they'll not be transformed as described above. This
+    folder should only contain imports.
+
+  </p>
+</div>
 
 You may also specify the output style with the `style` option in your
 `_config.yml` file:

docs/_docs/code_of_conduct.md

@@ -8,11 +8,17 @@ editable: false
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment include:
+Examples of behavior that contributes to creating a positive environment
+include:
 
 * Using welcoming and inclusive language
 * Being respectful of differing viewpoints and experiences
@@ -22,31 +28,55 @@ Examples of behavior that contributes to creating a positive environment include
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
 
-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.
+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.
 
 ## Scope
 
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting a project maintainer. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [olivia@jekyllrb.com](mailto:olivia@jekyllrb.com). All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
 
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html][version]
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)
 
-[homepage]: https://www.contributor-covenant.org/
-[version]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)

docs/_docs/collections.md

@@ -24,12 +24,30 @@ collections:
     people: true
 ```
 
+<div class="note">
+  <h5>Gather your collections {%- include docs_version_badge.html version="3.7.0" -%}</h5>
+
+  <p>You can optionally specify a directory to store all your collections in the same place with <code>collections_dir: my_collections</code>.</p>
+
+  <p>Then Jekyll will look in <code>my_collections/_books</code> for the <code>books</code> collection, and
+  in <code>my_collections/_recipes</code> for the <code>recipes</code> collection.</p>
+</div>
+
+<div class="note warning">
+  <h5>Be sure to move drafts and posts into custom collections directory</h5>
+
+  <p>If you specify a directory to store all your collections in the same place with <code>collections_dir: my_collections</code>, then you will need to move your <code>_drafts</code> and <code>_posts</code> directory to <code>my_collections/_drafts</code> and <code>my_collections/_posts</code>. Note that, the name of your collections directory cannot start with an underscore (`_`).</p>
+</div>
+
 ## Add content
 
 Create a corresponding folder (e.g. `<source>/_staff_members`) and add
 documents. Front matter is processed if the front matter exists, and everything
 after the front matter is pushed into the document's `content` attribute. If no front
-matter is provided, Jekyll will not generate the file in your collection.
+matter is provided, Jekyll will consider it to be a [static file](/docs/static-files/)
+and copy it to the destination (e.g. `_site`) without processing. If front matter
+is provided, Jekyll will process the file in your collection but will not write to disk
+unless `output: true` is set in the collection's metadata.
 
 For example here's how you would add a staff member to the collection set above.
 The filename is `./_staff_members/jane.md` with the following content:
@@ -96,16 +114,54 @@ You can link to the generated page using the `url` attribute:
 There are special [permalink variables for collections](/docs/permalinks/) to
 help you control the output url for the entire collection.
 
-## Custom Collection directory
-You can optionally specify a directory to store all your collections in the same place with `collections_dir: my_collections`.
+## Custom Sorting of Documents
 
-Then Jekyll will look in `my_collections/_books` for the `books` collection, and
-in `my_collections/_recipes` for the `recipes` collection.
+By default, documents in a collection are sorted by their paths. But you can control this sorting via the collection's metadata.
 
-The name of your collections directory cannot start with an `_`.
+### Sort By Front Matter Key
 
-You will need to move your `_drafts` and `_posts` to your `collection_dir`
-{: .warning }
+Documents can be sorted based on a front matter key by setting a `sort_by` metadata to the front matter key string. For example,
+to sort a collection of tutorials based on key `lesson`, the configuration would be:
+
+```yaml
+collections:
+  tutorials:
+    sort_by: lesson
+```
+
+The documents are arranged in the increasing order of the key's value. If a document does not have the front matter key defined
+then that document is placed immediately after sorted documents. When multiple documents do not have the front matter key defined,
+those documents are sorted by their dates or paths and then placed immediately after the sorted documents.
+
+### Manually Ordering Documents
+
+You can also manually order the documents by setting an `order` metadata with **the filenames listed** in the desired order.
+For example, a collection of tutorials would be configured as:
+
+```yaml
+collections:
+  tutorials:
+    order:
+      - hello-world.md
+      - introduction.md
+      - basic-concepts.md
+      - advanced-concepts.md
+```
+
+Any documents with filenames that do not match the list entry simply gets placed after the rearranged documents. If a document is
+nested under subdirectories, include them in entries as well:
+
+```yaml
+collections:
+  tutorials:
+    order:
+      - hello-world.md
+      - introduction.md
+      - concepts/basics.md
+      - concepts/advanced.md
+```
+
+If both metadata keys have been defined properly, `order` list takes precedence.
 
 ## Liquid Attributes
 

docs/_docs/community/community.md

@@ -8,15 +8,15 @@ redirect_from: "/help/index.html"
 
 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.
 
-[Read the full code of conduct](/docs/conduct/)
+Read the full [code of conduct](/docs/conduct/)
 
 ## Where to get support
 
 If you're looking for support for Jekyll, there are a lot of options:
 
-* Read [Jekyll Documentation](https://jekyllrb.com/docs/)
-* If you have a question about using Jekyll, start a discussion on [the Jekyll Forum](https://talk.jekyllrb.com/) or [StackOverflow](https://stackoverflow.com/questions/tagged/jekyll)
-* Chat with Jekyllers — Join [our Gitter channel](https://gitter.im/jekyll/jekyll) or [our IRC channel on Freenode](irc:irc.freenode.net/jekyll)
+* Read the [Jekyll Documentation](https://jekyllrb.com/docs/)
+* If you have a question about using Jekyll, start a discussion on the [Jekyll Forum](https://talk.jekyllrb.com/) or [StackOverflow](https://stackoverflow.com/questions/tagged/jekyll)
+* Chat with Jekyllers — Join our [Gitter channel](https://gitter.im/jekyll/jekyll) or our [IRC channel on Freenode](irc:irc.freenode.net/jekyll)
 
 There are a bunch of helpful community members on these services that should be willing to point you in the right direction.
 

docs/_docs/conduct.md

@@ -6,25 +6,42 @@ 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.
+## Our Pledge
 
-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.
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery
-* Personal attacks
-* Trolling or insulting/derogatory comments
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing other's private information, such as physical or electronic
-  addresses, without explicit permission
-* Other unethical or unprofessional conduct
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
 
 Project maintainers have the right and responsibility to remove, edit, or
 reject comments, commits, code, wiki edits, issues, and other contributions
@@ -32,24 +49,34 @@ 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.
+## Scope
 
 This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community.
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
 
 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.
+reported by contacting the project team at [olivia@jekyllrb.com](mailto:olivia@jekyllrb.com). All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
 
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
 
-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]
+## Attribution
 
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/3/0/
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)

docs/_docs/configuration/default.md

@@ -16,6 +16,8 @@ plugins_dir         : _plugins
 layouts_dir         : _layouts
 data_dir            : _data
 includes_dir        : _includes
+sass:
+  sass_dir: _sass
 collections:
   posts:
     output          : true

docs/_docs/configuration/front-matter-defaults.md

@@ -22,9 +22,17 @@ defaults:
       layout: "default"
 ```
 
-
-`_config.yml` is only read when Jekyll first starts. For changes to take effect you'll need to restart Jekyll.
-{: .warning }
+<div class="note info">
+  <h5>Stop and rerun `jekyll serve` command.</h5>
+  <p>
+    The <code>_config.yml</code> master configuration file contains global configurations
+    and variable definitions that are read once at execution time. Changes made to <code>_config.yml</code>
+    during automatic regeneration are not loaded until the next execution.
+  </p>
+  <p>
+    Note <a href="/docs/datafiles">Data Files</a> are included and reloaded during automatic regeneration.
+  </p>
+</div>
 
 Here, we are scoping the `values` to any file that exists in the path `scope`. Since the path is set as an empty string, it will apply to **all files** in your project. You probably don't want to set a layout on every file in your project - like css files, for example - so you can also specify a `type` value under the `scope` key.
 
@@ -96,12 +104,16 @@ defaults:
       layout: "specific-layout"
 ```
 
+<div class="note warning">
+  <h5>Globbing and Performance</h5>
+  <p>
+    Please note that globbing a path is known to have a negative effect on
+    performance and is currently not optimized, especially on Windows.
+    Globbing a path will increase your build times in proportion to the size
+    of the associated collection directory.
+  </p>
+</div>
 
-Please note that globbing a path is known to have a negative effect on
-performance and is currently not optimized, especially on Windows.
-Globbing a path will increase your build times in proportion to the size
-of the associated collection directory.
-{: .warning }
 
 ### Precedence
 

docs/_docs/configuration/incremental-regeneration.md

@@ -4,13 +4,15 @@ permalink: "/docs/configuration/incremental-regeneration/"
 ---
 
 ## Incremental Regeneration
-
-
-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
-[opening an issue on GitHub](https://github.com/jekyll/jekyll/issues/new).
-{: .warning }
+<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

docs/_docs/configuration/markdown.md

@@ -42,11 +42,22 @@ currently supported options:
 * **transliterated_header_ids** - Transliterate the header text before generating the ID
 * **typographic_symbols** - Defines a mapping from typographical symbol to output characters
 
-Please note that both `remove_block_html_tags` and
-`remove_span_html_tags` are currently unsupported in Jekyll due
-to the fact that they are not included within the kramdown HTML converter.
-{: .warning }
-For more details about these options have a look at the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html).
+<div class="note warning">
+  <h5>There are two unsupported kramdown options</h5>
+  <p>
+    Please note that both <code>remove_block_html_tags</code> and
+    <code>remove_span_html_tags</code> are currently unsupported in Jekyll due
+    to the fact that they are not included within the kramdown HTML converter.
+  </p>
+</div>
+
+For more details about these options have a look at the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html). 
+
+### CommonMark
+
+[CommonMark](https://commonmark.org/) is a rationalized version of Markdown syntax, implemented in C and thus faster than default Kramdown implemented in Ruby. It [slightly differs](https://github.com/commonmark/CommonMark#differences-from-original-markdown) from original Markdown and does not support all the syntax elements implemented in Kramdown, like [Block Inline Attribute Lists](https://kramdown.gettalong.org/syntax.html#block-ials).
+
+It comes in two flavors: basic CommonMark with [jekyll-commonmark](https://github.com/jekyll/jekyll-commonmark) plugin and [GitHub Flavored Markdown supported by GitHub Pages](https://github.com/github/jekyll-commonmark-ghpages).
 
 ### Redcarpet
 

docs/_docs/configuration/options.md

@@ -7,8 +7,6 @@ The tables below list the available settings for Jekyll, and the various <code
 class="option">options</code> (specified in the configuration file) and <code
 class="flag">flags</code> (specified on the command-line) that control them.
 
-Remember, configuration files are YAML so use spaces for indention not tabs.
-
 ### Global Configuration
 
 <div class="mobile-side-scroller">
@@ -35,8 +33,7 @@ Remember, configuration files are YAML so use spaces for indention not tabs.
     <tr class="setting">
       <td>
         <p class="name"><strong>Site Destination</strong></p>
-        <p class="description">Change the directory where Jekyll will write files. Files or folders in this directory that are not created by your site will be removed. Some files could be retained
-        by specifying them within the <code>&lt;keep_files&gt;</code> configuration directive.</p>
+        <p class="description">Change the directory where Jekyll will write files</p>
       </td>
       <td class="align-center">
         <p><code class="option">destination: DIR</code></p>
@@ -119,6 +116,8 @@ Remember, configuration files are YAML so use spaces for indention not tabs.
             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
             default of <code>ASCII-8BIT</code>.
+            Available encodings can be shown by the
+            command <code>ruby -e 'puts Encoding::list.join("\n")'</code>.
         </p>
       </td>
       <td class="align-center">
@@ -141,6 +140,20 @@ Remember, configuration files are YAML so use spaces for indention not tabs.
 </table>
 </div>
 
+<div class="note warning">
+  <h5>Destination folders are cleaned on site builds</h5>
+  <p>
+    The contents of <code>&lt;destination&gt;</code> are automatically
+    cleaned, by default, when the site is built. Files or folders that are not
+    created by your site will be removed. Some files could be retained
+    by specifying them within the <code>&lt;keep_files&gt;</code> configuration directive.
+  </p>
+  <p>
+    Do not use an important location for <code>&lt;destination&gt;</code>; instead, use it as
+    a staging area and copy files from there to your web server.
+  </p>
+</div>
+
 ### Build Command Options
 
 <div class="mobile-side-scroller">
@@ -339,17 +352,27 @@ before your site is served.
     <tr class="setting">
       <td>
         <p class="name"><strong>Base URL</strong></p>
-        <p class="description">Serve the website from the given base URL</p>
+        <p class="description">Serve the website from the given base URL.</p>
       </td>
       <td class="align-center">
         <p><code class="option">baseurl: URL</code></p>
         <p><code class="flag">--baseurl URL</code></p>
       </td>
     </tr>
+    <tr class="setting">
+      <td>
+        <p class="name"><strong>Live Reload</strong></p>
+        <p class="description">Reload a page automatically on the browser when its content is edited.</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">livereload: true</code></p>
+        <p><code class="flag">--livereload</code></p>
+      </td>
+    </tr>
     <tr class="setting">
       <td>
         <p class="name"><strong>Detach</strong></p>
-        <p class="description">Detach the server from the terminal</p>
+        <p class="description">Detach the server from the terminal.</p>
       </td>
       <td class="align-center">
         <p><code class="option">detach: BOOL</code></p>
@@ -358,7 +381,7 @@ before your site is served.
     </tr>
     <tr class="setting">
       <td>
-        <p class="name"><strong>Skips the initial site build.</strong></p>
+        <p class="name"><strong>Skips the initial site build</strong></p>
         <p class="description">Skips the initial site build which occurs before the server is started.</p>
       </td>
       <td class="align-center">
@@ -368,7 +391,7 @@ before your site is served.
     <tr class="setting">
       <td>
         <p class="name"><strong>X.509 (SSL) Private Key</strong></p>
-        <p class="description">SSL Private Key.</p>
+        <p class="description">SSL Private Key, stored or symlinked in the site source.</p>
       </td>
       <td class="align-center">
         <p><code class="flag">--ssl-key</code></p>
@@ -377,7 +400,7 @@ before your site is served.
     <tr class="setting">
       <td>
         <p class="name"><strong>X.509 (SSL) Certificate</strong></p>
-        <p class="description">SSL Public certificate.</p>
+        <p class="description">SSL Public certificate, stored or symlinked in the site source.</p>
       </td>
       <td class="align-center">
         <p><code class="flag">--ssl-cert</code></p>
@@ -386,3 +409,11 @@ before your site is served.
   </tbody>
 </table>
 </div>
+
+<div class="note warning">
+  <h5>Do not use tabs in configuration files</h5>
+  <p>
+    This will either lead to parsing errors, or Jekyll will revert to the
+    default settings. Use spaces instead.
+  </p>
+</div>

docs/_docs/continuous-integration/circleci.md

@@ -34,7 +34,7 @@ gem 'jekyll'
 gem 'html-proofer'
 ```
 
-CircleCI detects when `Gemfile` is present is will automatically run `bundle install` for you in the `dependencies` phase.
+CircleCI detects when `Gemfile` is present and will automatically run `bundle install` for you in the `dependencies` phase.
 
 ## 3. Testing
 
@@ -105,6 +105,13 @@ jobs:
       - run:
           name: Bundle Install
           command: bundle check || bundle install
+      - save_cache:
+          key: rubygems-v1-{% raw %}{{ checksum "Gemfile.lock" }}{% endraw %}
+          paths:
+            - vendor/bundle
+      - run:
+          name: Jekyll build
+          command: bundle exec jekyll build
       - run:
           name: HTMLProofer tests
           command: |
@@ -113,13 +120,6 @@ jobs:
               --check-favicon  \
               --check-html \
               --disable-external
-      - save_cache:
-          key: rubygems-v1-{% raw %}{{ checksum "Gemfile.lock" }}{% endraw %}
-          paths:
-            - vendor/bundle
-      - run:
-          name: Jekyll build
-          command: bundle exec jekyll build
       - persist_to_workspace:
           root: ./
           paths:

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

@@ -90,7 +90,7 @@ Your `.travis.yml` file should look like this:
 ```yaml
 language: ruby
 rvm:
-  - 2.4.1
+  - 2.6.3
 
 before_script:
  - chmod +x ./script/cibuild # or do this locally and commit
@@ -134,7 +134,7 @@ access to Bundler, RubyGems, and a Ruby runtime.
 
 ```yaml
 rvm:
-  - 2.4.1
+  - 2.6.3
 ```
 
 RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This

docs/_docs/contributing.md

@@ -8,7 +8,7 @@ Hi there! Interested in contributing to Jekyll? We'd love your help. Jekyll is a
 
 ## Where to get help or report a problem
 
-See [the support guidelines](https://jekyllrb.com/docs/support/)
+See the [support guidelines](https://jekyllrb.com/docs/support/)
 
 ## Ways to contribute
 
@@ -16,9 +16,9 @@ Whether you're a developer, a designer, or just a Jekyll devotee, there are lots
 
 * [Install Jekyll on your computer](https://jekyllrb.com/docs/installation/) and kick the tires. Does it work? Does it do what you'd expect? If not, [open an issue](https://github.com/jekyll/jekyll/issues/new) and let us know.
 * Comment on some of the project's [open issues](https://github.com/jekyll/jekyll/issues). Have you experienced the same problem? Know a work around? Do you have a suggestion for how the feature could be better?
-* Read through [the documentation](https://jekyllrb.com/docs/home/), and click the "improve this page" button, any time you see something confusing, or have a suggestion for something that could be improved.
-* Browse through [the Jekyll discussion forum](https://talk.jekyllrb.com/), and lend a hand answering questions. There's a good chance you've already experienced what another user is experiencing.
-* Find [an open issue](https://github.com/jekyll/jekyll/issues) (especially [those labeled `help-wanted`](https://github.com/jekyll/jekyll/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)), and submit a proposed fix. If it's your first pull request, we promise we won't bite, and are glad to answer any questions.
+* Read through the [documentation](https://jekyllrb.com/docs/home/), and click the "improve this page" button, any time you see something confusing, or have a suggestion for something that could be improved.
+* Browse through the [Jekyll discussion forum](https://talk.jekyllrb.com/), and lend a hand answering questions. There's a good chance you've already experienced what another user is experiencing.
+* Find an [open issue](https://github.com/jekyll/jekyll/issues) (especially [those labeled `help-wanted`](https://github.com/jekyll/jekyll/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)), and submit a proposed fix. If it's your first pull request, we promise we won't bite, and are glad to answer any questions.
 * Help evaluate [open pull requests](https://github.com/jekyll/jekyll/pulls), by testing the changes locally and reviewing what's proposed.
 
 ## Submitting a pull request
@@ -53,7 +53,7 @@ That's it! You'll be automatically subscribed to receive updates as others revie
 2. Clone the repository locally `git clone https://github.com/<you-username>/jekyll`.
 3. Create a new, descriptively named branch to contain your change ( `git checkout -b my-awesome-feature` ).
 4. Hack away, add tests. Not necessarily in that order.
-5. Make sure everything still passes by running `script/cibuild` (see [the tests section](#running-tests-locally) below)
+5. Make sure everything still passes by running `script/cibuild` (see the [tests section](#running-tests-locally) below)
 6. Push the branch up ( `git push origin my-awesome-feature` ).
 7. Create a pull request by visiting `https://github.com/<your-username>/jekyll` and following the instructions at the top of the screen.
 
@@ -93,7 +93,7 @@ If you want to add your plugin to the [list of plugins](https://jekyllrb.com/doc
 
 ## Code Contributions
 
-Interesting in submitting a pull request? Awesome. Read on. There's a few common gotchas that we'd love to help you avoid.
+Interested in submitting a pull request? Awesome. Read on. There's a few common gotchas that we'd love to help you avoid.
 
 ### Tests and documentation
 
@@ -119,6 +119,8 @@ If your contribution changes any Jekyll behavior, make sure to update the docume
 Jekyll's methods. It also provides you with helpful methods to quickly create a
 site or configuration. [Feel free to check it out!](https://github.com/jekyll/jekyll/blob/master/script/console)
 
+* Previously, we've used the WIP Probot app to help contributors determine whether their pull request is ready for review. Please use a [draft pull request](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests) instead. When you're ready, [mark the pull request as ready for review](https://help.github.com/en/articles/changing-the-stage-of-a-pull-request)
+
 ## Running tests locally
 
 ### Test Dependencies

docs/_docs/datafiles.md

@@ -7,9 +7,8 @@ In addition to the [built-in variables](../variables/) available from Jekyll,
 you can specify your own custom data that can be accessed via the [Liquid
 templating system](https://wiki.github.com/shopify/liquid/liquid-for-designers).
 
-Jekyll supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/),
-and [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) files located in the `_data` directory.
-Note that CSV files *must* contain a header row.
+Jekyll supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/), [CSV](https://en.wikipedia.org/wiki/Comma-separated_values), and [TSV](https://en.wikipedia.org/wiki/Tab-separated_values) files located in the `_data` directory.
+Note that CSV and TSV files *must* contain a header row.
 
 This powerful feature allows you to avoid repetition in your templates and to
 set site specific options without changing `_config.yml`.

docs/_docs/deployment/automated.md

@@ -36,6 +36,12 @@ Next, add the following lines to hooks/post-receive and be sure Jekyll is
 installed on the server:
 
 ```bash
+#!/bin/bash -l
+
+# Install Ruby Gems to ~/gems
+export GEM_HOME=$HOME/gems
+export PATH=$GEM_HOME/bin:$PATH
+
 GIT_REPO=$HOME/myrepo.git
 TMP_GIT_CLONE=$HOME/tmp/myrepo
 GEMFILE=$TMP_GIT_CLONE/Gemfile

docs/_docs/deployment/third-party.md

@@ -9,6 +9,12 @@ permalink: /docs/deployment/third-party/
 
 Automating the deployment of a Jekyll site is simple. See their [Jekyll docs](https://www.aerobatic.com/docs/static-site-generators/#jekyll) for more details. Your built `_site` folder is deployed to their highly-available, globally distributed hosting service.
 
+## AWS Amplify
+
+The [AWS Amplify Console](https://console.amplify.aws) provides continuous deployment and hosting for modern web apps (single page apps and static site generators). Continuous deployment allows developers to deploy updates to their web app on every code commit to their Git repository. Hosting includes features such as globally available CDNs, 1-click custom domain setup + HTTPS, feature branch deployments, redirects, trailing slashes, and password protection.
+
+Read this [step-by-step guide](https://medium.com/@FizzyInTheHall/build-and-publish-a-jekyll-powered-blog-easily-with-aws-amplify-529852042ab6) to deploy and host your Jekyll site on AWS Amplify.
+
 ## CloudCannon
 
 [CloudCannon](https://cloudcannon.com) has everything you need to build, host

docs/_docs/front-matter.md

@@ -4,7 +4,7 @@ permalink: /docs/front-matter/
 redirect_from: /docs/frontmatter/index.html
 ---
 
-Any file that contains a [YAML](http://yaml.org/) front matter block will be
+Any file that contains a [YAML](https://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:
@@ -22,16 +22,25 @@ 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.
 
-If you want to use [Liquid tags and variables](/docs/variables/)
-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)
-
-If you use UTF-8 encoding, make sure that no `BOM` 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="">[Jekyll on Windows](/docs/installation/windows/).
+<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="/docs/installation/windows/">Jekyll on Windows</a>.
+  </p>
+</div>
 
+<div class="note">
+  <h5>Front Matter Variables Are Optional</h5>
+  <p>
+    If you want to use <a href="/docs/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
 
@@ -96,8 +105,7 @@ front matter of a page or post.
       <td>
         <p>
           Set to false if you don’t want a specific post to show up when the
-          site is generated. To preview unpublished pages, run `jekyll serve`
-          or `jekyll build` with the `--unpublished` switch. 
+          site is generated.
         </p>
       </td>
     </tr>
@@ -105,6 +113,15 @@ front matter of a page or post.
 </table>
 </div>
 
+<div class="note">
+  <h5>Render Posts Marked As Unpublished</h5>
+  <p>
+    To preview unpublished pages, run `jekyll serve` or `jekyll build`
+    with the `--unpublished` switch. Jekyll also has a handy <a href="/docs/posts/#drafts">drafts</a>
+    feature tailored specifically for blog posts.
+  </p>
+</div>
+
 ## Custom Variables
 
 You can also set your own front matter variables you can access in Liquid. For
@@ -183,6 +200,12 @@ These are available out-of-the-box to be used in the front matter for a post.
 </table>
 </div>
 
-## Defaults
-
-[Front matter defaults](/docs/configuration/front-matter-defaults/) help you to reduce repetition for things like `layouts` which is often the same across multiple pages.
+<div class="note">
+  <h5>Don't repeat yourself</h5>
+  <p>
+    If you don't want to repeat your frequently used front matter variables
+    over and over, define <a href="/docs/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>

docs/_docs/github-pages.md

@@ -122,7 +122,7 @@ to see more detailed examples.
   <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="/docs/configuration/>“Site Source”</a>
+    the <a href="/docs/configuration/options/">“Site Source”</a>
     configuration value, so if you locate your files anywhere other than the
     root directory, your site may not build correctly.
   </p>

docs/_docs/history.md

@@ -4,6 +4,342 @@ permalink: "/docs/history/"
 note: This file is autogenerated. Edit /History.markdown instead.
 ---
 
+## 4.0.1 / 2020-05-08
+{: #v4-0-1}
+
+### Bug Fixes
+{: #bug-fixes-v4-0-1}
+
+- Prevent console warning with Ruby 2.7 ([#8124]({{ site.repository }}/issues/8124))
+- Clear cached Liquid template scope before render ([#8141]({{ site.repository }}/issues/8141))
+- Add static file's basename to its url_placeholder ([#8142]({{ site.repository }}/issues/8142))
+- Update item_property to recognize integers ([#8160]({{ site.repository }}/issues/8160))
+
+### Development Fixes
+{: #development-fixes-v4-0-1}
+
+- Fix Kramdown converter based tests for v4.0.x ([#8143]({{ site.repository }}/issues/8143))
+
+
+## 4.0.0 / 2019-08-19
+{: #v4-0-0}
+
+### Major Enhancements
+{: #major-enhancements-v4-0-0}
+
+- Drop ruby 2.3 ([#7454]({{ site.repository }}/issues/7454))
+- Drop support for Ruby 2.1 and 2.2 ([#6560]({{ site.repository }}/issues/6560))
+- Drop support for older versions of Rouge ([#6978]({{ site.repository }}/issues/6978))
+- Drop support for pygments as syntax-highlighter ([#7118]({{ site.repository }}/issues/7118))
+- Drop support for Redcarpet ([#6987]({{ site.repository }}/issues/6987))
+- Drop support for rdiscount ([#6988]({{ site.repository }}/issues/6988))
+- Drop support for `jekyll-watch-1.4.0` and older ([#7287]({{ site.repository }}/issues/7287))
+- Incorporate `relative_url` filter in `link` tag ([#6727]({{ site.repository }}/issues/6727))
+- Upgrade kramdown dependency to v2.x ([#7492]({{ site.repository }}/issues/7492))
+- Upgrade jekyll-sass-converter to v2.x - Sassc + sourcemaps ([#7778]({{ site.repository }}/issues/7778))
+- Upgrade i18n to v1.x ([#6931]({{ site.repository }}/issues/6931))
+- Add `Jekyll::Cache` class to handle caching on disk ([#7169]({{ site.repository }}/issues/7169))
+- Cache converted markdown ([#7159]({{ site.repository }}/issues/7159))
+- Cache: Do not dump undumpable objects ([#7190]({{ site.repository }}/issues/7190))
+- Cache matched defaults sets for given parameters ([#6888]({{ site.repository }}/issues/6888))
+- Ignore cache directory ([#7184]({{ site.repository }}/issues/7184))
+- Add `Site#in_cache_dir` helper method ([#7160]({{ site.repository }}/issues/7160))
+- Remove 'cache_dir' during `jekyll clean` ([#7158]({{ site.repository }}/issues/7158))
+- Cache parsed Liquid templates in memory ([#7136]({{ site.repository }}/issues/7136))
+- Only read layouts from source_dir or theme_dir ([#6788]({{ site.repository }}/issues/6788))
+- Allow custom sorting of collection documents ([#7427]({{ site.repository }}/issues/7427))
+- Always exclude certain paths from being processed ([#7188]({{ site.repository }}/issues/7188))
+- Remove Jekyll::Utils#strip_heredoc in favor of a Ruby > 2.3 built in ([#7584]({{ site.repository }}/issues/7584))
+- Incorporate `relative_url` within `post_url` tag ([#7589]({{ site.repository }}/issues/7589))
+- Remove patch to modify config for kramdown ([#7699]({{ site.repository }}/issues/7699))
+
+### Minor Enhancements
+{: #minor-enhancements-v4-0-0}
+
+- Enhance `--blank` scaffolding ([#7310]({{ site.repository }}/issues/7310))
+- Use `jekyll-compose` if installed ([#6932]({{ site.repository }}/issues/6932))
+- Disable Liquid via front matter ([#6824]({{ site.repository }}/issues/6824))
+- Configure cache_dir ([#7232]({{ site.repository }}/issues/7232))
+- ISO week date drops ([#5981]({{ site.repository }}/issues/5981))
+- Fix custom 404 page for GitHub pages ([#7132]({{ site.repository }}/issues/7132))
+- Load config file from within current theme-gem ([#7304]({{ site.repository }}/issues/7304))
+- Suggest re-running command with `--trace` on fail ([#6551]({{ site.repository }}/issues/6551))
+- Support for binary operators in where_exp filter ([#6998]({{ site.repository }}/issues/6998))
+- Automatically load `_config.toml` ([#7299]({{ site.repository }}/issues/7299))
+- Add vendor folder to a newly installed site's .gitignore ([#6968]({{ site.repository }}/issues/6968))
+- Output Jekyll Version while debugging ([#7173]({{ site.repository }}/issues/7173))
+- Memoize computing excerpt's relative_path ([#6951]({{ site.repository }}/issues/6951))
+- Skip processing posts that can not be read ([#7302]({{ site.repository }}/issues/7302))
+- Memoize the return value of Site#documents ([#7273]({{ site.repository }}/issues/7273))
+- Cache globbed paths in front matter defaults ([#7345]({{ site.repository }}/issues/7345))
+- Cache computed item property ([#7301]({{ site.repository }}/issues/7301))
+- Cleanup Markdown converter ([#7519]({{ site.repository }}/issues/7519))
+- Do not process Liquid in post excerpt when disabled in front matter ([#7146]({{ site.repository }}/issues/7146))
+- Liquefied link tag ([#6269]({{ site.repository }}/issues/6269))
+- Update item_property to return numbers as numbers instead of strings ([#6608]({{ site.repository }}/issues/6608))
+- Use `.markdown` extension for page templates ([#7126]({{ site.repository }}/issues/7126))
+- Add support for `*.xhtml` files ([#6854]({{ site.repository }}/issues/6854))
+- Allow i18n v0.9.5 and higher ([#7044]({{ site.repository }}/issues/7044))
+- Ignore permission error of /proc/version ([#7267]({{ site.repository }}/issues/7267))
+- Strip extra slashes via `Jekyll.sanitized_path` ([#7182]({{ site.repository }}/issues/7182))
+- Site template: remove default config for markdown ([#7285]({{ site.repository }}/issues/7285))
+- Add a custom inspect string for StaticFile objects ([#7422]({{ site.repository }}/issues/7422))
+- Remind user to include gem in the Gemfile on error ([#7476]({{ site.repository }}/issues/7476))
+- Search Front matter defaults for Page objects with relative_path ([#7261]({{ site.repository }}/issues/7261))
+- Lock use of `tzinfo` gem to v1.x ([#7521]({{ site.repository }}/issues/7521), [#7562]({{ site.repository }}/issues/7562))
+- Utilize absolute paths of user-provided file paths ([#7450]({{ site.repository }}/issues/7450))
+- Detect `nil` and empty values in objects with `where` filter ([#7580]({{ site.repository }}/issues/7580))
+- Initialize mutations for Drops only if necessary ([#7657]({{ site.repository }}/issues/7657))
+- Reduce Array allocations via Jekyll::Cleaner ([#7659]({{ site.repository }}/issues/7659))
+- Encode and unencode urls only as required ([#7654]({{ site.repository }}/issues/7654))
+- Reduce string allocations with better alternatives ([#7643]({{ site.repository }}/issues/7643))
+- Reduce allocations from Jekyll::Document instances ([#7625]({{ site.repository }}/issues/7625))
+- Add `type` attribute to Document instances ([#7406]({{ site.repository }}/issues/7406))
+- Reduce allocations from where-filter ([#7653]({{ site.repository }}/issues/7653))
+- Memoize SiteDrop#documents to reduce allocations ([#7697]({{ site.repository }}/issues/7697))
+- Add PathManager class to cache interim paths ([#7732]({{ site.repository }}/issues/7732))
+- Remove warnings and fixes for deprecated config ([#7440]({{ site.repository }}/issues/7440))
+- Delegate --profile tabulation to `terminal-table` ([#7627]({{ site.repository }}/issues/7627))
+
+### Bug Fixes
+{: #bug-fixes-v4-0-0}
+
+- Security: fix `include` bypass of `EntryFilter#filter` symlink check ([#7226]({{ site.repository }}/issues/7226))
+- Theme gems: ensure directories aren't symlinks ([#7419]({{ site.repository }}/issues/7419))
+- Add call to unused method `validate_options` in `commands/serve.rb` ([#7122]({{ site.repository }}/issues/7122))
+- Check if scope applies to type before given path ([#7263]({{ site.repository }}/issues/7263))
+- Document two methods, simplify one of the methods ([#7270]({{ site.repository }}/issues/7270))
+- Check key in collections only if it isn't "posts" ([#7277]({{ site.repository }}/issues/7277))
+- Interpolate Jekyll::Page subclass on inspection ([#7203]({{ site.repository }}/issues/7203))
+- Measure the no. of times a template gets rendered ([#7316]({{ site.repository }}/issues/7316))
+- Reduce array traversal in Jekyll::Reader ([#7157]({{ site.repository }}/issues/7157))
+- Re-implement handling Liquid blocks in excerpts ([#7250]({{ site.repository }}/issues/7250))
+- Documents should be able to render their date ([#7404]({{ site.repository }}/issues/7404))
+- Fix Interpreter warning from Jekyll::Renderer ([#7448]({{ site.repository }}/issues/7448))
+- Loggers should accept both numbers and symbols ([#6967]({{ site.repository }}/issues/6967))
+- Replace regex arg to :gsub with a string arg ([#7189]({{ site.repository }}/issues/7189))
+- Dont write static files from unrendered collection ([#7410]({{ site.repository }}/issues/7410))
+- Excerpt handling of custom and intermediate tags ([#7382]({{ site.repository }}/issues/7382))
+- Change future post loglevel to warn to help user narrow down issues ([#7527]({{ site.repository }}/issues/7527))
+- Handle files with trailing dots in their basename ([#7315]({{ site.repository }}/issues/7315))
+- Fix unnecessary allocations via StaticFileReader ([#7572]({{ site.repository }}/issues/7572))
+- Don't check if site URL is absolute if it is nil ([#7498]({{ site.repository }}/issues/7498))
+- Avoid unnecessary duplication of pages array ([#7272]({{ site.repository }}/issues/7272))
+- Memoize Site#post_attr_hash ([#7276]({{ site.repository }}/issues/7276))
+- Memoize Document#excerpt_separator ([#7569]({{ site.repository }}/issues/7569))
+- Optimize Document::DATE_FILENAME_MATCHER to match valid filenames ([#7292]({{ site.repository }}/issues/7292))
+- Escape valid special chars in a site's path name ([#7568]({{ site.repository }}/issues/7568))
+- Replace `name` in Page#inspect with relative_path ([#7434]({{ site.repository }}/issues/7434))
+- Log a warning when the slug is empty ([#7357]({{ site.repository }}/issues/7357))
+- Push Markdown link refs to excerpt only as required ([#7577]({{ site.repository }}/issues/7577))
+- Fix broken include_relative usage in excerpt ([#7633]({{ site.repository }}/issues/7633))
+- Initialize and reset glob_cache only as necessary ([#7658]({{ site.repository }}/issues/7658))
+- Revert memoizing Site#docs_to_write and #documents ([#7684]({{ site.repository }}/issues/7684))
+- Backport [#7684]({{ site.repository }}/issues/7684) for v3.8.x: Revert memoizing Site#docs_to_write and refactor #documents ([#7689]({{ site.repository }}/issues/7689))
+- Backport [#7213]({{ site.repository }}/issues/7213) and [#7633]({{ site.repository }}/issues/7633) for v3.8.x: Fix broken include_relative usage in excerpt ([#7690]({{ site.repository }}/issues/7690))
+- Don't read symlinks in site.include in safe mode ([#7711]({{ site.repository }}/issues/7711))
+- Replace `String#=~` with `String#match?` ([#7723]({{ site.repository }}/issues/7723))
+- Update log output for an invalid theme directory ([#7679]({{ site.repository }}/issues/7679))
+- Remove configuration of theme sass files from Core ([#7290]({{ site.repository }}/issues/7290))
+- Actually conditionally include liquid-c ([#7792]({{ site.repository }}/issues/7792))
+- Test number_like regex on stringified property ([#7788]({{ site.repository }}/issues/7788))
+
+### Development Fixes
+{: #development-fixes-v4-0-0}
+
+- Upgrade liquid-c to v4.0 ([#7375]({{ site.repository }}/issues/7375))
+- Bump RuboCop to v0.71.0 ([#7687]({{ site.repository }}/issues/7687))
+- Target Ruby 2.4 syntax ([#7583]({{ site.repository }}/issues/7583))
+- Fix: RuboCop offenses ([#7769]({{ site.repository }}/issues/7769))
+- Use communicative method parameters ([#7566]({{ site.repository }}/issues/7566))
+- Scan `assert_equal` methods and rectify any offenses with a custom RuboCop cop ([#7130]({{ site.repository }}/issues/7130))
+- CI: Test with Ruby 2.6 ([#7438]({{ site.repository }}/issues/7438))
+- CI: Test with Ruby 2.6 on AppVeyor ([#7518]({{ site.repository }}/issues/7518))
+- CI: Update RuboCop config ([#7050]({{ site.repository }}/issues/7050))
+- CI: Add a script to profile docs ([#7540]({{ site.repository }}/issues/7540))
+- CI(Appveyor): shallow clone with 5 last commits ([#7312]({{ site.repository }}/issues/7312))
+- CI: Test with oldest and latest Ruby only ([#7412]({{ site.repository }}/issues/7412))
+- CI: Update excludes for CodeClimate Analyses ([#7365]({{ site.repository }}/issues/7365))
+- CI: Lock Travis to Bundler-1.16.2 ([#7144]({{ site.repository }}/issues/7144))
+- CI: Bump tested version of JRuby to 9.2.7.0 ([#7612]({{ site.repository }}/issues/7612))
+- CI: Do not install docs on updating gems on Travis ([#7706]({{ site.repository }}/issues/7706))
+- Update gemspec ([#7425]({{ site.repository }}/issues/7425))
+- deps: relax version constraint on classifier-reborn gem ([#7471]({{ site.repository }}/issues/7471))
+- deps: update yajl-ruby ([#7278]({{ site.repository }}/issues/7278))
+- deps: bump yajl-ruby to v1.4.0 ([#6976]({{ site.repository }}/issues/6976))
+- Create symlink only if target is accessible ([#7429]({{ site.repository }}/issues/7429))
+- Switch to `:install_if` for wdm gem ([#7372]({{ site.repository }}/issues/7372))
+- Add cucumber feature to test include_relative tag ([#7213]({{ site.repository }}/issues/7213))
+- Small benchmark refactoring ([#7211]({{ site.repository }}/issues/7211))
+- Fix incorrectly passed arguments to assert_equal ([#7134]({{ site.repository }}/issues/7134))
+- fix up refute_equal call ([#7133]({{ site.repository }}/issues/7133))
+- Fix RuboCop offences in test files ([#7128]({{ site.repository }}/issues/7128))
+- Use assert_include ([#7093]({{ site.repository }}/issues/7093))
+- Remember to release docs gem ([#7066]({{ site.repository }}/issues/7066))
+- Useless privates removed ([#6768]({{ site.repository }}/issues/6768))
+- Load Rouge for TestKramdown ([#7007]({{ site.repository }}/issues/7007))
+- Update instructions for releasing docs Gem ([#6975]({{ site.repository }}/issues/6975))
+- We are not using Ruby 2.2 anymore ([#6977]({{ site.repository }}/issues/6977))
+- Remove unnecessary Jekyll::Page constant ([#6770]({{ site.repository }}/issues/6770))
+- Remove unused error class ([#6511]({{ site.repository }}/issues/6511))
+- Add a Cucumber feature for post_url tag ([#7586]({{ site.repository }}/issues/7586))
+- Generate a "TOTAL" row for build-profile table ([#7614]({{ site.repository }}/issues/7614))
+- Refactor Jekyll::Cache ([#7532]({{ site.repository }}/issues/7532))
+- Store list of expected extnames in a constant ([#7638]({{ site.repository }}/issues/7638))
+- Profile allocations from a build session ([#7646]({{ site.repository }}/issues/7646))
+- Update small typo in contributing.md ([#7671]({{ site.repository }}/issues/7671))
+- Remove override to Jekyll::Document#respond_to? ([#7695]({{ site.repository }}/issues/7695))
+- Update TestTags in sync with Rouge v3.4 ([#7709]({{ site.repository }}/issues/7709))
+- Use regexp to filter special entries ([#7702]({{ site.repository }}/issues/7702))
+- Reduce Array objects generated from utility method ([#7749]({{ site.repository }}/issues/7749))
+- Update mime.types ([#7756]({{ site.repository }}/issues/7756))
+- Replace redundant Array#map with Array#each ([#7761]({{ site.repository }}/issues/7761))
+- Reduce allocations by using #each_with_object ([#7758]({{ site.repository }}/issues/7758))
+- Memoize fallback_data for Drop ([#7728]({{ site.repository }}/issues/7728))
+- Use String#end_with? to check if entry is a backup ([#7701]({{ site.repository }}/issues/7701))
+
+### Documentation
+
+- Refactor docs ([#7205]({{ site.repository }}/issues/7205))
+- Add a link to Giraffe Academy's tutorial ([#7325]({{ site.repository }}/issues/7325))
+- Do not advise users to install Jekyll outside of Bundler ([#6927]({{ site.repository }}/issues/6927))
+- Remove documentation for using Redcarpet ([#6990]({{ site.repository }}/issues/6990))
+- Install Docs that Work on MacOS 10.14 ([#7561]({{ site.repository }}/issues/7561))
+- Add Installation Instructions for Ubuntu ([#6925]({{ site.repository }}/issues/6925))
+- Don't prompt for sudo when installing with Ubuntu WSL ([#6781]({{ site.repository }}/issues/6781))
+- Installation instructions for Fedora ([#7198]({{ site.repository }}/issues/7198))
+- Update Windows install docs ([#6926]({{ site.repository }}/issues/6926))
+- List all standard liquid filters ([#7333]({{ site.repository }}/issues/7333))
+- List all static files variables ([#7002]({{ site.repository }}/issues/7002))
+- Improve how to include Rouge stylesheets ([#7752]({{ site.repository }}/issues/7752))
+- Mention CommonMark plugins ([#7418]({{ site.repository }}/issues/7418))
+- Add TSV to list of supported _data files. ([#7168]({{ site.repository }}/issues/7168))
+- How to deploy using pre-push git hook ([#7179]({{ site.repository }}/issues/7179))
+- Hosting with AWS Amplify ([#7510]({{ site.repository }}/issues/7510))
+- CircleCI deployment through CircleCI v2 ([#7024]({{ site.repository }}/issues/7024))
+- GitHub Pages: use themes from other repos ([#7112]({{ site.repository }}/issues/7112))
+- Document page.dir and page.name ([#7373]({{ site.repository }}/issues/7373))
+- Document custom tag blocks ([#7359]({{ site.repository }}/issues/7359))
+- Document converter methods ([#7289]({{ site.repository }}/issues/7289))
+- Document {% raw %}`{{ page.collection }}`{% endraw %} ([#7430]({{ site.repository }}/issues/7430))
+- Document Jekyll Filters with YAML data ([#7335]({{ site.repository }}/issues/7335))
+- Document where Jekyll looks for layouts in a site ([#7564]({{ site.repository }}/issues/7564))
+- plugin: liquid tag jekyll-flickr ([#6946]({{ site.repository }}/issues/6946))
+- plugin: jekyll-target-blank ([#7046]({{ site.repository }}/issues/7046))
+- plugin: json-get. ([#7086]({{ site.repository }}/issues/7086))
+- plugin: `jekyll-info` ([#7091]({{ site.repository }}/issues/7091))
+- plugin: jekyll-xml-source ([#7114]({{ site.repository }}/issues/7114))
+- plugin: jekyll-firstimage filter ([#7127]({{ site.repository }}/issues/7127))
+- plugin: CAT ([#7011]({{ site.repository }}/issues/7011))
+- Resources: Statictastic ([#7593]({{ site.repository }}/issues/7593))
+- Resources: Bonsai Search ([#7543]({{ site.repository }}/issues/7543))
+- Resources: Formspark ([#7601]({{ site.repository }}/issues/7601))
+- Resources: Jekpack([#7598]({{ site.repository }}/issues/7598))
+- Resources: formX ([#7536]({{ site.repository }}/issues/7536))
+- Resources: 99inbound's Jekyll post ([#7348]({{ site.repository }}/issues/7348))
+- Resources: CloudSh ([#7497]({{ site.repository }}/issues/7497))
+- Community:  DEV Community's Jekyll tag ([#7139]({{ site.repository }}/issues/7139))
+- Showcase: developer.spotify.com ([#7217]({{ site.repository }}/issues/7217))
+- Showcase: Isomer ([#7300]({{ site.repository }}/issues/7300))
+- Add version number for group_by_exp doc ([#6956]({{ site.repository }}/issues/6956))
+- Updated nginx configuration for custom-404-page documentation ([#6994]({{ site.repository }}/issues/6994))
+- Clarify definition of 'draft' ([#7037]({{ site.repository }}/issues/7037))
+- _drafts need to be contained within the custom collection directory ([#6985]({{ site.repository }}/issues/6985))
+- Updated to supported version ([#7031]({{ site.repository }}/issues/7031))
+- Add Hints for some Improved Travis Config in Doc ([#7049]({{ site.repository }}/issues/7049))
+- Update travis-ci.md to point out "this is an example Gemfile" ([#7089]({{ site.repository }}/issues/7089))
+- Instructions to view theme’s files under Linux ([#7095]({{ site.repository }}/issues/7095))
+- Use a real theme in the example ([#7125]({{ site.repository }}/issues/7125))
+- Update docs about post creation ([#7138]({{ site.repository }}/issues/7138))
+- Initialize upgrading doc for v4.0 ([#7140]({{ site.repository }}/issues/7140))
+- Add version badge for date filters with ordinal ([#7162]({{ site.repository }}/issues/7162))
+- Corrected sample usage of postfiles ([#7181]({{ site.repository }}/issues/7181))
+- Resolve "Unable to locate package ruby2.4" error ([#7196]({{ site.repository }}/issues/7196))
+- Correct stylesheet url in tutorial step 7 ([#7210]({{ site.repository }}/issues/7210))
+- Removes quotes from markdown for assets ([#7223]({{ site.repository }}/issues/7223))
+- Clarified front matter requirement ([#7234]({{ site.repository }}/issues/7234))
+- Explicit location of where to create blog.html ([#7241]({{ site.repository }}/issues/7241))
+- Reference the build command options that allows multiple config files ([#7266]({{ site.repository }}/issues/7266))
+- Add more issue template(s) and pull request template ([#7269]({{ site.repository }}/issues/7269))
+- Suggest sites use OpenSSL instead of GnuTLS for their site's CI ([#7010]({{ site.repository }}/issues/7010))
+- Fix broken Contributors link in README.markdown ([#7200]({{ site.repository }}/issues/7200))
+- Add title tag to item in RSS template ([#7282]({{ site.repository }}/issues/7282))
+- Add link tag to item in RSS template ([#7291]({{ site.repository }}/issues/7291))
+- Remove redundant instruction comment ([#7342]({{ site.repository }}/issues/7342))
+- Textile is only supported through a converter plugin ([#7003]({{ site.repository }}/issues/7003))
+- Add recursive navigation tutorial ([#7720]({{ site.repository }}/issues/7720))
+- Remove installation instructions with Homebrew ([#7381]({{ site.repository }}/issues/7381))
+- Fix dead link and misleading prose ([#7383]({{ site.repository }}/issues/7383))
+- Fix content management section ([#7385]({{ site.repository }}/issues/7385))
+- Apply ruby official guide documents ([#7393]({{ site.repository }}/issues/7393))
+- Fix group_by_exp filter example ([#7394]({{ site.repository }}/issues/7394))
+- Remove alt attribute from a tags ([#7407]({{ site.repository }}/issues/7407))
+- Fix BASH code-block in ubuntu.md ([#7420]({{ site.repository }}/issues/7420))
+- zlib is missing ([#7428]({{ site.repository }}/issues/7428))
+- Fixed unnecessary aticles and pronouns ([#7466]({{ site.repository }}/issues/7466))
+- Store SSL key and cert in site source ([#7473]({{ site.repository }}/issues/7473))
+- Fix typo in tutorial for converting existing site ([#7524]({{ site.repository }}/issues/7524))
+- Check if var exists before include tag ([#7530]({{ site.repository }}/issues/7530))
+- Clarify docs on collections regarding the need for front matter ([#7538]({{ site.repository }}/issues/7538))
+- Fix incorrect Windows path in themes.md ([#7525]({{ site.repository }}/issues/7525))
+- Addresses bundle not found. ([#7351]({{ site.repository }}/issues/7351))
+- Update the contribution docs for draft pull requests ([#7619]({{ site.repository }}/issues/7619))
+- Data file section adds TSV ([#7640]({{ site.repository }}/issues/7640))
+- Indicate where the _sass folder is by default ([#7644]({{ site.repository }}/issues/7644))
+- Docs: add version tags to new placeholders ([#5981]({{ site.repository }}/issues/5981)) for permalinks ([#7647]({{ site.repository }}/issues/7647))
+- Solve "GitHub Page build failure" in 10-deployment.md ([#7648]({{ site.repository }}/issues/7648))
+- fix link to Site Source config ([#7708]({{ site.repository }}/issues/7708))
+- Introduce frontmatter in step 2 ([#7704]({{ site.repository }}/issues/7704))
+- Add @ashmaroli to Core Team listing ([#7398]({{ site.repository }}/issues/7398))
+- Lnk to Tidelift in site's footer ([#7377]({{ site.repository }}/issues/7377))
+- Link to OpenCollective backing ([#7378]({{ site.repository }}/issues/7378)
+- Link to sponsor listing in README ([#7405]({{ site.repository }}/issues/7405))
+- Adjust team page listings ([#7395]({{ site.repository }}/issues/7395))
+- Updates to CODE OF CONDUCT (v1.4.0) ([#7105]({{ site.repository }}/issues/7105))
+- More inclusive writing ([#7283]({{ site.repository }}/issues/7283))
+- Update Ruby version used in Travis-CI example ([#7783]({{ site.repository }}/issues/7783))
+- Documentation for binary operators in where_exp ([#7786]({{ site.repository }}/issues/7786))
+- Adding SmartForms as Forms service ([#7794]({{ site.repository }}/issues/7794))
+
+### Site Enhancements
+{: #site-enhancements-v4-0-0}
+
+- Better Performance ([#7388]({{ site.repository }}/issues/7388))
+- Add some minor improvements to image loading in Showcase page ([#7214]({{ site.repository }}/issues/7214))
+- Simplify assigning classname to docs' aside-links ([#7609]({{ site.repository }}/issues/7609))
+- Simplify couple of includes in the docs site ([#7607]({{ site.repository }}/issues/7607))
+- Avoid generating empty classnames ([#7610]({{ site.repository }}/issues/7610))
+- Minimize rendering count ([#7343]({{ site.repository }}/issues/7343))
+
+### Release
+
+- Release post for v4.0.0 beta1 ([#7716]({{ site.repository }}/issues/7716))
+- Release post for v4.0.0.pre.alpha1 ([#7574]({{ site.repository }}/issues/7574))
+- Release post for v3.8.0 ([#6849]({{ site.repository }}/issues/6849))
+- Release post for v3.6.3, v3.7.4 and v3.8.4 ([#7259]({{ site.repository }}/issues/7259))
+- Post: v4.0 development ([#6934]({{ site.repository }}/issues/6934))
+
+
+## 3.8.6 / 2019-07-02
+{: #v3-8-6}
+
+### Bug Fixes
+{: #bug-fixes-v3-8-6}
+
+- Update log output for an invalid theme directory ([#7734]({{ site.repository }}/issues/7734))
+- Memoize `SiteDrop#documents` to reduce allocations ([#7722]({{ site.repository }}/issues/7722))
+- Excerpt handling of custom and intermediate tags ([#7467]({{ site.repository }}/issues/7467))
+- Escape valid special chars in a site's path name ([#7573]({{ site.repository }}/issues/7573))
+- Revert memoizing `Site#docs_to_write` and refactor `#documents` ([#7689]({{ site.repository }}/issues/7689))
+- Fix broken `include_relative` usage in excerpt ([#7690]({{ site.repository }}/issues/7690))
+- Install platform-specific gems as required (3c06609406)
+
+### Security Fixes
+{: #security-fixes-v3-8-6}
+
+- Theme gems: ensure directories aren't symlinks ([#7424]({{ site.repository }}/issues/7424))
+
+
 ## 3.8.5 / 2018-11-04
 {: #v3-8-5}
 
@@ -77,10 +413,10 @@ note: This file is autogenerated. Edit /History.markdown instead.
 - Minimize array allocations in the `where` filter ([#6860]({{ site.repository }}/issues/6860))
 - Bump JRuby ([#6878]({{ site.repository }}/issues/6878))
 - Assert existence of <collection>.files ([#6907]({{ site.repository }}/issues/6907))
-- Bump Rubocop to 0.54.x ([#6915]({{ site.repository }}/issues/6915))
+- Bump RuboCop to 0.54.x ([#6915]({{ site.repository }}/issues/6915))
 - Regenerate unconditionally unless its an incremental build ([#6917]({{ site.repository }}/issues/6917))
 - Centralize require statements ([#6910]({{ site.repository }}/issues/6910))
-- Bump to Rubocop 0.55 ([#6929]({{ site.repository }}/issues/6929))
+- Bump to RuboCop 0.55 ([#6929]({{ site.repository }}/issues/6929))
 - Refactor private method `HighlightBlock#parse_options` ([#6822]({{ site.repository }}/issues/6822))
 
 ### Minor Enhancements

docs/_docs/includes.md

@@ -13,44 +13,7 @@ The `include` tag allows you to include the content from another file stored in
 
 Jekyll will look for the referenced file (in this case, `footer.html`) in the `_includes` directory at the root of your source directory and insert its contents.
 
-## Parameters
-
-Includes can take parameters which is especially useful for reducing repetition across your Jekyll site.
-
-To use parameters you pass a list of key/values to the include:
-
-{% raw %}
-```liquid
-{% include note.html style="big" content="This is my sample note." %}
-```
-{% endraw %}
-
-The parameters are available in the include under the `include` variable:
-
-{% raw %}
-```liquid
-<div class="my-note {{ include.style }}">
-  {{ include.content }}
-</div>
-```
-{% endraw %}
-
-To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://shopify.github.io/liquid/filters/default/).
-
-If you need to modify a variable before sending it to the include, you can save it to an intermediate variable. For example this is one way to prepend a string to variable used in an include:
-
-{% raw %}
-```liquid
-{% capture download_note %}
-The latest version of {{ site.product_name }} is now available.
-{% endcapture %}
-{% include note.html style="big" content=download_note %}
-```
-{% endraw %}
-
-
-
-## Including files relative to another file
+### Including files relative to another file
 
 You can choose to include file fragments relative to the current file by using the `include_relative` tag:
 
@@ -70,7 +33,7 @@ Note that you cannot use the `../` syntax to specify an include location that re
 All the other capabilities of the `include` tag are available to the `include_relative` tag,
 such as variables.
 
-## Include file by variable
+### Using variables names for the include file
 
 The name of the file you want to embed can be specified as a variable instead of an actual file name. For example, suppose you defined a variable in your page's front matter like this:
 
@@ -85,8 +48,109 @@ You could then reference that variable in your include:
 
 {% raw %}
 ```liquid
-{% include {{ page.my_variable }} %}
+{% if page.my_variable %}
+  {% include {{ page.my_variable }} %}
+{% endif %}
 ```
 {% endraw %}
 
 In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory.
+
+### Passing parameters to includes
+
+You can also pass parameters to an include. For example, suppose you have a file called `note.html` in your `_includes` folder that contains this formatting:
+
+{% raw %}
+```liquid
+<div markdown="span" class="alert alert-info" role="alert">
+<i class="fa fa-info-circle"></i> <b>Note:</b>
+{{ include.content }}
+</div>
+```
+{% endraw %}
+
+The `{% raw %}{{ include.content }}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this:
+
+{% raw %}
+```liquid
+{% include note.html content="This is my sample note." %}
+```
+{% endraw %}
+
+The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter.
+
+Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content.
+
+For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you might want to populate with an include:
+
+```html
+<figure>
+   <a href="http://jekyllrb.com">
+   <img src="logo.png" style="max-width: 200px;"
+      alt="Jekyll logo" />
+   </a>
+   <figcaption>This is the Jekyll logo</figcaption>
+</figure>
+```
+
+You could templatize this content in your include and make each value available as a parameter, like this:
+
+{% raw %}
+```liquid
+<figure>
+   <a href="{{ include.url }}">
+   <img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
+      alt="{{ include.alt }}"/>
+   </a>
+   <figcaption>{{ include.caption }}</figcaption>
+</figure>
+```
+{% endraw %}
+
+This include contains 5 parameters:
+
+* `url`
+* `max-width`
+* `file`
+* `alt`
+* `caption`
+
+Here's an example that passes all the parameters to this include (the include file is named `image.html`):
+
+{% raw %}
+```liquid
+{% include image.html url="http://jekyllrb.com"
+max-width="200px" file="logo.png" alt="Jekyll logo"
+caption="This is the Jekyll logo." %}
+```
+{% endraw %}
+
+The result is the original HTML code shown earlier.
+
+To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://shopify.github.io/liquid/filters/default/).
+
+Overall, you can create includes that act as templates for a variety of uses &mdash; inserting audio or video clips, alerts, special formatting, and more. Note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.)
+
+### Passing parameter variables to includes
+
+Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{ site.product_name }}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.)
+
+The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{ site.product_name }} is now available."`{% endraw %}
+
+If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable:
+
+{% raw %}
+```liquid
+{% capture download_note %}
+The latest version of {{ site.product_name }} is now available.
+{% endcapture %}
+```
+{% endraw %}
+
+Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable):
+
+{% raw %}
+```liquid
+{% include note.html content=download_note %}
+```
+{% endraw %}

docs/_docs/installation.md

@@ -8,7 +8,7 @@ Jekyll is a [Ruby Gem](/docs/ruby-101/#gems) that can be installed on most syste
 
 ## Requirements
 
-* [Ruby](https://www.ruby-lang.org/en/downloads/) version 2.2.5 or above, including all development headers (ruby version can be checked by running `ruby -v`)
+* [Ruby](https://www.ruby-lang.org/en/downloads/) version **{{ site.data.ruby.min_version }}** or above, including all development headers (ruby version can be checked by running `ruby -v`)
 * [RubyGems](https://rubygems.org/pages/download) (which you can check by running `gem -v`)
 * [GCC](https://gcc.gnu.org/install/) and [Make](https://www.gnu.org/software/make/) (in case your system doesn't have them installed, which you can check by running `gcc -v`,`g++ -v`  and `make -v` in your system's command line interface)
 

docs/_docs/installation/macos.md

@@ -3,45 +3,55 @@ title: Jekyll on macOS
 permalink: /docs/installation/macos/
 ---
 
+## Install Command Line Tools
 First, you need to install the command-line tools to be able to compile native extensions, open a terminal and run:
 
 ```sh
 xcode-select --install
 ```
 
-## Set up Ruby included with the OS
+## Install Ruby
 
-Check your Ruby version meets our requirements. Jekyll requires Ruby 2.2.5 or above. If you're running an older version you'll need to [install a more recent Ruby version via Homebrew](#homebrew).
-
-```sh
-ruby -v
-2.3.3
-```
-
-Now install Jekyll and [Bundler](/docs/ruby-101/#bundler).
-
-```sh
-gem install bundler jekyll
-```
-
-### Install a newer Ruby version via Homebrew {#homebrew}
-
-If you wish to install the latest version of Ruby and get faster builds, we recommend doing it via [Homebrew](https://brew.sh) a handy package manager for macOS.
+Jekyll requires **Ruby > {{ site.data.ruby.min_version }}**.
+As macOS Mojave 10.14 comes only with ruby 2.3.x, you'll have to install a newer version of Ruby.
+
+### With Homebrew {#brew}
+To run the latest Ruby version you need to install it through [Homebrew](https://brew.sh).
 
 ```sh
+# Install Homebrew
 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
 brew install ruby
-ruby -v
-ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]
 ```
 
-### Install multiple Ruby versions with rbenv {#rbenv}
+Add the brew ruby path to your shell config :
 
-Developers often use [rbenv](https://github.com/rbenv/rbenv) to manage multiple
-Ruby versions. This can be useful if you want to run the same Ruby version used
-by your colleagues/collaborators.
+```
+export PATH=/usr/local/opt/ruby/bin:$PATH
+```
+
+Then relaunch your terminal and check your updated Ruby setup:
 
 ```sh
+which ruby
+# /usr/local/opt/ruby/bin/ruby
+
+ruby -v
+{{ site.data.ruby.current_version_output }}
+```
+
+Yay, we are now running current stable Ruby!
+
+### With rbenv {#rbenv}
+
+People often use [rbenv](https://github.com/rbenv/rbenv) to manage multiple
+Ruby versions. This is very useful when you need to be able to run a given Ruby version on a project.
+
+```sh
+# Install Homebrew
+/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
 # Install rbenv and ruby-build
 brew install rbenv
 
@@ -53,17 +63,73 @@ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor
 ```
 
 Restart your terminal for changes to take effect.
-Now we can install the Ruby version of our choice, let's go with Ruby 2.5.1 here:
+Now you can install the Ruby version of our choice, let's go with current latest stable Ruby:
 
 ```sh
-rbenv install 2.5.1
-rbenv global 2.5.1
+rbenv install {{ site.data.ruby.current_version }}
+rbenv global {{ site.data.ruby.current_version }}
 ruby -v
-ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]
+{{ site.data.ruby.current_version_output }}
 ```
 
 That's it! Head over [rbenv command references](https://github.com/rbenv/rbenv#command-reference) to learn how to use different versions of Ruby in your projects.
 
-### Problems?
+## Install Jekyll
+
+Now all that is left is installing [Bundler](/docs/ruby-101/#bundler) and Jekyll.
+
+### Local Install
+
+```sh
+gem install --user-install bundler jekyll
+```
+
+and then get your Ruby version using
+
+```sh
+ruby -v
+{{ site.data.ruby.current_version_output }}
+```
+
+Then append your path file with the following, replacing the `X.X` with the first two digits of your Ruby version.
+
+```
+export PATH=$HOME/.gem/ruby/X.X.0/bin:$PATH
+```
+
+To check your that you gem paths point to your home directory run:
+
+```sh
+gem env
+```
+
+And check that `GEM PATHS:` points to a path in your home directory
+
+{: .note }
+Every time you update Ruby to a version with a different first two digits, you will need to update your path to match.
+
+### Global Install
+
+{: .note .warning}
+We strongly recommend against installing Ruby gems globally to avoid file permissions problems and using `sudo`.
+
+#### On Mojave (10.14)
+
+Because of SIP Protections in Mojave, you must run:
+
+```sh
+sudo gem install bundler
+sudo gem install -n /usr/local/bin/ jekyll
+```
+
+#### Before Mojave (<10.14)
+
+You only have to run:
+
+```sh
+sudo gem install bundler jekyll
+```
+
+## Problems?
 
 Check out the [troubleshooting](/docs/troubleshooting/) page or [ask for help on our forum](https://talk.jekyllrb.com).

docs/_docs/installation/ubuntu.md

@@ -6,7 +6,7 @@ Before we install Jekyll, we need to make sure we have all the required
 dependencies.
 
 ```sh
-sudo apt-get install ruby ruby-dev build-essential
+sudo apt-get install ruby-full build-essential zlib1g-dev
 ```
 
 It is best to avoid installing Ruby Gems as the root user. Therefore, we need to
@@ -16,8 +16,8 @@ the gem installation path. Run them now:
 
 ```sh
 echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
-echo 'export GEM_HOME=$HOME/gems' >> ~/.bashrc
-echo 'export PATH=$HOME/gems/bin:$PATH' >> ~/.bashrc
+echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
+echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
 source ~/.bashrc
 ```
 

docs/_docs/installation/windows.md

@@ -5,66 +5,36 @@ redirect_from:
   - /docs/windows/
 ---
 
-While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks. This page aims to collect some of the general knowledge and lessons that have been unearthed by Windows users.
+While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks. This page aims to
+collect some of the general knowledge and lessons that have been unearthed by Windows users.
 
 
 ## Installing Jekyll
-The easiest way to run Jekyll is by using the [RubyInstaller](https://rubyinstaller.org/) for Windows.
 
 ### Installation via RubyInstaller
 
-[RubyInstaller](https://rubyinstaller.org/) is a self-contained Windows-based installer that includes the Ruby language, an execution environment, important documentation, and more.
-We only cover RubyInstaller-2.4 and newer here, older versions need to [install the Devkit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit) manually.
+The easiest way to run Jekyll is by using the [RubyInstaller](https://rubyinstaller.org/) for Windows.
+
+RubyInstaller is a self-contained Windows-based installer that includes the Ruby language, an execution environment,
+important documentation, and more.
+We only cover RubyInstaller-2.4 and newer here, older versions need to
+[install the Devkit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit) manually.
 
 1. Download and Install a **Ruby+Devkit** version from [RubyInstaller Downloads](https://rubyinstaller.org/downloads/).
    Use default options for installation.
-2. Open a new command prompt window from the start menu, so that changes to the `PATH` environment variable becomes effective.
+2. Run the `ridk install` step on the last stage of the installation wizard. This is needed for installing gems with native
+   extensions. You can find additional information regarding this in the
+   [RubyInstaller Documentation](https://github.com/oneclick/rubyinstaller2#using-the-installer-on-a-target-system)
+3. Open a new command prompt window from the start menu, so that changes to the `PATH` environment variable becomes effective.
    Install Jekyll and Bundler via: `gem install jekyll bundler`
-3. Check if Jekyll installed properly: `jekyll -v`
+4. Check if Jekyll installed properly: `jekyll -v`
 
 That's it, you're ready to use Jekyll!
 
-### Encoding
-
-If you use UTF-8 encoding, make sure that no `BOM` header characters exist in your files or very, very bad things will happen to
-Jekyll. This is especially relevant when you're running Jekyll on Windows.
-
-Additionally, you might need to change the code page of the console window to UTF-8 in case you get a "Liquid Exception: Incompatible character encoding" error during the site generation process. It can be done with the following command:
-
-```sh
-chcp 65001
-```
-
-### Time-Zone Management
-
-Since Windows doesn't have a native source of zoneinfo data, the Ruby Interpreter would not understand IANA Timezones and hence using them had the `TZ` environment variable default to UTC/GMT 00:00.
-Though Windows users could alternatively define their blog's timezone by setting the key to use POSIX format of defining timezones, it wasn't as user-friendly when it came to having the clock altered to changing DST-rules.
-
-Jekyll now uses a rubygem to internally configure Timezone based on established [IANA Timezone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-While 'new' blogs created with Jekyll v3.4 and greater, will have the following added to their `Gemfile` by default, existing sites *will* have to update their `Gemfile` (and installed) to enable development on Windows:
-
-```ruby
-# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
-gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
-```
-
-### Auto Regeneration
-
-Jekyll uses the `listen` gem to watch for changes when the `--watch` switch is specified during a build or serve. While `listen` has built-in support for UNIX systems, it may require an extra gem for compatibility with Windows.
-
-Add the following to the `Gemfile` for your site if you have issues with auto-regeneration on Windows alone:
-
-```ruby
-gem 'wdm', '~> 0.1.1' if Gem.win_platform?
-```
-
-You have to use a [Ruby+Devkit](https://rubyinstaller.org/downloads/) version of the RubyInstaller.
-
-
-## Installation via Bash on Windows 10
-
-If you are using Windows 10 version 1607 or later, another option to run Jekyll is by [installing](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) the Windows Subsystem for Linux.
+### Installation via Bash on Windows 10
 
+If you are using Windows 10 version 1607 or later, another option to run Jekyll is by
+[installing](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) the Windows Subsystem for Linux.
 
 *Note:* You must have [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) enabled.
 
@@ -78,7 +48,8 @@ Your Command Prompt instance should now be a Bash instance. Now we must update o
 ```sh
 sudo apt-get update -y && sudo apt-get upgrade -y
 ```
-Now we can install Ruby. To do this we will use a repository from [BrightBox](https://www.brightbox.com/docs/ruby/ubuntu/), which hosts optimized versions of Ruby for Ubuntu.
+Now we can install Ruby. To do this we will use a repository from [BrightBox](https://www.brightbox.com/docs/ruby/ubuntu/),
+which hosts optimized versions of Ruby for Ubuntu.
 
 ```sh
 sudo apt-add-repository ppa:brightbox/ruby-ng
@@ -89,34 +60,90 @@ sudo apt-get install ruby2.5 ruby2.5-dev build-essential dh-autoreconf
 Next let's update our Ruby gems:
 
 ```sh
-sudo gem update
+gem update
 ```
 
 Now all that is left to do is install Jekyll.
 
 ```sh
-sudo gem install jekyll bundler
+gem install jekyll bundler
 ```
 
+(*Note: no `sudo` here.*)
+
 Check if Jekyll installed properly by running:
 
 ```sh
 jekyll -v
 ```
 
-Configure the bundler/gem path so bundle doesn't prompt for sudo
-
-```sh
-bundle config path vendor/bundle
-```
-
 **And that's it!**
 
-You can make sure time management is working properly by inspecting your `_posts` folder. You should see a markdown file with the current date in the filename.
+You can make sure time management is working properly by inspecting your `_posts` folder. You should see a markdown file
+with the current date in the filename.
 
 <div class="note info">
   <h5>Non-superuser account issues</h5>
-  <p>If the `jekyll new` command prints the error "Your user account isn't allowed to install to the system RubyGems", see the "Running Jekyll as Non-Superuser" instructions in <a href="/docs/troubleshooting/#no-sudo">Troubleshooting</a>.</p>
+  <p>If the `jekyll new` command prints the error "Your user account isn't allowed to install to the system RubyGems", see
+  the "Running Jekyll as Non-Superuser" instructions in <a href="/docs/troubleshooting/#no-sudo">Troubleshooting</a>.</p>
 </div>
 
 **Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues.
+
+
+## Encoding
+
+If you use UTF-8 encoding, make sure that no `BOM` header characters exist in your files or very, very bad things will happen to
+Jekyll. This is especially relevant when you're running Jekyll on Windows.
+
+Additionally, you might need to change the code page of the console window to UTF-8 in case you get a
+`Liquid Exception: Incompatible character encoding` error during the site generation process. It can be done with the following
+command:
+
+```sh
+chcp 65001
+```
+
+## Time-Zone Management
+
+Since Windows doesn't have a native source of zoneinfo data, the Ruby Interpreter would not understand IANA Timezones and hence
+using them had the `TZ` environment variable default to UTC/GMT 00:00.
+
+Though Windows users could alternatively define their blog's timezone by setting the key to use POSIX format of defining
+timezones, it wasn't as user-friendly when it came to having the clock altered to changing DST-rules.
+
+Jekyll now uses a rubygem to internally configure Timezone based on established
+[IANA Timezone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+While 'new' blogs created with Jekyll v3.4 and greater, will have the following added to their `Gemfile` by default, existing
+sites *will* have to update their `Gemfile` (and installed) to enable development on Windows:
+
+```ruby
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+```
+
+<div class="note warning">
+  <h5>TZInfo 2.0 incompatibility</h5>
+  <p>
+    <code>v2.0</code> of the TZInfo library has introduced a change in how timezone offsets are calculated.
+    This will result in incorrect date and time for your posts when the site is built with Jekyll 3.x on Windows.
+  </p>
+  <p>
+    We therefore recommend that you lock the Timezone library to <code>v1.2</code> and above by listing
+    <code>gem 'tzinfo', '~> 1.2'</code> in your <code>Gemfile</code>.
+  </p>
+</div>
+
+## Auto Regeneration
+
+Jekyll uses the `listen` gem to watch for changes when the `--watch` switch is specified during a build or serve.
+While `listen` has built-in support for UNIX systems, it may require an extra gem for compatibility with Windows.
+
+Add the following to the `Gemfile` for your site if you have issues with auto-regeneration on Windows alone:
+
+```ruby
+gem 'wdm', '~> 0.1.1', :install_if => Gem.win_platform?
+```
+
+You have to use a [Ruby+Devkit](https://rubyinstaller.org/downloads/) version of the RubyInstaller and install
+the MSYS2 build tools to successfully install the `wdm` gem.

docs/_docs/layouts.md

@@ -11,6 +11,20 @@ Layouts live in the `_layouts` directory. The convention is to have a base
 template called `default.html` and have other layouts [inherit](#inheritance)
 from this as needed.
 
+<div class="note">
+  <h5>Layouts Directory</h5>
+  <p>
+    Jekyll looks for the <code>_layouts</code> directory either at the root of
+    your site's <code>source</code> or at the root of your theme.
+  </p>
+  <p>
+    While you can configure the directory name in which your layouts can reside by
+    setting the <code>layouts_dir</code> key in your config file, the directory
+    itself should be located at the root of your site's <code>source</code> directory.
+  </p>
+</div>
+
+
 ## Usage
 
 The first step is to put the template source code in `default.html`. `content`

docs/_docs/liquid/filters.md

@@ -104,6 +104,37 @@ The default is `default`. They are as follows (with what they filter):
 - `ascii`: spaces, non-alphanumeric, and non-ASCII characters
 - `latin`: like `default`, except Latin characters are first transliterated (e.g. `àèïòü` to `aeiou`) {%- include docs_version_badge.html version="3.7.0" -%}.
 
+### Detecting `nil` values with `where` filter {%- include docs_version_badge.html version="4.0" -%}
+
+You can use the `where` filter to detect documents and pages with properties that are `nil` or `""`. For example,
+
+```liquid
+// Using `nil` to select posts that either do not have `my_prop` defined or `my_prop` has been set to `nil` explicitly.
+{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', nil %}{% endraw %}
+```
+
+```liquid
+// Using Liquid's special literal `empty` or `blank` to select posts that have `my_prop` set to an empty value.
+{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', empty %}{% endraw %}
+```
+
+### Binary operators in `where_exp` filter {%- include docs_version_badge.html version="4.0" -%}
+
+You can use Liquid binary operators `or` and `and` in the expression passed to the `where_exp` filter to employ multiple
+conditionals in the operation.
+
+For example, to get a list of documents on English horror flicks, one could use the following snippet:
+
+```liquid
+{% raw %}{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}{% endraw %}
+```
+
+Or to get a list of comic-book based movies, one may use the following:
+
+```liquid
+{% raw %}{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}{% endraw %}
+```
+
 ### Standard Liquid Filters
 
 For your convenience, here is the list of all [Liquid filters]({{ page.shopify_filter_url }}) with links to examples in the official Liquid documentation.

docs/_docs/liquid/tags.md

@@ -16,19 +16,12 @@ If you have page snippets that you use repeatedly across your site, an
 
 Jekyll has built in support for syntax highlighting of over 100 languages
 thanks to [Rouge](http://rouge.jneen.net). Rouge is the default highlighter
-in Jekyll 3 and above. To use it in Jekyll 2, set `highlighter` to `rouge`
-and ensure the `rouge` gem is installed properly.
+in Jekyll 3 and above.
 
-Alternatively, you can use [Pygments](http://pygments.org) to highlight your
-code snippets in Jekyll 3.x and below. To use Pygments, you must have Python
-installed on your system, have the `pygments.rb` gem installed and set
-`highlighter` to `pygments` in your site's configuration file. Pygments
-supports [over 100 languages](http://pygments.org/languages/)
-
-<div class="note info">
-  <p>Using Pygments has been deprecated and will not be officially supported in
-  Jekyll 4, meaning that the configuration setting <code>highlighter: pygments</code>
-  will automatically fall back to using <em>Rouge</em> which is written in Ruby
+<div class="note warning">
+  <p>Using Pygments has been deprecated and is not supported in
+  Jekyll 4, the configuration setting <code>highlighter: pygments</code>
+  now automatically falls back to using <em>Rouge</em> which is written in Ruby
   and 100% compatible with stylesheets for Pygments.</p>
 </div>
 
@@ -47,13 +40,15 @@ end
 The argument to the `highlight` tag (`ruby` in the example above) is the
 language identifier. To find the appropriate identifier to use for the language
 you want to highlight, look for the “short name” on the [Rouge
-wiki](https://github.com/jayferd/rouge/wiki/List-of-supported-languages-and-lexers)
-or the [Pygments' Lexers page](http://pygments.org/docs/lexers/).
+wiki](https://github.com/jayferd/rouge/wiki/List-of-supported-languages-and-lexers).
 
-### Raw
-Surround a block of code in <code>{&#37; raw &#37;}</code> will ignore Liquid until
-<code>{&#37; endraw &#37;}</code>. This is useful if you're using a language that
-contains curly braces or you're documenting Liquid.
+<div class="note">
+  <h5>Jekyll processes all Liquid filters in code blocks</h5>
+  <p>If you are using a language that contains curly braces, you
+    will likely need to place <code>{&#37; raw &#37;}</code> and
+    <code>{&#37; endraw &#37;}</code> tags around your code.
+    Since {% include docs_version_badge.html version="4.0" %} you can add <code>render_with_liquid: false</code> in your front matter to disable Liquid entirely for a particular document.</p>
+</div>
 
 ### Line numbers
 
@@ -76,10 +71,22 @@ end
 
 In order for the highlighting to show up, you’ll need to include a highlighting
 stylesheet. For Pygments or Rouge you can use a stylesheet for Pygments, you
-can find an example gallery [here](http://help.farbox.com/pygments.html).
+can find an example gallery 
+[here](https://jwarby.github.io/jekyll-pygments-themes/languages/ruby.html) 
+or from [its repository](https://github.com/jwarby/jekyll-pygments-themes).
+
+Copy the CSS file (`native.css` for example) into your css directory and import
+the syntax highlighter styles into your `main.css`:
+
+```css
+@import "native.css";
+```
 
 ## Links
 
+{: .note }
+Since Jekyll {% include docs_version_badge.html version="v4.0"%} you don't need to prepend `link` and `post_url` tags with `site.baseurl`
+
 ### 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.
@@ -88,10 +95,10 @@ You must include the file's original extension when using the `link` tag. Here a
 
 {% raw %}
 ```liquid
-{{ 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 %}
+{% link _collection/name-of-document.md %}
+{% link _posts/2016-07-26-name-of-post.md %}
+{% link news/index.html %}
+{% link /assets/files/doc.pdf %}
 ```
 {% endraw %}
 
@@ -99,15 +106,13 @@ You can also use the `link` tag to create a link in Markdown as follows:
 
 {% raw %}
 ```liquid
-[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 %})
+[Link to a document]({% link _collection/name-of-document.md %})
+[Link to a post]({% link _posts/2016-07-26-name-of-post.md %})
+[Link to a page]({% link news/index.html %})
+[Link to a file]({% 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 in `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`.
@@ -116,7 +121,7 @@ If you're unsure of the path, add `{% raw %}{{ page.path }}{% endraw %}` to the
 
 One major benefit of using the `link` or `post_url` 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.
+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
 
@@ -124,7 +129,7 @@ If you want to include a link to a post on your site, the `post_url` tag will ge
 
 {% raw %}
 ```liquid
-{{ site.baseurl }}{% post_url 2010-07-21-name-of-post %}
+{% post_url 2010-07-21-name-of-post %}
 ```
 {% endraw %}
 
@@ -132,7 +137,7 @@ If you organize your posts in subdirectories, you need to include subdirectory p
 
 {% raw %}
 ```liquid
-{{ site.baseurl }}{% post_url /subdir/2010-07-21-name-of-post %}
+{% post_url /subdir/2010-07-21-name-of-post %}
 ```
 {% endraw %}
 
@@ -142,6 +147,6 @@ You can also use this tag to create a link to a post in Markdown as follows:
 
 {% raw %}
 ```liquid
-[Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
+[Name of Link]({% post_url 2010-07-21-name-of-post %})
 ```
 {% endraw %}

docs/_docs/maintaining/avoiding-burnout.md

@@ -5,21 +5,21 @@ title: "Avoiding Burnout"
 **This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone.
 {: .note .info }
 
-## 1. Use Jekyll
+# 1. Use Jekyll
 
 Maintainers of Jekyll should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users, but also because you may at some point decide to stop using Jekyll, and at that point you should also decide to stop being a maintainer and find other things to work on.
 
-## 2. No Guilt About Leaving
+# 2. No Guilt About Leaving
 
 All maintainers can stop working on Jekyll at any time without any guilt or explanation (like at a job). We may still ask for your help with questions after you leave but you are under no obligation to answer them. If you create a big mess and then leave you still have no obligations but we may think less of you (or, realistically, probably just revert the problematic work). Also, you should probably take a break from Jekyll at least a few times a year.
 
 This also means contributors should be consumers. If a maintainer finds they are not using a project in the real-world, they should reconsider their involvement with the project.
 
-## 3. Prioritise Maintainers Over Users
+# 3. Prioritise Maintainers Over Users
 
 It's important to be user-focused but ultimately, as long as you follow #1 above, Jekyll's minimum number of users will be the number of maintainers. However, if Jekyll has no maintainers it will quickly become useless to all users and the project will die. As a result, no user complaint, behaviour or need takes priority over the burnout of maintainers. If users do not like the direction of the project, the easiest way to influence it is to make significant, high-quality code contributions and become a maintainer.
 
-## 4. Learn To Say No
+# 4. Learn To Say No
 
 Jekyll gets a lot of feature requests, non-reproducible bug reports, usage questions and PRs we won't accept. These should be closed out as soon as we realise that they aren't going to be resolved or merged. This is kinder than deciding this after a long period of review. Our issue tracker should reflect work to be done.
 

docs/_docs/pagination.md

@@ -11,12 +11,16 @@ generate the appropriate files and folders you need for paginated listings.
 For Jekyll 3, include the `jekyll-paginate` plugin in your Gemfile and in
 your `_config.yml` under `plugins`. For Jekyll 2, this is standard.
 
-Pagination does not work from within Markdown files from
-your Jekyll site. Pagination works when called from within the HTML
-file, named `index.html`, which optionally may reside in and
-produce pagination from within a subdirectory, via the
-`paginate_path` configuration value.
-{: .warning }
+<div class="note info">
+  <h5>Pagination only works within HTML files</h5>
+  <p>
+    Pagination does not work from within Markdown files from
+    your Jekyll site. Pagination works when called from within the HTML
+    file, named <code>index.html</code>, which optionally may reside in and
+    produce pagination from within a subdirectory, via the
+    <code>paginate_path</code> configuration value.
+  </p>
+</div>
 
 ## Enable pagination
 
@@ -43,8 +47,24 @@ If a site has 12 posts and specifies `paginate: 5`, Jekyll will write `blog/inde
 with the first 5 posts, `blog/page2/index.html` with the next 5 posts and
 `blog/page3/index.html` with the last 2 posts into the destination directory.
 
-Setting a permalink in the front matter of your blog page will cause pagination to break. Just omit the permalink.
-{: .warning }
+<div class="note warning">
+  <h5>Don't set a permalink</h5>
+  <p>
+    Setting a permalink in the front matter of your blog page will cause
+    pagination to break. Just omit the permalink.
+  </p>
+</div>
+
+<div class="note info">
+  <h5>Pagination for categories, tags and collections</h5>
+  <p>
+    The more recent <a href="https://github.com/sverrirs/jekyll-paginate-v2">
+    jekyll-paginate-v2</a> plugin supports more features. See the
+    <a href="https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples">
+    pagination examples</a> in the repository. <strong>This plugin is not
+    supported by GitHub Pages</strong>.
+  </p>
+</div>
 
 ## Liquid Attributes Available
 
@@ -53,22 +73,20 @@ attributes:
 
 {% include docs_variables_table.html scope=site.data.jekyll_variables.paginator %}
 
-## Tags and Categories
-
-Pagination pages through every post in the `posts`
-variable unless a post has `hidden: true` in its front matter.
-It does not currently allow paging over groups of posts linked
-by a common tag or category. It cannot include any collection of documents because it is restricted to posts.
-
-[jekyll-paginate-v2](https://github.com/sverrirs/jekyll-paginate-v2) is an unofficial successor of jekyll-paginate which supports more features.
+<div class="note info">
+  <h5>Pagination does not support tags or categories</h5>
+  <p>Pagination pages through every post in the <code>posts</code>
+  variable unless a post has <code>hidden: true</code> in its front matter.
+  It does not currently allow paging over groups of posts linked
+  by a common tag or category. It cannot include any collection of
+  documents because it is restricted to posts.</p>
+</div>
 
 ## Render the paginated Posts
 
 The next thing you need to do is to actually display your posts in a list using
 the `paginator` variable that will now be available to you. You’ll probably
-want to do this in one of the main pages of your site.
-
-Here’s one example of a
+want to do this in one of the main pages of your site. Here’s one example of a
 simple way of rendering paginated Posts in a HTML file:
 
 {% raw %}
@@ -110,19 +128,24 @@ title: My Blog
 ```
 {% endraw %}
 
+<div class="note warning">
+  <h5>Beware the page one edge-case</h5>
+  <p>
+    Jekyll does not generate a ‘page1’ folder, so the above code will not work
+    when a <code>/page1</code> link is produced. See below for a way to handle
+    this if it’s a problem for you.
+  </p>
+</div>
 
-Jekyll does not generate a `page1` folder, so the above code will not work
-when a `/page1` link is produced. See below for a way to handle
-this if it’s a problem for you:
+The following HTML snippet should handle page one, and render a list of each
+page with links to all but the current page.
 
 {% raw %}
 ```liquid
 {% if paginator.total_pages > 1 %}
 <div class="pagination">
   {% if paginator.previous_page %}
-    <a href="{{ paginator.previous_page_path | relative_url }}">
-      &laquo; Prev
-    </a>
+    <a href="{{ paginator.previous_page_path | relative_url }}">&laquo; Prev</a>
   {% else %}
     <span>&laquo; Prev</span>
   {% endif %}
@@ -131,20 +154,14 @@ this if it’s a problem for you:
     {% if page == paginator.page %}
       <em>{{ page }}</em>
     {% elsif page == 1 %}
-      <a href="{{ paginator.previous_page_path | relative_url }}">
-        {{ page }}
-      </a>
+      <a href="{{ paginator.previous_page_path | relative_url }}">{{ page }}</a>
     {% else %}
-      <a href="{{ site.paginate_path | relative_url | replace: ':num', page }}">
-        {{ page }}
-      </a>
+      <a href="{{ site.paginate_path | relative_url | replace: ':num', page }}">{{ page }}</a>
     {% endif %}
   {% endfor %}
 
   {% if paginator.next_page %}
-    <a href="{{ paginator.next_page_path | relative_url }}">
-      Next &raquo;
-    </a>
+    <a href="{{ paginator.next_page_path | relative_url }}">Next &raquo;</a>
   {% else %}
     <span>Next &raquo;</span>
   {% endif %}

docs/_docs/permalinks.md

@@ -14,7 +14,7 @@ The simplest way to set a permalink is using front matter. You set the
 
 For example, you might have a page on your site located at
 `/my_pages/about-me.html` and you want the output url to be `/about/`. In
-front matter the page you would set:
+front matter of the page you would set:
 
 ```
 ---
@@ -25,7 +25,7 @@ permalink: /about/
 ## Global
 
 Setting a permalink in front matter for every page on your site is no fun.
-Luckily, Jekyll let's you set in globally in your `_config.yml`.
+Luckily, Jekyll lets you set the permalink structure globally in your `_config.yml`.
 
 To set a global permalink, you use the `permalink` variable in `_config.yml`.
 You can use placeholders to your desired output. For example:
@@ -61,8 +61,19 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Year from the post's filename. May be overridden via the document’s
-          <code>date</code> front matter
+          Year from the post’s filename with four digits.
+          May be overridden via the document’s <code>date</code> front matter.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>short_year</code></p>
+      </td>
+      <td>
+        <p>
+          Year from the post’s filename without the century. (00..99)
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -72,8 +83,8 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Month from the post's filename. May be overridden via the document’s
-          <code>date</code> front matter
+          Month from the post’s filename. (01..12)
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -83,19 +94,36 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Month without leading zeros from the post's filename. May be
-          overridden via the document’s <code>date</code> front matter
+          Month without leading zeros from the post’s filename. May be
+          overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p><code>short_month</code></p>
+      </td>
+      <td>
+        <p>Three-letter month abbreviation, e.g. “Jan”.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>long_month</code></p>
+        <small>{% include docs_version_badge.html version="4.0" %}</small>
+      </td>
+      <td>
+        <p>Full month name, e.g. “January”.</p>
+      </td>
+    </tr>
     <tr>
       <td>
         <p><code>day</code></p>
       </td>
       <td>
         <p>
-          Day from the post's filename. May be overridden via the document’s
-          <code>date</code> front matter
+          Day of the month from the post’s filename. (01..31)
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -105,8 +133,8 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Day without leading zeros from the post's filename. May be overridden
-          via the document’s <code>date</code> front matter
+          Day of the month without leading zeros from the post’s filename.
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -115,18 +143,52 @@ Here's the full list of placeholders available:
         <p><code>y_day</code></p>
       </td>
       <td>
-        <p>Day of the year from the post's filename, with leading zeros.</p>
+        <p>Ordinal day of the year from the post’s filename, with leading zeros. (001..366)</p>
       </td>
     </tr>
     <tr>
       <td>
-        <p><code>short_year</code></p>
+        <p><code>w_year</code></p>
+        <small>{% include docs_version_badge.html version="4.0" %}</small>
       </td>
       <td>
-        <p>
-          Year without the century from the post's filename. May be overridden
-          via the document’s <code>date</code> front matter
-        </p>
+        <p>Week year which may differ from the month year for up to three days at the start of January and end of December</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>week</code></p>
+        <small>{% include docs_version_badge.html version="4.0" %}</small>
+      </td>
+      <td>
+        <p>Week number of the current year, starting with the first week having a majority of its days in January. (01..53)</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>w_day</code></p>
+        <small>{% include docs_version_badge.html version="4.0" %}</small>
+      </td>
+      <td>
+        <p>Day of the week, starting with Monday. (1..7)</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>short_day</code></p>
+        <small>{% include docs_version_badge.html version="4.0" %}</small>
+      </td>
+      <td>
+        <p>Three-letter weekday abbreviation, e.g. “Sun”.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>long_day</code></p>
+        <small>{% include docs_version_badge.html version="4.0" %}</small>
+      </td>
+      <td>
+        <p>Weekday name, e.g. “Sunday”.</p>
       </td>
     </tr>
     <tr>
@@ -135,7 +197,7 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Hour of the day, 24-hour clock, zero-padded from the post's
+          Hour of the day, 24-hour clock, zero-padded from the post’s
           <code>date</code> front matter. (00..23)
         </p>
       </td>
@@ -146,7 +208,7 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Minute of the hour from the post's <code>date</code> front matter. (00..59)
+          Minute of the hour from the post’s <code>date</code> front matter. (00..59)
         </p>
       </td>
     </tr>
@@ -156,7 +218,7 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Second of the minute from the post's <code>date</code> front matter. (00..59)
+          Second of the minute from the post’s <code>date</code> front matter. (00..59)
         </p>
       </td>
     </tr>
@@ -202,7 +264,7 @@ Here's the full list of placeholders available:
 
 ### Built-in formats
 
-For posts, Jekyll also provides the following built-in styles for convenience. Note, these aren't recognized when setting the permalink in front matter.
+For posts, Jekyll also provides the following built-in styles for convenience:
 
 <div class="mobile-side-scroller">
 <table>
@@ -237,6 +299,15 @@ For posts, Jekyll also provides the following built-in styles for convenience. N
         <p><code>/:categories/:year/:y_day/:title:output_ext</code></p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p><code>weekdate</code></p>
+        <small>{% include docs_version_badge.html version="4.0" %}</small>
+      </td>
+      <td>
+        <p><code>/:categories/:year/W:week/:short_day/:title:output_ext</code></p>
+      </td>
+    </tr>
     <tr>
       <td>
         <p><code>none</code></p>
@@ -249,6 +320,13 @@ For posts, Jekyll also provides the following built-in styles for convenience. N
 </table>
 </div>
 
+Rather than typing `permalink: /:categories/:year/:month/:day/:title/`, you can just type `permalink: pretty`.
+
+<div class="note info">
+<h5>Specifying permalinks through the front matter</h5>
+<p>Built-in permalink styles are not recognized in front matter. As a result, <code>permalink: pretty</code> will not work.</p>
+</div>
+
 ### Collections
 
 For collections, you have the option to override the global permalink in the

docs/_docs/plugins/commands.md

@@ -2,7 +2,7 @@
 title: Commands
 permalink: /docs/plugins/commands/
 ---
-Jekyll can be extended with plugins which provide
+As of version 2.5.0, Jekyll can be extended with plugins which provide
 subcommands for the `jekyll` executable. This is possible by including the
 relevant plugins in a `Gemfile` group called `:jekyll_plugins`:
 

docs/_docs/plugins/filters.md

@@ -19,9 +19,12 @@ end
 Liquid::Template.register_filter(Jekyll::AssetFilter)
 ```
 
-## Access the site object in Liquid
-
-Jekyll lets you access the `site` object through the
-`context.registers` feature of Liquid at `context.registers[:site]`. For example, you can
-access the global configuration file `_config.yml` using
-`context.registers[:site].config`.
+<div class="note">
+  <h5>ProTip™: Access the site object using Liquid</h5>
+  <p>
+    Jekyll lets you access the <code>site</code> object through the
+    <code>context.registers</code> feature of Liquid at <code>context.registers[:site]</code>. For example, you can
+    access the global configuration file <code>_config.yml</code> using
+    <code>context.registers[:site].config</code>.
+  </p>
+</div>

docs/_docs/plugins/generators.md

@@ -44,22 +44,6 @@ This is a more complex generator that generates new pages:
 
 ```ruby
 module Jekyll
-  class CategoryPage < Page
-    def initialize(site, base, dir, category)
-      @site = site
-      @base = base
-      @dir = dir
-      @name = 'index.html'
-
-      self.process(@name)
-      self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
-      self.data['category'] = category
-
-      category_title_prefix = site.config['category_title_prefix'] || 'Category: '
-      self.data['title'] = "#{category_title_prefix}#{category}"
-    end
-  end
-
   class CategoryPageGenerator < Generator
     safe true
 
@@ -72,6 +56,23 @@ module Jekyll
       end
     end
   end
+
+  # A Page subclass used in the `CategoryPageGenerator`
+  class CategoryPage < Page
+    def initialize(site, base, dir, category)
+      @site = site
+      @base = base
+      @dir  = dir
+      @name = 'index.html'
+
+      self.process(@name)
+      self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
+      self.data['category'] = category
+
+      category_title_prefix = site.config['category_title_prefix'] || 'Category: '
+      self.data['title'] = "#{category_title_prefix}#{category}"
+    end
+  end
 end
 ```
 

docs/_docs/plugins/installation.md

@@ -3,7 +3,7 @@ title: Plugins
 permalink: /docs/plugins/installation/
 ---
 
-There are three options for installing plugins:
+You have 3 options for installing plugins:
 
 1. In your site source root, make a `_plugins` directory. Place your plugins
    here. Any file ending in `*.rb` inside this directory will be loaded before
@@ -37,20 +37,34 @@ There are three options for installing plugins:
 
    Now you need to install all plugins from your Bundler group by running single command `bundle install`.
 
-## Plugins on GitHub Pages
+<div class="note info">
+  <h5>Plugins on GitHub Pages</h5>
+  <p>
+    <a href="https://pages.github.com/">GitHub Pages</a> is powered by Jekyll.
+    All Pages sites are generated using the <code>--safe</code> option
+    to disable plugins (with the exception of some
+    <a href="https://pages.github.com/versions">whitelisted plugins</a>) for
+    security reasons. Unfortunately, this means
+    your plugins won’t work if you’re deploying to GitHub Pages.<br><br>
+    You can still use GitHub Pages to publish your site, but you’ll need to
+    convert the site locally and push the generated static files to your GitHub
+    repository instead of the Jekyll source files.
+  </p>
+</div>
 
-[GitHub Pages](https://pages.github.com/) is powered by Jekyll.
-All Pages sites are generated using the `--safe` option
-to disable plugins (with the exception of some
-[whitelisted plugins](https://pages.github.com/versions)) for
-security reasons. Unfortunately, this means
-your plugins won’t work if you’re deploying to GitHub Pages.
+<div class="note info">
+  <h5>
+    <code>_plugins</code>, <code>_config.yml</code> and <code>Gemfile</code>
+    can be used simultaneously
+  </h5>
+  <p>
+    You may use any of the aforementioned plugin options simultaneously in the
+    same site if you so choose. Use of one does not restrict the use of the
+    others.
+  </p>
+</div>
 
-You can still use GitHub Pages to publish your site, but you’ll need to
-convert the site locally and push the generated static files to your GitHub
-repository instead of the Jekyll source files.
-
-## jekyll_plugins group
+### The jekyll_plugins group
 
 Jekyll gives this particular group of gems in your `Gemfile` a different
 treatment. Any gem included in this group is loaded before Jekyll starts
@@ -59,8 +73,10 @@ processing the rest of your source directory.
 A gem included here will be activated even if its not explicitly listed under
 the `plugins:` key in your site's config file.
 
-
-Gems included in the `:jekyll-plugins` group are activated
-regardless of the `--safe` mode setting. Be aware of what
-gems are included under this group!
-{: .warning }
+<div class="note warning">
+  <p>
+    Gems included in the <code>:jekyll-plugins</code> group are activated
+    regardless of the <code>--safe</code> mode setting. Be aware of what
+    gems are included under this group!
+  </p>
+</div>

docs/_docs/plugins/tags.md

@@ -70,3 +70,46 @@ And we would get something like this on the page:
 ```html
 <p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>
 ```
+
+## Tag Blocks
+
+The `render_time` tag seen above can also be rewritten as a tag block by 
+inheriting the `Liquid::Block` class. Look at the example below:
+
+```ruby
+module Jekyll
+  class RenderTimeTagBlock < Liquid::Block
+
+    def render(context)
+      text = super
+      "<p>#{text} #{Time.now}</p>"
+    end
+
+  end
+end
+
+Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTagBlock)
+```
+
+We can now use the tag block anywhere:
+
+{% raw %}
+```liquid
+{% render_time %}
+page rendered at:
+{% endrender_time %}
+```
+{% endraw %}
+
+And we would still get the same output as above on the page:
+
+```html
+<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>
+```
+
+<div class="note info">
+  <p>In the above example, the tag block and the tag are both registered with 
+  the name <code>render_time</code> but to register a tag and a tag block using 
+  the same name in the same project is not recommended as this may lead to 
+  conflicts.</p>
+</div>

docs/_docs/posts.md

@@ -140,7 +140,7 @@ tags: [hot, summer]
 ```
 
 Jekyll makes the categories available to us at `site.categories`. Iterating over
-`site.categories` on a page gives as another array with two items, the first
+`site.categories` on a page gives us another array with two items, the first
 item is the name of the category and the second item is an array of posts in that
 category.
 

docs/_docs/resources.md

@@ -1,60 +0,0 @@
----
-title: Resources
-permalink: /docs/resources/
----
-
-Jekyll's growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources.
-
-## Editors
-
-- [jekyll-atom](https://atom.io/packages/jekyll): A collection of snippets and tools for Jekyll in Atom
-- [markdown-writer](https://atom.io/packages/markdown-writer): An Atom package for Jekyll. It can create new posts/drafts, manage tags/categories, insert link/images and add many useful key mappings.
-- [sublime-jekyll](https://github.com/23maverick23/sublime-jekyll): A Sublime Text package for Jekyll static sites. This package should help creating Jekyll sites and posts easier by providing access to key template tags and filters, as well as common completions and a current date/datetime command (for dating posts). You can install this package manually via GitHub, or via [Package Control](https://packagecontrol.io/packages/Jekyll).
-- [vim-jekyll](https://github.com/parkr/vim-jekyll): A vim plugin to generate new posts and run `jekyll build` all without leaving vim.
-- [WordPress2Jekyll](https://wordpress.org/plugins/wp2jekyll/): A WordPress plugin that allows you to use WordPress as your editor and (automatically) export content in to Jekyll. WordPress2Jekyll attempts to marry these two systems together in order to make a site that can be easily managed from all devices.
-
-## Useful Guides
-
-- [CloudCannon Academy](https://learn.cloudcannon.com/) is a set of resources created by [CloudCannon](https://cloudcannon.com/) to help folks get up and running with Jekyll. They cover all skill levels, and even include some great video tutorials.
-- [Jekyll Cheatsheet](https://learn.cloudcannon.com/jekyll-cheat-sheet/) is a single-page resource for Jekyll filters, variables, and the like.
-- ["Creating and Hosting a Personal Site on GitHub"](http://jmcglone.com/guides/github-pages/)
-- ['Build A Blog With Jekyll And GitHub Pages' on Smashing Magazine](https://www.smashingmagazine.com/2014/08/01/build-blog-jekyll-github-pages/)
-- Publishing to GitHub Pages? [Check out our documentation page for just that purpose](/docs/github-pages/).
-- [Blogging with Git, Emacs and Jekyll](https://metajack.im/2009/01/23/blogging-with-git-emacs-and-jekyll/)
-- [Tips for working with GitHub Pages Integration](https://gist.github.com/jedschneider/2890453)
-
-## Integrations
-
-- Use a SaaS service as a backend for forms (contact forms, hiring forms, etc.)
-
-  - [Formspree (open source)](https://formspree.io/)
-  - [FormKeep](https://formkeep.com/guides/contact-form-jekyll?utm_source=github&utm_medium=jekyll-docs&utm_campaign=contact-form-jekyll)
-  - [Simple Form](https://getsimpleform.com/)
-  - [Formingo](https://www.formingo.co/guides/jekyll?utm_source=github&utm_medium=jekyll-docs&utm_campaign=Jekyll%20Documentation)
-  - [Formester](http://www.formester.com)
-  - [Talkyard](https://www.talkyard.io/blog-comments): Embedded comments for Jekyll and others (free and open source, or hosted serverless)
-  - [Staticman](https://staticman.net): Add user-generated content to a Jekyll site (free and open source)
-  - [Snipcart](https://snipcart.com/blog/static-site-e-commerce-part-2-integrating-snipcart-with-jekyll): Add a shopping cart to a Jekyll site
-  - [Contentful](https://www.contentful.com/ecosystem/jekyll/): use Jekyll together with the API-driven Contentful CMS.
-  - [Algolia](https://blog.algolia.com/instant-search-blog-documentation-jekyll-plugin/): Add a powerful instant search to your Jekyll site
-
-## Other commentary
-
-- [How I'm using Jekyll in 2016](https://mademistakes.com/articles/using-jekyll-2016/)
-
-- [Talkyard comments instructions for Jekyll](https://jekyll-demo.talkyard.io/2018/01/09/installation-instructions.html)
-
-- [Static Comments with Jekyll & Staticman](https://mademistakes.com/articles/improving-jekyll-static-comments/)
-
-- [Adding Ajax pagination to Jekyll](https://eduardoboucas.com/blog/2014/11/05/adding-ajax-pagination-to-jekyll.html)
-
-- ['My Jekyll Fork', by Mike West](https://mikewest.org/2009/11/my-jekyll-fork)
-
-  > "Jekyll is a well-architected throwback to a time before WordPress, when men were men, and HTML was static. I like the ideas it espouses, and have made a few improvements to it's core. Here, I'll point out some highlights of my fork in the hopes that they see usage beyond this site."
-
-- ['About this Website', by Carter Allen](http://cartera.me/2010/08/12/about-this-website/)
-
-  > "Jekyll is everything that I ever wanted in a blogging engine. Really. It isn't perfect, but what's excellent about it is that if there's something wrong, I know exactly how it works and how to fix it. It runs on the your machine only, and is essentially an added"build" step between you and the browser. I coded this entire site in TextMate using standard HTML5 and CSS3, and then at the end I added just a few little variables to the markup. Presto-chango, my site is built and I am at peace with the world."
-
-- A way to [extend Jekyll](https://github.com/rfelix/jekyll_ext) without forking and modifying the Jekyll gem codebase and some [portable Jekyll extensions](https://wiki.github.com/rfelix/jekyll_ext/extensions) that can be reused and shared.
-- [Using your Rails layouts in Jekyll](http://numbers.brighterplanet.com/2010/08/09/sharing-rails-views-with-jekyll)

docs/_docs/ruby-101.md

@@ -12,7 +12,7 @@ A gem is code you can include in Ruby projects. It allows you to package up func
 
 * Converting a Ruby object to JSON
 * Pagination
-* Interacting with APIs such as Github
+* Interacting with APIs such as GitHub
 * Jekyll itself is a gem as well as many Jekyll plugins including
 [jekyll-feed](https://github.com/jekyll/jekyll-feed),
 [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) and
@@ -24,13 +24,13 @@ A gem is code you can include in Ruby projects. It allows you to package up func
 A `Gemfile` is a list of gems required for your site. For a simple Jekyll site it might look something like this:
 
 ```ruby
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
-gem 'jekyll'
+gem "jekyll"
 
 group :jekyll_plugins do
-  gem 'jekyll-feed'
-  gem 'jekyll-seo-tag'
+  gem "jekyll-feed"
+  gem "jekyll-seo-tag"
 end
 ```
 

docs/_docs/step-by-step/01-setup.md

@@ -22,6 +22,23 @@ terminal:
 gem install jekyll bundler
 ```
 
+To create a new `Gemfile` to list your project's dependencies run:
+
+```
+bundle init
+```
+
+Now edit the `Gemfile`and add jekyll as a dependency:
+
+```
+gem "jekyll"
+```
+
+Finally run `bundle` to install jekyll for your project.
+
+You can now prefix all jekyll commands listed in this tutorial with `bundle exec` 
+to make sure you use the jekyll version defined in your `Gemfile`.
+
 ## Create a site
 
 It's time to create a site! Create a new directory for your site, you can name
@@ -54,7 +71,7 @@ content:
 ## Build
 
 Jekyll is a static site generator so we need Jekyll to build the site
-before we can view it. There's two commands you can run in the root of your site
+before we can view it. There are two commands you can run in the root of your site
 to build it:
 
 * `jekyll build` - Builds the site and outputs a static site to a directory

docs/_docs/step-by-step/02-liquid.md

@@ -16,7 +16,7 @@ braces: {% raw %}`{{`{% endraw %} and {% raw %}`}}`{% endraw %}. For example:
 {% raw %}
 ```liquid
 {{ page.title }}
-```  
+```
 {% endraw %}
 
 Outputs a variable called `page.title` on the page.
@@ -34,7 +34,7 @@ braces and percent signs: {% raw %}`{%`{% endraw %} and
     sidebar content
   </div>
 {% endif %}
-```  
+```
 {% endraw %}
 
 Outputs the sidebar if `page.show_sidebar` is true. You can learn more about the
@@ -48,7 +48,7 @@ and are separated by a `|`. For example:
 {% raw %}
 ```liquid
 {{ "hi" | capitalize }}
-```  
+```
 {% endraw %}
 
 Outputs `Hi`. You can learn more about the filters available to Jekyll
@@ -63,12 +63,22 @@ Now it's your turn, change the Hello World! on your page to output as lowercase:
 ...
 <h1>{{ "Hello World!" | downcase }}</h1>
 ...
-```  
+```
 {% endraw %}
 
-It may not seem like it now, but much of Jekyll's power comes from combining
-Liquid with other features. 
+To get our changes processed by Jekyll we need to add [front matter](../03-front-matter/) to the top of the page:
 
-In order to see the changes from `downcase` Liquid filter, we will need to add front matter. 
+```markdown
+---
+# front matter tells Jekyll to process Liquid
+---
+```
+
+Our "Hello World!" will now be downcased on render.
+
+It may not seem like it now, but much of Jekyll's power comes from combining
+Liquid with other features.
+
+In order to see the changes from `downcase` Liquid filter, we will need to add front matter.
 
 That's next. Let's keep going.

docs/_docs/step-by-step/04-layouts.md

@@ -43,7 +43,7 @@ Create your first layout at `_layouts/default.html` with the following content:
 You'll notice this is almost identical to `index.html` except there's
 no front matter and the content of the page is replaced with a `content`
 variable. `content` is a special variable which has the value of the rendered
-content of the page its called on.
+content of the page it's called on.
 
 To have `index.html` use this layout, you can set a `layout` variable in front
 matter. The layout wraps around the content of the page so all you need in

docs/_docs/step-by-step/05-includes.md

@@ -3,7 +3,7 @@ layout: step
 title: Includes
 position: 5
 ---
-The site is coming together however, there's no way to navigate between
+The site is coming together; however, there's no way to navigate between
 pages. Let's fix that.
 
 Navigation should be on every page so adding it to your layout is the correct

docs/_docs/step-by-step/07-assets.md

@@ -36,8 +36,7 @@ You could use a standard CSS file for styling, we're going to take it a step
 further by using [Sass](https://sass-lang.com/). Sass is a fantastic extension
 to CSS baked right into Jekyll.
 
-First create a Sass file at `/assets/css/styles.scss` with the following
-content:
+First create a Sass file at `/assets/css/styles.scss` with the following content:
 
 {% raw %}
 ```css
@@ -49,12 +48,12 @@ content:
 
 The empty front matter at the top tells Jekyll it needs to process the file. The
 `@import "main"` tells Sass to look for a file called `main.scss` in the sass
-directory (`_sass/` by default).
+directory (`_sass/` by default which is directly under root folder of your website).
 
 At this stage you'll just have a main css file. For larger projects, this is a
 great way to keep your CSS organized.
 
-Create `_sass/main.scss` with the following content:
+Create a Sass file at `/_sass/main.scss` with the following content:
 
 ```sass
 .current {

docs/_docs/step-by-step/09-collections.md

@@ -21,6 +21,8 @@ collections:
   authors:
 ```
 
+To (re)load the configuration, restart the jekyll server. Press `Ctrl`+`C` in your terminal to stop the server, and then `jekyll serve` to restart it.
+
 ## Add authors
 
 Documents (the items in a collection) live in a folder in the root of the site

docs/_docs/step-by-step/10-deployment.md

@@ -63,6 +63,15 @@ group :jekyll_plugins do
 end
 ```
 
+Then add these lines to your `_config.yml`:
+
+```
+plugins:
+  - jekyll-feed
+  - jekyll-sitemap
+  - jekyll-seo-tag
+```
+
 Now install them by running a `bundle update`.
 
 `jekyll-sitemap` doesn't need any setup, it will create your sitemap on build.

docs/_docs/structure.md

@@ -29,9 +29,16 @@ A basic Jekyll site usually looks something like this:
 └── index.html # can also be an 'index.md' with valid front matter
 ```
 
-`jekyll new` uses [gem-based themes](/docs/themes/) to define the look of the site. This results in a lighter default directory structure: `_layouts`, `_includes` and `_sass` are stored in the theme-gem, by default.
-
-[minima](https://github.com/jekyll/minima) is the current default theme, and `bundle show minima` will show you where minima theme's files are stored on your computer.
+<div class="note info">
+  <h5>Directory structure of Jekyll sites using gem-based themes</h5>
+  <p>
+    Starting <strong>Jekyll 3.2</strong>, a new Jekyll project bootstrapped with <code>jekyll new</code> uses <a href="/docs/themes/">gem-based themes</a> to define the look of the site. This results in a lighter default directory structure : <code>_layouts</code>, <code>_includes</code> and <code>_sass</code> are stored in the theme-gem, by default.
+  </p>
+  <br />
+  <p>
+     <a href="https://github.com/jekyll/minima">minima</a> is the current default theme, and <code>bundle show minima</code> will show you where minima theme's files are stored on your computer.
+  </p>
+</div>
 
 An overview of what each of these does:
 

docs/_docs/themes.md

@@ -43,15 +43,23 @@ To locate a theme's files on your computer:
 
 1. Run `bundle show` followed by the name of the theme's gem, e.g., `bundle show minima` for Jekyll's default theme.
 
-   This returns the location of the gem-based theme files. For example, the Minima theme's files might be located in `/usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0` on macOS.
+   This returns the location of the gem-based theme files. For example, the Minima theme's files might be located in `/usr/local/lib/ruby/gems/2.6.0/gems/minima-2.5.1` on macOS.
 
 2. Open the theme's directory in Finder or Explorer:
 
    ```sh
    # On MacOS
    open $(bundle show minima)
+
    # On Windows
-   explorer /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0
+   # First get the gem's installation path:
+   #
+   #   bundle show minima
+   #   => C:/Ruby26-x64/lib/ruby/gems/{{ site.data.ruby.current_version }}/gems/minima-2.5.1
+   #
+   # then invoke explorer with above path, substituting `/` with `\`
+   explorer C:\Ruby26-x64\lib\ruby\gems\{{ site.data.ruby.current_version}}\gems\minima-2.5.1
+
    # On Linux
    xdg-open $(bundle show minima)
    ```
@@ -113,8 +121,8 @@ To do this, copy the files from the theme gem's directory into your Jekyll site
 Then you must tell Jekyll about the plugins that were referenced by the theme. You can find these plugins in the theme's gemspec file as runtime dependencies. If you were converting the Minima theme, for example, you might see:
 
 ```
-spec.add_runtime_dependency "jekyll-feed", "~> 0.9"
-spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.1"
+spec.add_runtime_dependency "jekyll-feed", "~> 0.12"
+spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.6"
 ```
 
 You should include these references in the `Gemfile` in one of two ways.
@@ -124,8 +132,8 @@ You could list them individually in both `Gemfile` and `_config.yml`.
 ```ruby
 # ./Gemfile
 
-gem "jekyll-feed", "~> 0.9"
-gem "jekyll-seo-tag", "~> 2.1"
+gem "jekyll-feed", "~> 0.12"
+gem "jekyll-seo-tag", "~> 2.6"
 ```
 
 ```yaml
@@ -142,8 +150,8 @@ Or you could list them explicitly as Jekyll plugins in your Gemfile, and not upd
 # ./Gemfile
 
 group :jekyll_plugins do
-  gem "jekyll-feed", "~> 0.9"
-  gem "jekyll-seo-tag", "~> 2.1"
+  gem "jekyll-feed", "~> 0.12"
+  gem "jekyll-seo-tag", "~> 2.6"
 end
 ```
 
@@ -153,7 +161,7 @@ If you're publishing on GitHub Pages you should update only your `_config.yml` a
 
 Finally, remove references to the theme gem in `Gemfile` and configuration. For example, to remove `minima`:
 
-- Open `Gemfile` and remove `gem "minima", "~> 2.0"`.
+- Open `Gemfile` and remove `gem "minima", "~> 2.5"`.
 - Open `_config.yml` and remove `theme: minima`.
 
 Now `bundle update` will no longer get updates for the theme gem.
@@ -179,7 +187,7 @@ To install a gem-based theme:
    ```diff
    # ./Gemfile
 
-   - gem "minima", "~> 2.0"
+   - gem "minima", "~> 2.5"
    + gem "jekyll-theme-minimal"
    ```
 
@@ -274,10 +282,7 @@ Jekyll will automatically require all whitelisted `runtime_dependencies` of your
 
 With this, the end-user need not keep track of the plugins required to be included in their config file for their theme-gem to work as intended.
 
-{% if site.version == '4.0.0' %}
-{% comment %} Remove this encapsulation when `v4.0` ships {% endcomment %}
-
-### Pre-configuring Theme-gems {%- include docs_version_badge.html version="4.0.0" -%}
+### Pre-configuring Theme-gems {%- include docs_version_badge.html version="4.0" -%}
 
 Jekyll will read-in a `_config.yml` at the root of the theme-gem and merge its data into the site's existing configuration data.
 
@@ -290,7 +295,6 @@ But unlike other entities loaded from within the theme, loading the config file
 While this feature is to enable easier adoption of a theme, the restrictions ensure that a theme-config cannot affect the build in a concerning manner. Any plugins required by the theme will have to be listed manually by the user or provided by the theme's `gemspec` file.
 
 This feature will let the theme-gem to work with *theme-specific config variables* out-of-the-box.
-{% endif %}
 
 ### Documenting your theme
 

docs/_docs/troubleshooting.md

@@ -21,7 +21,7 @@ the header files for compiling extension modules for Ruby 2.x This
 can be done on Ubuntu or Debian by running:
 
 ```sh
-sudo apt-get install ruby2.3-dev
+sudo apt-get install ruby2.6-dev
 ```
 
 On Red Hat, CentOS, and Fedora systems you can do this by running:
@@ -138,10 +138,10 @@ jekyll new test
 
 Running bundle install in /home/user/test...
 
-Your user account isn't allowed to install to the system RubyGems.
+Your user account is not allowed to install to the system RubyGems.
 You can cancel this installation and run:
 
-      bundle install --path vendor/bundle
+    bundle install --path vendor/bundle
 
 to install the gems into ./vendor/bundle/, or you can enter your password
 and install the bundled gems to RubyGems using sudo.

docs/_docs/upgrading.md

@@ -10,11 +10,16 @@ guides to aid your upgrade:
 
 - [From 0.x to 1.x and 2.x](/docs/upgrading/0-to-2/)
 - [From 2.x to 3.x](/docs/upgrading/2-to-3/)
+- [From 3.x to 4.x](/docs/upgrading/3-to-4/)
 
 ## Minor updates
 
-We recommend you update Jekyll as often as possible to benefit from
-the latest bug fixes.
+<div class="note">
+  <h5>Stay Up to Date</h5>
+  <p>We recommend you update Jekyll as often as possible to benefit from
+  the latest bug fixes.
+  </p>
+</div>
 
 If you followed our setup recommendations and installed [Bundler](http://bundler.io/), run `bundle update jekyll` or simply `bundle update` and all your gems will
 update to the latest versions.

docs/_docs/upgrading/3-to-4.md

@@ -3,33 +3,57 @@ title: Upgrading from 3.x to 4.x
 permalink: /docs/upgrading/3-to-4/
 ---
 
-Upgrading from an older version of Jekyll? A few things have changed in Jekyll 4
-that you'll want to know about.
+A few things have changed in Jekyll 4.
 
-Before we dive in, you need to have at least Ruby 2.3.0 installed. Run the following
-in your terminal to check
+Before we dive in, you need to have at least Ruby {{ site.data.ruby.min_version }}
+installed.
+
+Run the following in your terminal to check
 
 ```sh
 ruby -v
+{{ site.data.ruby.current_version_output }}
 ```
 
-If you're using Ruby >= 2.3.0, go ahead and fetch the latest version of Jekyll:
+If you're using a supported Ruby version > {{ site.data.ruby.min_version }}, go ahead
+and fetch the latest version of Jekyll:
 
 ```sh
 gem update jekyll
 ```
 
+<div class="note warning">
+  <h5><code>post_url</code> Tag and Baseurl</h5>
+  <p>&nbsp;</p>
+  <p>
+    The <code>post_url</code> tag now incorporates the <code>relative_url</code> filter within itself
+    and therefore automatically prepends your site's <code>baseurl</code> to the post's <code>url</code>
+    value.
+  </p>
+  <p>
+    Please ensure that you change all instances of the <code>post_url</code> usage as following:
+  </p>
 
-### Template rendering
+{% highlight diff %}
+{% raw %}
+- {{ site.baseurl }}/{% post_url 2018-03-20-hello-world.markdown %}
++ {% post_url 2018-03-20-hello-world.markdown %}
+{% endraw %}
+{% endhighlight %}
+</div>
 
-We've slightly altered the way Jekyll parses and renders your various templates to improve
-the overall build times. Jekyll now parses a template once, caches it internally and then
-renders the parsed template multiple times as required by your pages and documents.
 
-The downside to this is that some of the community-authored plugins may not work as they
-previously used to.
+## Template rendering
 
-#### For Plugin-authors
+We've slightly altered the way Jekyll parses and renders your various templates
+to improve the overall build times. Jekyll now parses a template once, caches it
+internally and then renders the parsed template multiple times as required by
+your pages and documents.
+
+The downside to this is that some of the community-authored plugins may not work
+as they previously used to.
+
+## For plugin authors
 
 * If your plugin depends on the following code: `site.liquid_renderer.file(path).parse(content)`,
 note that the return value (`template`, an instance of *`Liquid::Template`*), from that line will
@@ -40,12 +64,105 @@ You'll therefore have to ensure that *`payload`* is not memoized or cached in yo
 * If its a requirement that `template` you get from the above step *be different* at all times,
 you can invoke *`Liquid::Template`* directly:
 
-
   ```diff
   - template = site.liquid_renderer.file(path).parse(content)
   + template = Liquid::Template.parse(content)
   ```
 
----
+## Exclusion changes
 
-*Did we miss something? Please click "Improve this page" above and add a section. Thanks!*
+We've enhanced our default exclusion array.
+It now looks like the following:
+
+```yaml
+# default excludes
+exclude:
+- .sass-cache/
+- .jekyll-cache/
+- gemfiles/
+- Gemfile
+- Gemfile.lock
+- node_modules/
+- vendor/bundle/
+- vendor/cache/
+- vendor/gems/
+- vendor/ruby/
+```
+
+What's new is that this array **does not get overridden by the `exclude` array
+in the user's config file anymore**. The user's exclude entries simply get
+**added** to the above default array (if the entry isn't already excluded).
+
+To forcibly "process" directories or files that have been excluded, list them
+in the `include` array instead:
+
+```yaml
+# overrides your excluded items configuration and the default include array ([".htaccess"])
+include:
+  - .htaccess
+  - node_modules/uglifier/index.js
+```
+
+The above configuration directs Jekyll to handle only
+`node_modules/uglifier/index.js` while ignoring every other file in the
+`node_modules` directory since that directory is "excluded" by default.
+
+Note that the default `include` array still gets overridden by the `include`
+array in your config file. So, be sure to add `.htaccess` to the list if you
+need that file to be present in the generated site.
+
+## Kramdown v2
+
+Jekyll has dropped support for `kramdown-1.x` entirely.
+
+From [`v2.0` onwards](https://kramdown.gettalong.org/news.html#kramdown-200-released)
+kramdown requires specific extensions to be additionally installed to use
+certain features are desired outside of kramdown's core functionality.
+
+Out of all the extensions listed in the report linked above, gem
+`kramdown-parser-gfm` is automatically installed along with Jekyll 4.0. The
+remaining extensions will have to be manually installed by the user depending on
+desired funtionality, by listing the extension's gem-name in their `Gemfile`.
+
+Notes:
+  * `kramdown-converter-pdf` will be ignored by Jekyll Core. To have Jekyll convert Markdown to PDF
+    you'll have to depend on a plugin that subclasses `Jekyll::Converter` with the
+    [required methods]({% link _docs/plugins/converters.md %}).
+
+    For example:
+
+    ```ruby
+    module Jekyll
+      External.require_with_graceful_fail "kramdown-converter-pdf"
+
+      class Markdown2PDF < Converter
+        safe true
+        priority :low
+
+        def matches(ext)
+          # match only files that have an extension exactly ".markdown"
+          ext =~ /^\.markdown$/
+        end
+
+        def convert(content)
+          Kramdown::Document.new(content).to_pdf
+        end
+
+        def output_ext
+          ".pdf"
+        end
+      end
+    end
+    ```
+  * Vendors that provide a versioned Jekyll Environment Image (e.g. Docker Image, GitHub Pages, etc)
+    will have to manually whitelist kramdown's extension gems in their distributions for Jekyll 4.0.
+
+## Deprecated Configuration Options
+
+Jekyll 4.0 has dropped support for all legacy configuration options that were deprecated over multiple
+releases in the previous series.
+
+To that end, we shall no longer output a deprecation warning when we encounter a legacy config key nor
+shall we gracefully assign their values to the newer counterparts. Depending on the key, it shall either
+be ignored or raise an `InvalidConfigurationError` error if the key is still valid but the associated
+value is not of the valid type.

docs/_docs/usage.md

@@ -12,9 +12,9 @@ You can use this command in a number of ways:
 * `jekyll build` or `jekyll b` - Performs a one off build your site to `./_site` (by default)
 * `jekyll serve` or `jekyll s` - Builds your site any time a source file changes and serves it locally
 * `jekyll doctor` - Outputs any deprecation or configuration issues
-* `jekyll new-theme` - Creates a new Jekyll theme scaffold
-* `jekyll clean` - Removes the generated site and metadata file
+* `jekyll clean` - Removes all generated files: destination folder, metadata file, Sass and Jekyll caches.
 * `jekyll help` - Shows help, optionally for a given subcommand, e.g. `jekyll help build`
+* `jekyll new-theme` - Creates a new Jekyll theme scaffold
 
 Typically you'll use `jekyll serve` while developing locally and `jekyll build` when you need to generate the site for production.
 

docs/_includes/anchor_links.html

@@ -3,22 +3,25 @@
     var anchor = document.createElement("a");
     anchor.className = "header-link";
     anchor.href      = "#" + id;
-    anchor.innerHTML = "#";
+    anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
     anchor.title = "Permalink";
     return anchor;
   };
+
   var linkifyAnchors = function (level, containingElement) {
     var headers = containingElement.getElementsByTagName("h" + level);
     for (var h = 0; h < headers.length; h++) {
       var header = headers[h];
+
       if (typeof header.id !== "undefined" && header.id !== "") {
         header.appendChild(anchorForId(header.id));
       }
     }
   };
+
   document.onreadystatechange = function () {
     if (this.readyState === "complete") {
-      var contentBlock = document.getElementsByClassName("content")[0];
+      var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
       if (!contentBlock) {
         return;
       }

docs/_includes/docs_contents.html

@@ -0,0 +1,17 @@
+<div class="unit one-fifth hide-on-mobiles">
+  <aside>
+    {% for section in site.data.docs_nav %}
+      <h4>{{ section.title }}</h4>
+      <ul>
+        {% for item in section.docs %}
+          {% assign p = site.documents | where: "url", item.link | first %}
+          <li {%- if page.url == p.url %} class="current" {%- endif %}>
+            <a href="{{ p.url }}">
+              {{ p.menu_name | default: p.title }}
+            </a>
+          </li>
+        {% endfor %}
+      </ul>
+    {% endfor %}
+  </aside>
+</div>

docs/_includes/docs_contents_mobile.html

@@ -0,0 +1,15 @@
+<div class="docs-nav-mobile unit whole show-on-mobiles">
+  <select onchange="if (this.value) window.location.href=this.value">
+    <option value="">Navigate the docs…</option>
+    {% for section in site.data.docs_nav %}
+    <optgroup label="{{ section.title }}">
+      {% for item in section.docs %}
+        {% assign p = site.documents | where: "url", item.link | first %}
+        <option value="{{ p.url }}">
+          {{ p.menu_name | default: p.title }}
+        </option>
+      {% endfor %}
+    </optgroup>
+    {% endfor %}
+  </select>
+</div>

docs/_includes/footer.html

@@ -1,31 +1,23 @@
 <footer>
-  <div class="container columns">
-    <div class="column copy-text">
+  <div class="grid">
+    <div class="unit one-third center-on-mobiles">
       <p>Jekyll is lovingly maintained by the <a href="/team/">core team</a> of volunteers. </p>
-      <p>The contents of this website are <br>
-        &copy; {{ site.time | date: '%Y' }} under the terms of the <a href="{{ site.repository }}/blob/master/LICENSE">MIT License</a>.</p>
+      <p>The contents of this website are <br />&copy;&nbsp;{{ site.time | date: '%Y' }} under the terms of the <a href="{{ site.repository }}/blob/master/LICENSE">MIT&nbsp;License</a>.</p>
     </div>
-    <div class="column sponsors">
+    <div class="unit two-thirds align-right center-on-mobiles">
       <p>
         Proudly hosted by
         <a href="https://github.com">
-          <img src="/img/github.svg" width="100" alt="GitHub">
+          <img src="/img/footer-logo.png" width="100" height="30" alt="GitHub • Social coding">
         </a>
       </p>
-      <p>
-        Get professional Jekyll support and more with
-        <a href="https://tidelift.com/subscription/pkg/rubygems-jekyll?utm_source=rubygems-jekyll&utm_medium=referral&utm_campaign=readme">
-        <img src="/img/tidelift-logo.png" width="100" height="30" alt="Tidelift">
-      </p>
     </div>
     <div class="unit two-thirds align-right center-on-mobiles">
       <p>
-        Sponsored by
-        {% for sponsor in site.data.sponsors %}
-          <a href="{{ sponsor.url }}">
-            <img src="{{ sponsor.image }}" alt="{{ sponsor.name }}">
-          </a>
-        {% endfor %}
+        Jekyll is funded thanks to its
+        <a href="https://github.com/jekyll/jekyll#sponsors">
+          sponsors!
+        </a>
       </p>
     </div>
   </div>

docs/_includes/mobile-nav-items.html

@@ -0,0 +1,18 @@
+<ul>
+  {% for p in site.data.primary_nav %}
+    {%- if p.show_on_mobile %}
+    <li
+      {%- if p.link == '/' -%}
+        {% if page.url == '/' %} class="current" {%- endif %}
+      {%- else -%}
+        {% if page.url contains p.link %} class="current" {%- endif %}
+      {%- endif -%}
+    >
+      <a href="{{ p.link }}">{{ p.title }}</a>
+    </li>
+    {%- endif %}
+  {% endfor %}
+  <li>
+    <a href="{{ site.repository }}">GitHub</a>
+  </li>
+</ul>

docs/_includes/navigation/main.html

@@ -1,12 +0,0 @@
-<nav class="main-nav">
-  {% for p in site.data.primary_nav %}
-    <a href="{{ p.link }}" class="
-      {% if p.link == '/' %}
-        {% if page.url == '/' %}current{% endif %}
-      {% else %}
-        {% if page.url contains p.link %}current{% endif %}
-      {% endif %}">
-      {{ p.title }}
-    </a>
-  {% endfor %}
-</nav>

docs/_includes/navigation/sub-mobile.html

@@ -1,19 +0,0 @@
-<div class="sub-mobile-nav">
-  <select onchange="if (this.value) window.location.href=this.value">
-    <option value="">Navigate the {{ include.source.first.collection }}...</option>
-    {% for section in include.sections %}
-    <optgroup label="{{ section.title }}">
-      {% for item in section.items %}
-        {% assign p = include.source | where: "url", item.link | first %}
-        <option value="{{ p.url }}">
-          {% if p.menu_name %}
-            {{ p.menu_name }}
-          {% else %}
-            {{ p.title }}
-          {% endif %}
-        </option>
-      {% endfor %}
-    </optgroup>
-    {% endfor %}
-  </select>
-</div>

docs/_includes/navigation/sub.html

@@ -1,23 +0,0 @@
-<nav class="sub-nav page-pad">
-  {% for section in include.sections %}
-    <h4>{{ section.title }}</h4>
-    <ul>
-      {% for item in section.items %}
-        {% assign p = include.source | where: "url", item.link | first %}
-        <li>
-          <a href="{{ p.url }}" class="{% if p.url == include.home %}
-            {% if page.url == include.home %}current{% endif %}
-          {% else %}
-            {% if page.url contains p.url %}current{% endif %}
-          {% endif %}">
-            {% if p.menu_name %}
-              {{ p.menu_name }}
-            {% else %}
-              {{ p.title }}
-            {% endif %}
-          </a>
-        </li>
-      {% endfor %}
-    </ul>
-  {% endfor %}
-</nav>

docs/_includes/news_contents.html

@@ -0,0 +1,33 @@
+<div class="unit one-fifth hide-on-mobiles">
+  <aside>
+    <ul>
+      <li {%- if page.title == 'News' %} class="current" {%- endif %}>
+        <a href="/news/">All News</a>
+      </li>
+      <li {%- if page.title == 'Releases' %} class="current" {%- endif %}>
+        <a href="/news/releases/">Jekyll Releases</a>
+      </li>
+    </ul>
+    <h4>Recent Releases</h4>
+    <ul>
+      {% for post in site.categories.release limit:5 %}
+      <li {%- if page.title == post.title %} class="current" {%- endif %}>
+        <a href="{{ post.url }}">Version {{ post.version }}</a>
+      </li>
+      {% endfor %}
+      <li>
+        <a href="/docs/history/">History »</a>
+      </li>
+    </ul>
+    <h4>Other News</h4>
+    <ul>
+      {% for post in site.posts %}
+        {% unless post.categories contains 'release' %}
+        <li {%- if page.title == post.title %} class="current" {%- endif %}>
+          <a href="{{ post.url }}">{{ post.title }}</a>
+        </li>
+        {% endunless %}
+      {% endfor %}
+    </ul>
+  </aside>
+</div>

docs/_includes/news_contents_mobile.html

@@ -0,0 +1,11 @@
+<div class="docs-nav-mobile unit whole show-on-mobiles">
+  <select onchange="if (this.value) window.location.href=this.value">
+    <option value="">Navigate the blog…</option>
+    <option value="/news/">Home</option>
+    <optgroup label="posts">
+      {% for post in site.posts %}
+      <option value="{{ post.url }}">{{ post.title }}</option>
+      {% endfor %}
+    </optgroup>
+  </select>
+</div>

docs/_includes/news_item.html

@@ -0,0 +1,25 @@
+<article>
+  <h2>
+    <a href="{{ post.url }}">
+      {{ post.title }}
+    </a>
+  </h2>
+  <span class="post-category">
+    <span class="label">
+      {{ post.categories | array_to_sentence_string }}
+    </span>
+  </span>
+  <div class="post-meta">
+    <span class="post-date">
+      {{ post.date | date_to_string }}
+    </span>
+    {% assign author = post.author %}
+    <a href="https://github.com/{{ author }}" class="post-author">
+      {% avatar user=author size=24 %}
+      {{ author }}
+    </a>
+  </div>
+  <div class="post-content">
+    {{ post.content }}
+  </div>
+</article>

docs/_includes/post.html

@@ -1,24 +0,0 @@
-<article class="post page">
-	<div class="page-pad">
-		<h2><a href="{{ include.post.url }}">{{ include.post.title }}</a></h2>
-
-		<div class="post-meta">
-			<span class="post-category">
-				{{ include.post.categories | array_to_sentence_string | capitalize }}
-			</span>
-			&middot;
-			<span class="post-date">
-				{{ include.post.date | date: '%e %b %Y' }}
-			</span>
-			&middot;
-			{% assign author = include.post.author %}
-			<a href="https://github.com/{{ author }}" class="post-author">
-				{% avatar user=author size=24 %}
-				{{ author }}
-			</a>
-		</div>
-		<div class="post-content">
-			{{ include.post.content }}
-		</div>
-	</div>
-</article>

docs/_includes/primary-nav-items.html

@@ -1,11 +1,12 @@
 <ul>
   {% for p in site.data.primary_nav %}
-  <li class="
-    {% if p.link == '/' %}
-      {% if page.url == '/' %}current{% endif %}
-    {% else %}
-      {% if page.url contains p.link %}current{% endif %}
-    {% endif %}">
+  <li
+    {%- if p.link == '/' -%}
+      {% if page.url == p.link %} class="current" {%- endif %}
+    {%- else -%}
+      {% if page.url contains p.link %} class="current" {%- endif %}
+    {%- endif -%}
+  >
     <a href="{{ p.link }}">{{ p.title }}</a>
   </li>
   {% endfor %}

docs/_includes/section_nav_tutorials.html

@@ -0,0 +1,39 @@
+{% comment %}
+Map grabs the tutorials sections, giving us an array of arrays. Join, flattens all
+the items to a comma delimited string. Split turns it into an array again.
+{% endcomment %}
+{% assign tutorials = site.data.tutorials | map: 'tutorials' | join: ',' | split: ',' %}
+
+{% comment %}
+Because this is built for every page, lets find where we are in the ordered
+document list by comparing url strings. Then if there's something previous or
+next, lets build a link to it.
+{% endcomment %}
+
+{% for tutorial in tutorials %}
+  {% assign tutorial_url = tutorial | prepend:"/tutorials/" | append:"/" %}
+  {% if tutorial_url == page.url %}
+    <div class="section-nav">
+      <div class="left align-right">
+          {% if forloop.first %}
+            <span class="prev disabled">Back</span>
+          {% else %}
+            {% assign previous = forloop.index0 | minus: 1 %}
+            {% assign previous_page = tutorials[previous] | prepend:"/tutorials/" | append:"/" %}
+            <a href="{{ previous_page }}" class="prev">Back</a>
+          {% endif %}
+      </div>
+      <div class="right align-left">
+          {% if forloop.last %}
+            <span class="next disabled">Next</span>
+          {% else %}
+            {% assign next = forloop.index0 | plus: 1 %}
+            {% assign next_page = tutorials[next] | prepend:"/tutorials/" | append:"/" %}
+            <a href="{{ next_page }}" class="next">Next</a>
+          {% endif %}
+      </div>
+    </div>
+    <div class="clear"></div>
+    {% break %}
+  {% endif %}
+{% endfor %}

docs/_includes/step-index.html

@@ -1,22 +1,58 @@
-
-
 {% assign docs = site.docs | where_exp: "doc", "doc.url contains '/step-by-step/'" %}
 
-<div class="section-nav">
-  {% for doc in docs %}
-    {% if doc.url == page.url %}
-      {% unless forloop.first %}
-        {% assign previous = forloop.index0 | minus: 1 %}
-        <a href="{{ docs[previous].url }}" class="btn">Back</a>
-      {% endunless %}
-      {% unless forloop.last %}
-        {% assign next = forloop.index0 | plus: 1 %}
-        <a href="{{ docs[next].url }}" class="btn">Next</a>
-      {% endunless %}
-      {% break %}
-    {% endif %}
-  {% endfor %}
-</div>
+{% for tutorial in tutorials %}
+  {% assign tutorial_url = tutorial | prepend:"/tutorials/" | append:"/" %}
+  {% if tutorial_url == page.url %}
+    <div class="section-nav">
+      <div class="left align-right">
+          {% if forloop.first %}
+            <span class="prev disabled">Back</span>
+          {% else %}
+            {% assign previous = forloop.index0 | minus: 1 %}
+            {% assign previous_page = tutorials[previous] | prepend:"/tutorials/" | append:"/" %}
+            <a href="{{ previous_page }}" class="prev">Back</a>
+          {% endif %}
+      </div>
+      <div class="right align-left">
+          {% if forloop.last %}
+            <span class="next disabled">Next</span>
+          {% else %}
+            {% assign next = forloop.index0 | plus: 1 %}
+            {% assign next_page = tutorials[next] | prepend:"/tutorials/" | append:"/" %}
+            <a href="{{ next_page }}" class="next">Next</a>
+          {% endif %}
+      </div>
+    </div>
+    <div class="clear"></div>
+    {% break %}
+  {% endif %}
+{% endfor %}
+
+
+{% for doc in docs %}
+  {% if doc.url == page.url %}
+    <div class="section-nav">
+      <div class="left align-right">
+          {% if forloop.first %}
+            <span class="prev disabled">Back</span>
+          {% else %}
+            {% assign previous = forloop.index0 | minus: 1 %}
+            <a href="{{ docs[previous].url }}" class="prev">Back</a>
+          {% endif %}
+      </div>
+      <div class="right align-left">
+          {% if forloop.last %}
+            <span class="next disabled">Next</span>
+          {% else %}
+            {% assign next = forloop.index0 | plus: 1 %}
+            <a href="{{ docs[next].url }}" class="next">Next</a>
+          {% endif %}
+      </div>
+    </div>
+    <div class="clear"></div>
+    {% break %}
+  {% endif %}
+{% endfor %}
 
 <ol class="step-nav">
   {% for step in docs %}

docs/_includes/top.html

@@ -0,0 +1,20 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta name="generator" content="Jekyll v{{ jekyll.version }}">
+  {% feed_meta %}
+  <link type="application/atom+xml" rel="alternate" href="{{ "/feed/release.xml" | relative_url }}" title="Jekyll releases posts" />
+  <link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="{{ site.repository }}/commits/master.atom">
+  <link rel="preload" href="/fonts/lato-v14-latin-300.woff2" as="font" type="font/woff2" crossorigin />
+  <link rel="preload" href="/fonts/lato-v14-latin-700.woff2" as="font" type="font/woff2" crossorigin />
+  <link rel="preload" href="{{ "/css/screen.css" | relative_url }}" as="style">
+  <link rel="stylesheet" href="/css/screen.css">
+  <link rel="icon" type="image/x-icon" href="/favicon.ico">
+  {% seo %}
+  <!--[if lt IE 9]>
+  <script src="/js/html5shiv.min.js"></script>
+  <script src="/js/respond.min.js"></script>
+  <![endif]-->
+</head>

docs/_includes/tutorials_contents.html

@@ -0,0 +1,10 @@
+<div class="unit one-fifth hide-on-mobiles">
+  <aside>
+    {% for section in site.data.tutorials %}
+    <h4>{{ section.title }}</h4>
+
+   {% include tutorials_ul.html items=section.tutorials %}
+
+    {% endfor %}
+  </aside>
+</div>

docs/_includes/tutorials_contents_mobile.html

@@ -0,0 +1,10 @@
+<div class="docs-nav-mobile unit whole show-on-mobiles">
+  <select onchange="if (this.value) window.location.href=this.value">
+    <option value="">Navigate the tutorials…</option>
+    {% for section in site.data.tutorials %}
+    <optgroup label="{{ section.title }}">
+      {% include tutorials_option.html items=section.tutorials %}
+    </optgroup>
+    {% endfor %}
+  </select>
+</div>

docs/_includes/tutorials_option.html

@@ -0,0 +1,5 @@
+{% for item in include.items %}
+  {% assign item_url = item | prepend:"/tutorials/" | append:"/" %}
+  {% assign tutorial = site.tutorials | where: "url", item_url | first %}
+  <option value="{{ tutorial.url }}">{{ tutorial.title }}</option>
+{% endfor %}

docs/_includes/tutorials_ul.html

@@ -0,0 +1,7 @@
+<ul>
+{% for item in include.items %}
+  {% assign item_url = item | prepend:"/tutorials/" | append:"/" %}
+  {% assign p = site.tutorials | where:"url", item_url | first %}
+  <li {%- if item_url == page.url %} class="current" {%- endif %}><a href="{{ p.url }}">{{ p.title }}</a></li>
+{% endfor %}
+</ul>

docs/_layouts/blank.html

@@ -1,7 +0,0 @@
----
-layout: default
----
-
-<section class="page">
-  {{ content }}
-</section>

docs/_layouts/default.html

@@ -1,31 +1,13 @@
-<!DOCTYPE HTML>
-<html lang="en-US">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width,initial-scale=1">
-  <meta name="generator" content="Jekyll v{{ jekyll.version }}">
-  {% feed_meta %}
-  <link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="{{ site.repository }}/commits/master.atom">
-  <!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" /> -->
-  <link rel="stylesheet" href="/css/screen.css">
-  <link rel="icon" type="image/x-icon" href="/favicon.ico">
-  {% seo %}
-</head>
-<body>
-  <div class="top-bg"><div class="shape top"></div><div class="shape bottom"></div></div>
-  <div class="container header">
-    <div class="logo">
-      <a href="/">
-        <img src="/img/jekyll-logo.svg" width="140" height="65" alt="Jekyll Logo">
-      </a>
-    </div>
-    {% include navigation/main.html %}
-  </div>
-  <div class="container">
-    {{ content }}
-  </div>
+{% include top.html %}
+
+<body class="wrap">
+  {% include header.html %}
+
+  {{ content }}
+
   {% include footer.html %}
-  {% include anchor-links.html %}
+  {% include anchor_links.html %}
   {% include analytics.html %}
+  {% include search/script.html %}
 </body>
 </html>

docs/_layouts/docs.html

@@ -1,5 +1,25 @@
 ---
-layout: sub-nav
-nav_source: 'docs'
+layout: default
 ---
-{{ content }}
+
+  <section class="docs">
+    <div class="grid">
+
+      {% include docs_contents_mobile.html %}
+
+      <div class="unit four-fifths">
+        <article>
+          <div class="improve right hide-on-mobiles">
+            <a data-proofer-ignore href="https://github.com/jekyll/jekyll/edit/master/docs/{{ page.path }}"><i class="fa fa-pencil"></i> &nbsp;Improve this page</a>
+          </div>
+          <h1>{{ page.title }}</h1>
+          {{ content }}
+        </article>
+      </div>
+
+      {% include docs_contents.html %}
+
+      <div class="clear"></div>
+
+    </div>
+  </section>

docs/_layouts/error.html

@@ -1,3 +1,4 @@
+{% include top.html %}
 
 <body class="wrap">
   <header>
@@ -15,6 +16,7 @@
 
   {{ content }}
 
+  {% include anchor_links.html %}
   {% include analytics.html %}
 
 </body>