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`.
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 serve` to do the same. And if you want Jekyll to automatically
rebuild each time a file changes, just add the `--watch` flag at the end.
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.
<div class="note info">
<h5>Watching and Serving</h5>
<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
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`
or `jekyll build`.</p>
</div>
### Absolute Permalinks
In Jekyll v1.0, we introduced absolute permalinks for pages in subdirectories.
Until v2.0, it is **opt-in**. Starting with v2.0, however, absolute permalinks
will become **opt-out**, meaning Jekyll will default to using absolute permalinks
instead of relative 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.
* To use absolute permalinks, set `relative_permalinks: false` in your configuration file.
* To continue using relative permalinks, set `relative_permalinks: true` in your configuration file.
* To use absolute permalinks, set `relative_permalinks: false` in your
configuration file.
* To continue using relative permalinks, set `relative_permalinks: true` in
your configuration file.
<div class="note warning" id="absolute-permalinks-warning">
<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
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).
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`
* `--no-auto` (now `--no-watch`)
* `--auto` (now `--watch`)
* `--server`
* `--url=`
@ -106,9 +108,9 @@ to one or more config files (comma-delimited, no spaces).
### 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:
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`
@ -121,15 +123,16 @@ if so, make sure that you're using them properly:
### 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.
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.
<div class="note warning">