From 0cdf659ebf24e5bbe11ae0a1112147cb4e5765a2 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 18 Nov 2015 08:50:49 -0800 Subject: [PATCH] Add upgrading docs from 2.x to 3.x --- site/_data/docs.yml | 3 +- site/_docs/upgrading.md | 136 +------------------------------- site/_docs/upgrading/0-to-2.md | 140 +++++++++++++++++++++++++++++++++ site/_docs/upgrading/2-to-3.md | 64 +++++++++++++++ site/_includes/docs_ul.html | 8 +- 5 files changed, 211 insertions(+), 140 deletions(-) create mode 100644 site/_docs/upgrading/0-to-2.md create mode 100644 site/_docs/upgrading/2-to-3.md diff --git a/site/_data/docs.yml b/site/_data/docs.yml index bcdf352d..dcd9ac2c 100644 --- a/site/_data/docs.yml +++ b/site/_data/docs.yml @@ -39,7 +39,8 @@ - troubleshooting - sites - resources - - upgrading + - upgrading/0-to-2 + - upgrading/2-to-3 - title: Meta docs: diff --git a/site/_docs/upgrading.md b/site/_docs/upgrading.md index 51fe67a1..a1280672 100644 --- a/site/_docs/upgrading.md +++ b/site/_docs/upgrading.md @@ -4,137 +4,7 @@ title: Upgrading permalink: /docs/upgrading/ --- -Upgrading from an older version of Jekyll? A few things have changed in 1.0 -that you'll want to know about. +Upgrading from an older version of Jekyll? Upgrading to a new major version of Jekyll (e.g. from v2.x to v3.x) may cause some headaches. Take the following guides to aid your upgrade: -Before we dive in, go ahead and fetch the latest version of Jekyll: - -{% highlight bash %} -$ gem update jekyll -{% endhighlight %} - -
-
Diving in
-

Want to get a new Jekyll site up and running quickly? Simply - run jekyll new SITENAME to create a new folder with a bare bones - Jekyll site.

-
- -### The Jekyll Command - -For better clarity, Jekyll now accepts the commands `build` and `serve`. -Whereas before you might simply run the command `jekyll` to generate a site -and `jekyll --server` to view it locally, in v2.0 (and later) you should -use the subcommands `jekyll build` and `jekyll serve` to build and preview -your site. - -
-
Watching and Serving
-

With the new subcommands, the way sites are previewed locally - changed a bit. Instead of specifying `server: true` in the site's - configuration file, use `jekyll serve`. The same holds true for - `watch: true`. Instead, use the `--watch` flag with either `jekyll serve` - or `jekyll build`.

-
- -### Absolute Permalinks - -In Jekyll v1.0, we introduced absolute permalinks for pages in -subdirectories. Starting with v2.0, absolute permalinks are opt-out, -meaning Jekyll will default to using absolute permalinks instead of -relative permalinks. Relative permalink backwards-compatibility was removed in v3.0. - - - -### Draft Posts - -Jekyll now lets you write draft posts, and allows you to easily preview how -they will look prior to publishing. To start a draft, simply create a folder -called `_drafts` in your site's source directory (e.g., alongside `_posts`), -and add a new markdown file to it. To preview your new post, simply run the -`jekyll serve` command with the `--drafts` flag. - -
-
Drafts don't have dates
-

- Unlike posts, drafts don't have a date, since they haven't - been published yet. Rather than naming your draft something like - `2013-07-01-my-draft-post.md`, simply name the file what you'd like your - post to eventually be titled, here `my-draft-post.md`.

-
- -### Custom Config File - -Rather than passing individual flags via the command line, you can now pass -an entire custom Jekyll config file. This helps to distinguish between -environments, or lets you programmatically override user-specified -defaults. Simply add the `--config` flag to the `jekyll` command, followed -by the path to one or more config files (comma-delimited, no spaces). - -#### As a result, the following command line flags are now deprecated: - -* `--no-server` -* `--no-auto` (now `--no-watch`) -* `--auto` (now `--watch`) -* `--server` -* `--url=` -* `--maruku`, `--rdiscount`, and `--redcarpet` -* `--pygments` -* `--permalink=` -* `--paginate` - -
-
The config flag explicitly specifies your configuration file(s)
-

If you use the `--config` flag, Jekyll will ignore your - `_config.yml` file. Want to merge a custom configuration with the normal - configuration? No problem. Jekyll will accept more than one custom config - file via the command line. Config files cascade from right to left, such - that if I run `jekyll serve --config _config.yml,_config-dev.yml`, - the values in the config files on the right (`_config-dev.yml`) overwrite - those on the left (`_config.yml`) when both contain the same key.

