Skip to content
Permalink
Browse files

Upgrade documentation for Jekyll v4.0

  • Loading branch information...
DirtyF committed Aug 17, 2019
1 parent 2691412 commit 759315bfa394191d961e6363b4b527af6cb942c9
@@ -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:
@@ -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
@@ -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)
@@ -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

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

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

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

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
in Jekyll 3 and above.

<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,15 +129,15 @@ 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 %}

If you organize your posts in subdirectories, you need to include subdirectory path to the post:

{% 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 %}
@@ -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>
@@ -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
```

0 comments on commit 759315b

Please sign in to comment.
You can’t perform that action at this time.