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

Merge branch 'chrisfinazzo-upgrading-docs' 

* chrisfinazzo-upgrading-docs:
  Add further fixes to upgrade doc. #3607
  Use the new commands
  Fix a typo, wrap lines
  Remove reference to the watch command
  Start working on an upgrade guide for Jekyll 3
This commit is contained in:
Parker Moore 2015-04-10 16:57:00 -04:00
parent 70a3156385 20d48fcfe9
commit 2c316188fe
1 changed files with 31 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
site/_docs/upgrading.md
View File

@ -24,28 +24,30 @@ $ gem update jekyll
For better clarity, Jekyll now accepts the commands `build` and `serve`. For better clarity, Jekyll now accepts the commands `build` and `serve`.
Whereas before you might simply run the command `jekyll` to generate a site Whereas before you might simply run the command `jekyll` to generate a site
and `jekyll --server` to view it locally, now use the subcommands `jekyll build` and `jekyll --server` to view it locally, in v2.0 (and later) you should
and `jekyll serve` to do the same. And if you want Jekyll to automatically use the subcommands `jekyll build` and `jekyll serve` to build and preview
rebuild each time a file changes, just add the `--watch` flag at the end. your site.
<div class="note info"> <div class="note info">
<h5>Watching and Serving</h5> <h5>Watching and Serving</h5>
<p markdown="1">With the new subcommands, the way sites are previewed locally <p markdown="1">With the new subcommands, the way sites are previewed locally
changed a bit. Instead of specifying `server: true` in the site's changed a bit. Instead of specifying `server: true` in the site's
configuration file, use `jekyll serve`. The same hold's true for configuration file, use `jekyll serve`. The same holds true for
`watch: true`. Instead, use the `--watch` flag with either `jekyll serve` `watch: true`. Instead, use the `--watch` flag with either `jekyll serve`
or `jekyll build`.</p> or `jekyll build`.</p>
</div> </div>
### Absolute Permalinks ### Absolute Permalinks
In Jekyll v1.0, we introduced absolute permalinks for pages in subdirectories. In Jekyll v1.0, we introduced absolute permalinks for pages in
Until v2.0, it is **opt-in**. Starting with v2.0, however, absolute permalinks subdirectories. Starting with v2.0, absolute permalinks are opt-out,
will become **opt-out**, meaning Jekyll will default to using absolute permalinks meaning Jekyll will default to using absolute permalinks instead of
instead of relative permalinks. relative permalinks.
* To use absolute permalinks, set `relative_permalinks: false` in your configuration file. * To use absolute permalinks, set `relative_permalinks: false` in your
* To continue using relative permalinks, set `relative_permalinks: true` in your configuration file. configuration file.
* To continue using relative permalinks, set `relative_permalinks: true` in
your configuration file.
<div class="note warning" id="absolute-permalinks-warning"> <div class="note warning" id="absolute-permalinks-warning">
<h5 markdown="1">Absolute permalinks will be default in v2.0 and on</h5> <h5 markdown="1">Absolute permalinks will be default in v2.0 and on</h5>
@ -75,16 +77,16 @@ and add a new markdown file to it. To preview your new post, simply run the
### Custom Config File ### Custom Config File
Rather than passing individual flags via the command line, you can now pass an Rather than passing individual flags via the command line, you can now pass
entire custom Jekyll config file. This helps to distinguish between an entire custom Jekyll config file. This helps to distinguish between
environments, or lets you programmatically override user-specified defaults. environments, or lets you programmatically override user-specified
Simply add the `--config` flag to the `jekyll` command, followed by the path defaults. Simply add the `--config` flag to the `jekyll` command, followed
to one or more config files (comma-delimited, no spaces). by the path to one or more config files (comma-delimited, no spaces).
#### As a result, the following command line flags are now deprecated: #### As a result, the following command line flags are now deprecated:
* `--no-server` * `--no-server`
* `--no-auto` * `--no-auto` (now `--no-watch`)
* `--auto` (now `--watch`) * `--auto` (now `--watch`)
* `--server` * `--server`
* `--url=` * `--url=`
@ -106,9 +108,9 @@ to one or more config files (comma-delimited, no spaces).
### New Config File Options ### New Config File Options
Jekyll 1.0 introduced several new config file options. Before you upgrade, you Jekyll 1.0 introduced several new config file options. Before you upgrade,
should check to see if any of these are present in your pre-1.0 config file, and you should check to see if any of these are present in your pre-1.0 config
if so, make sure that you're using them properly: file, and if so, make sure that you're using them properly:
* `excerpt_separator` * `excerpt_separator`
* `host` * `host`
@ -121,15 +123,16 @@ if so, make sure that you're using them properly:
### Baseurl ### Baseurl
Often, you'll want the ability to run a Jekyll site in multiple places, such as Often, you'll want the ability to run a Jekyll site in multiple places,
previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes that such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes
easier with the new `--baseurl` flag. To take advantage of this feature, first that easier with the new `--baseurl` flag. To take advantage of this
add the production `baseurl` to your site's `_config.yml` file. Then, feature, first add the production `baseurl` to your site's `_config.yml`
throughout the site, simply prefix relative URLs with `{% raw %}{{ site.baseurl }}{% endraw %}`. file. Then, throughout the site, simply prefix relative URLs
When you're ready to preview your site locally, pass along the `--baseurl` flag with `{% raw %}{{ site.baseurl }}{% endraw %}`.
with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll will When you're ready to preview your site locally, pass along the `--baseurl`
swap in whatever you've passed along, ensuring all your links work as you'd flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll
expect in both environments. will swap in whatever you've passed along, ensuring all your links work as
you'd expect in both environments.
<div class="note warning"> <div class="note warning">