-
- -### New Config File Options - -Jekyll 1.0 introduced several new config file options. Before you upgrade, -you should check to see if any of these are present in your pre-1.0 config -file, and if so, make sure that you're using them properly: - -* `excerpt_separator` -* `host` -* `include` -* `keep_files` -* `layouts` -* `show_drafts` -* `timezone` -* `url` - -### Baseurl - -Often, you'll want the ability to run a Jekyll site in multiple places, -such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes -that easier with the new `--baseurl` flag. To take advantage of this -feature, first add the production `baseurl` to your site's `_config.yml` -file. Then, throughout the site, simply prefix relative URLs -with `{% raw %}{{ site.baseurl }}{% endraw %}`. -When you're ready to preview your site locally, pass along the `--baseurl` -flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll -will swap in whatever you've passed along, ensuring all your links work as -you'd expect in both environments. - - -
-
All page and post URLs contain leading slashes
-

If you use the method described above, please remember - that the URLs for all posts and pages contain a leading slash. Therefore, - concatenating the site baseurl and the post/page url where - `site.baseurl = /` and `post.url = /2013/06/05/my-fun-post/` will - result in two leading slashes, which will break links. It is thus - suggested that prefixing with `site.baseurl` only be used when the - `baseurl` is something other than the default of `/`.

-
+- [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/) diff --git a/site/_docs/upgrading/0-to-2.md b/site/_docs/upgrading/0-to-2.md new file mode 100644 index 00000000..84ec90e7 --- /dev/null +++ b/site/_docs/upgrading/0-to-2.md @@ -0,0 +1,140 @@ +--- +layout: docs +title: Upgrading from 0.x to 2.x +permalink: /docs/upgrading/0-to-2/ +--- + +Upgrading from an older version of Jekyll? A few things have changed in 1.0 +and 2.0 that you'll want to know about. + +Before we dive in, go ahead and fetch the latest version of Jekyll: + +{% highlight bash %} +$ gem update jekyll +{% endhighlight %} + +
+
Diving in
+

Want to get a new Jekyll site up and running quickly? Simply + run jekyll new SITENAME to create a new folder with a bare bones + Jekyll site.

+
+ +### The Jekyll Command + +For better clarity, Jekyll now accepts the commands `build` and `serve`. +Whereas before you might simply run the command `jekyll` to generate a site +and `jekyll --server` to view it locally, in v2.0 (and later) you should +use the subcommands `jekyll build` and `jekyll serve` to build and preview +your site. + +
+
Watching and Serving
+

With the new subcommands, the way sites are previewed locally + changed a bit. Instead of specifying `server: true` in the site's + configuration file, use `jekyll serve`. The same holds true for + `watch: true`. Instead, use the `--watch` flag with either `jekyll serve` + or `jekyll build`.

+
+ +### Absolute Permalinks + +In Jekyll v1.0, we introduced absolute permalinks for pages in +subdirectories. Starting with v2.0, absolute permalinks are opt-out, +meaning Jekyll will default to using absolute permalinks instead of +relative permalinks. Relative permalink backwards-compatibility was removed in v3.0. + + + +### Draft Posts + +Jekyll now lets you write draft posts, and allows you to easily preview how +they will look prior to publishing. To start a draft, simply create a folder +called `_drafts` in your site's source directory (e.g., alongside `_posts`), +and add a new markdown file to it. To preview your new post, simply run the +`jekyll serve` command with the `--drafts` flag. + +
+
Drafts don't have dates
+

+ Unlike posts, drafts don't have a date, since they haven't + been published yet. Rather than naming your draft something like + `2013-07-01-my-draft-post.md`, simply name the file what you'd like your + post to eventually be titled, here `my-draft-post.md`.

+
+ +### Custom Config File + +Rather than passing individual flags via the command line, you can now pass +an entire custom Jekyll config file. This helps to distinguish between +environments, or lets you programmatically override user-specified +defaults. Simply add the `--config` flag to the `jekyll` command, followed +by the path to one or more config files (comma-delimited, no spaces). + +#### As a result, the following command line flags are now deprecated: + +* `--no-server` +* `--no-auto` (now `--no-watch`) +* `--auto` (now `--watch`) +* `--server` +* `--url=` +* `--maruku`, `--rdiscount`, and `--redcarpet` +* `--pygments` +* `--permalink=` +* `--paginate` + +
+
The config flag explicitly specifies your configuration file(s)
+

If you use the `--config` flag, Jekyll will ignore your + `_config.yml` file. Want to merge a custom configuration with the normal + configuration? No problem. Jekyll will accept more than one custom config + file via the command line. Config files cascade from right to left, such + that if I run `jekyll serve --config _config.yml,_config-dev.yml`, + the values in the config files on the right (`_config-dev.yml`) overwrite + those on the left (`_config.yml`) when both contain the same key.

