dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Upgrade documentation for Jekyll v4.0

This commit is contained in:
Frank Taillandier 2019-08-17 14:02:14 +02:00
parent 26914126c7
commit 759315bfa3
18 changed files with 67 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.travis.yml
View File

@ -4,8 +4,8 @@ cache: bundler
language: ruby
rvm:
- &ruby1 2.6.0
- &ruby2 2.4.5
- &ruby1 2.6.3
- &ruby2 2.4.6
- &jruby jruby-9.2.7.0
matrix:

3
docs/_config.yml
View File

@ -1,6 +1,5 @@
---
version: 3.8.6
min_ruby_version: 2.4.0
name: Jekyll • Simple, blog-aware, static sites
description: Transform your plain text into static websites and blogs
url: https://jekyllrb.com
@ -54,6 +53,8 @@ feed:
sass:
style: compressed
strict_front_matter: true
exclude:
- .gitignore
- .jekyll-cache

3
docs/_data/ruby.yml Normal file
View File

@ -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)

3
docs/_docs/collections.md
View File

@ -114,8 +114,6 @@ 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.
{% if site.version == '4.0.0' %}{% comment %} Remove this encapsulation when v4.0 ships {% endcomment %}
## Custom Sorting of Documents
By default, documents in a collection are sorted by their paths. But you can control this sorting via the collection's metadata.
@ -164,7 +162,6 @@ collections:
```
If both metadata keys have been defined properly, `order` list takes precedence.
{% endif %}
## Liquid Attributes

6
docs/_docs/front-matter.md
View File

@ -33,7 +33,7 @@ relies on.
</div>
<div class="note">
<h5>ProTip™: Front Matter Variables Are Optional</h5>
<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
@ -114,7 +114,7 @@ front matter of a page or post.
</div>
<div class="note">
<h5>ProTip™: Render Posts Marked As Unpublished</h5>
<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>
@ -201,7 +201,7 @@ These are available out-of-the-box to be used in the front matter for a post.
</div>
<div class="note">
<h5>ProTip™: Don't repeat yourself</h5>
<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>

2
docs/_docs/installation.md
View File

@ -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 {{ site.min_ruby_version }} 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)

14
docs/_docs/installation/macos.md
View File

@ -12,7 +12,7 @@ xcode-select --install
## Install Ruby
Jekyll requires Ruby > {{ site.min_ruby_version }}.
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}
@ -25,7 +25,7 @@ To run the latest Ruby version you need to install it through [Homebrew](https:/
brew install ruby
```
Don't forget to add the brew ruby path to your shell config :
Add the brew ruby path to your shell config :
```
export PATH=/usr/local/opt/ruby/bin:$PATH
@ -38,7 +38,7 @@ which ruby
# /usr/local/opt/ruby/bin/ruby
ruby -v
# ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin18]
{{ site.data.ruby.current_version_output }}
```
Yay, we are now running current stable Ruby!
@ -66,10 +66,10 @@ Restart your terminal for changes to take effect.
Now you can install the Ruby version of our choice, let's go with current latest stable Ruby:
```sh
rbenv install 2.6.2
rbenv global 2.6.2
rbenv install {{ site.data.ruby.current_version }}
rbenv global {{ site.data.ruby.current_version }}
ruby -v
# ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin18]
{{ 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.
@ -88,7 +88,7 @@ and then get your Ruby version using
```sh
ruby -v
# ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18]
{{ 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.

2
docs/_docs/liquid/filters.md
View File

@ -104,7 +104,7 @@ 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.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,

38
docs/_docs/liquid/tags.md
View File

@ -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,14 +40,14 @@ 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).
<div class="note info">
<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.</p>
<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
@ -89,9 +82,11 @@ the syntax highlighter styles into your `main.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.
@ -118,9 +113,6 @@ You can also use the `link` tag to create a link in Markdown as follows:
```
{% endraw %}
{: .note }
Since {% include docs_version_badge.html version="v4.0"%} you don't need to prepend `link` tags with `site.baseurl`
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`.
@ -137,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 %}
@ -145,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 %}
@ -155,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 %}

14
docs/_docs/permalinks.md
View File

@ -110,7 +110,7 @@ Here's the full list of placeholders available:
<tr>
<td>
<p><code>long_month</code></p>
<small>{% include docs_version_badge.html version="4.0.0" %}</small>
<small>{% include docs_version_badge.html version="4.0" %}</small>
</td>
<td>
<p>Full month name, e.g. “January”.</p>
@ -149,7 +149,7 @@ Here's the full list of placeholders available:
<tr>
<td>
<p><code>w_year</code></p>
<small>{% include docs_version_badge.html version="4.0.0" %}</small>
<small>{% include docs_version_badge.html version="4.0" %}</small>
</td>
<td>
<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>
@ -158,7 +158,7 @@ Here's the full list of placeholders available:
<tr>
<td>
<p><code>week</code></p>
<small>{% include docs_version_badge.html version="4.0.0" %}</small>
<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>
@ -167,7 +167,7 @@ Here's the full list of placeholders available:
<tr>
<td>
<p><code>w_day</code></p>
<small>{% include docs_version_badge.html version="4.0.0" %}</small>
<small>{% include docs_version_badge.html version="4.0" %}</small>
</td>
<td>
<p>Day of the week, starting with Monday. (1..7)</p>
@ -176,7 +176,7 @@ Here's the full list of placeholders available:
<tr>
<td>
<p><code>short_day</code></p>
<small>{% include docs_version_badge.html version="4.0.0" %}</small>
<small>{% include docs_version_badge.html version="4.0" %}</small>
</td>
<td>
<p>Three-letter weekday abbreviation, e.g. “Sun”.</p>
@ -185,7 +185,7 @@ Here's the full list of placeholders available:
<tr>
<td>
<p><code>long_day</code></p>
<small>{% include docs_version_badge.html version="4.0.0" %}</small>
<small>{% include docs_version_badge.html version="4.0" %}</small>
</td>
<td>
<p>Weekday name, e.g. “Sunday”.</p>
@ -302,7 +302,7 @@ For posts, Jekyll also provides the following built-in styles for convenience:
<tr>
<td>
<p><code>weekdate</code></p>
<small>{% include docs_version_badge.html version="4.0.0" %}</small>
<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>

8
docs/_docs/ruby-101.md
View File

@ -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
```

28
docs/_docs/themes.md
View File

@ -43,7 +43,7 @@ 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:
@ -55,10 +55,10 @@ To locate a theme's files on your computer:
# First get the gem's installation path:
#
# bundle show minima
# => C:/Ruby24-x64/lib/ruby/gems/2.4.0/gems/minima-2.1.0
# => 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:\Ruby24-x64\lib\ruby\gems\2.4.0\gems\minima-2.1.0
explorer C:\Ruby26-x64\lib\ruby\gems\{{ site.data.ruby.current_version}}\gems\minima-2.5.1
# On Linux
xdg-open $(bundle show minima)
@ -121,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.
@ -132,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
@ -150,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
```
@ -161,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.
@ -187,7 +187,7 @@ To install a gem-based theme:
```diff
# ./Gemfile
- gem "minima", "~> 2.0"
- gem "minima", "~> 2.5"
+ gem "jekyll-theme-minimal"
```
@ -282,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.
@ -298,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

6
docs/_docs/upgrading/3-to-4.md
View File

@ -5,17 +5,17 @@ permalink: /docs/upgrading/3-to-4/
A few things have changed in Jekyll 4.
Before we dive in, you need to have at least Ruby {{ site.min_ruby_version }}
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
ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin18]
{{ site.data.ruby.current_version_output }}
```
If you're using a supported Ruby version > {{ site.min_ruby_version }}, go ahead
If you're using a supported Ruby version > {{ site.data.ruby.min_version }}, go ahead
and fetch the latest version of Jekyll:
```sh

4
docs/_docs/usage.md
View File

@ -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.

2
docs/_includes/news_contents_mobile.html
View File

@ -2,7 +2,7 @@
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the blog…</option>
<option value="/news/">Home</option>
<optgroup label="v1.x">
<optgroup label="posts">
{% for post in site.posts %}
<option value="{{ post.url }}">{{ post.title }}</option>
{% endfor %}

2
docs/latest_version.txt
View File

@ -1 +1 @@
3.8.5
3.8.6

3
jekyll.gemspec
View File

@ -50,9 +50,8 @@ Gem::Specification.new do |s|
s.post_install_message = <<~MSG
-------------------------------------------------------------------------------------
This version of Jekyll comes with some major changes.
Jekyll 4.0 comes with some major changes, notably:
Most notably:
* Our `link` tag now comes with the `relative_url` filter incorporated into it.
You should no longer prepend `{{ site.baseurl }}` to `{% link foo.md %}`
For further details: https://github.com/jekyll/jekyll/pull/6727

4
lib/jekyll/commands/new.rb
View File

@ -80,13 +80,13 @@ module Jekyll
# Happy Jekylling!
gem "jekyll", "~> #{Jekyll::VERSION}"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.0"
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
gem "jekyll-feed", "~> 0.6"
gem "jekyll-feed", "~> 0.12"
end
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem