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

Update Upgrading docs. #965

This commit is contained in:
Parker Moore 2013-05-05 23:39:42 +02:00
parent 04837f7c78
commit 0619265e5b
1 changed files with 39 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
site/_posts/2012-07-01-upgrading.md
View File

@ -4,13 +4,14 @@ title: Upgrading
prev_section: resources
---
Upgrading from an older version of Jekyll? A few things have changed in 1.0.
Upgrading from an older version of Jekyll? A few things have changed in 1.0.0
that you'll want to know about.
<div class="note feature">
<h5 markdown="1">Diving in</h5>
<p markdown="1">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
run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
Jekyll site.</p>
</div>
@ -18,7 +19,7 @@ Upgrading from an older version of Jekyll? A few things have changed in 1.0.
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 serve` to view it locally, now use the subcommands `jekyll build`
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.
@ -26,7 +27,7 @@ rebuild each time a file changes, just add the `--watch` flag at the end.
<h5 markdown="1">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
`_config.yml` file, use `jekyll serve`. The same hold's true for
configuration file, use `jekyll serve`. The same hold's true for
`watch: true`. Instead, use the `--watch` flag with either `jekyll serve`
or `jekyll build`.</p>
</div>
@ -37,7 +38,7 @@ 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.
to one or more config files (comma-deliminated, no spaces).
#### As a result, the following command line flags are now deprecated:
@ -54,12 +55,12 @@ to one or more config files.
<div class="note info">
<h5 markdown="1">The `--config` explicitly specifies your configuration file(s)</h5>
<p markdown="1">If you use the `--config` flag, Jekyll will ignore your
`_config.yml` file. Want to merge a custom configuration with the normal
`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.</p>
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.</p>
</div>
### Draft posts
@ -89,3 +90,15 @@ 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">
<h5 markdown="1">All page and post URLs contain leading slashes</h5>
<p markdown="1">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 `/`.</p>
</div>