+
+ +### New Config File Options + +Jekyll 1.0 introduced several new config file options. Before you upgrade, +you should check to see if any of these are present in your pre-1.0 config +file, and if so, make sure that you're using them properly: + +* `excerpt_separator` +* `host` +* `include` +* `keep_files` +* `layouts` +* `show_drafts` +* `timezone` +* `url` + +### Baseurl + +Often, you'll want the ability to run a Jekyll site in multiple places, +such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes +that easier with the new `--baseurl` flag. To take advantage of this +feature, first add the production `baseurl` to your site's `_config.yml` +file. Then, throughout the site, simply prefix relative URLs +with `{% raw %}{{ site.baseurl }}{% endraw %}`. +When you're ready to preview your site locally, pass along the `--baseurl` +flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll +will swap in whatever you've passed along, ensuring all your links work as +you'd expect in both environments. + + +
+
All page and post URLs contain leading slashes
+

If you use the method described above, please remember + that the URLs for all posts and pages contain a leading slash. Therefore, + concatenating the site baseurl and the post/page url where + `site.baseurl = /` and `post.url = /2013/06/05/my-fun-post/` will + result in two leading slashes, which will break links. It is thus + suggested that prefixing with `site.baseurl` only be used when the + `baseurl` is something other than the default of `/`.

+
diff --git a/site/_docs/upgrading/2-to-3.md b/site/_docs/upgrading/2-to-3.md new file mode 100644 index 00000000..25d38b00 --- /dev/null +++ b/site/_docs/upgrading/2-to-3.md @@ -0,0 +1,64 @@ +--- +layout: docs +title: Upgrading from 2.x to 3.x +permalink: /docs/upgrading/2-to-3/ +--- + +Upgrading from an older version of Jekyll? A few things have changed in 3.0 +that you'll want to know about. + +Before we dive in, go ahead and fetch the latest version of Jekyll: + +{% highlight bash %} +$ gem update jekyll +{% endhighlight %} + +
+
Diving in
+

Want to get a new Jekyll site up and running quickly? Simply + run jekyll new SITENAME to create a new folder with a bare bones + Jekyll site.

+
+ +### site.collections has changed + +In 2.x, your iterations over `site.collections` yielded an array with the collection +label and the collection object as the first and second items, respectively. In 3.x, +this complication has been removed and iterations now yield simply the collection object. +A simple conversion must be made in your templates: + +- `collection[0]` becomes `collection.label` +- `collection[1]` becomes `collection` + +When iterating over `site.collections`, ensure the above conversions are made. + +### Dropped dependencies + +We dropped a number of dependencies the Core Team felt were optional. As such, in 3.0, they must be explicitly installed and included if you use any of the features. They are: + +- jekyll-paginate – Jekyll's pagination solution from days past +- jekyll-coffeescript – processing of CoffeeScript +- jekyll-gist – the `gist` Liquid tag +- pygments.rb – the Pygments highlighter +- redcarpet – the Markdown processor +- toml – an alternative to YAML for configuration files +- classifier-reborn – for `site.related_posts` + +### Future posts + +A seeming feature regression in 2.x, the `--future` flag was automatically _enabled_. +The future flag allows post authors to give the post a date in the future and to have +it excluded from the build until the system time is equal or after the post time. +In Jekyll 3, this has been corrected. **Now, `--future` is disabled by default.** +This means you will need to include `--future` if you want your future-dated posts to +generate when running `jekyll build` or `jekyll serve`. + +### Layout metadata + +Introducing: `layout`. In Jekyll 2 and below, any metadata in the layout was munged onto +the `page` variable in Liquid. This caused a lot of confusion in the way the data was +merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible via `layout` +in Liquid. For example, if your layout has `class: my-layout` in its YAML front matter, +then the layout can access that via `{% raw %}{{ layout.class }}{% endraw %}`. + +_Did we miss something? Please click "Improve this page" above and add a section. Thanks!_ diff --git a/site/_includes/docs_ul.html b/site/_includes/docs_ul.html index 7cc54174..34b6278a 100644 --- a/site/_includes/docs_ul.html +++ b/site/_includes/docs_ul.html @@ -10,12 +10,8 @@ {% assign c = "" %} {% endif %} - {% for p in site.docs %} - {% if p.url == item_url %} -
  • {{ p.title }}
    • - {% break %} - {% endif %} - {% endfor %} + {% assign p = site.docs | where:"url",item_url | first %} +
  • {{ p.title }}
    • {% endfor %}