diff --git a/site/_includes/docs_contents.html b/site/_includes/docs_contents.html index aa4890a9..4575f9ef 100644 --- a/site/_includes/docs_contents.html +++ b/site/_includes/docs_contents.html @@ -77,6 +77,9 @@
  • Resources
    • +
  • + Upgrading +
    • diff --git a/site/_posts/2012-07-01-resources.md b/site/_posts/2012-07-01-resources.md index c14c584c..c319df2d 100644 --- a/site/_posts/2012-07-01-resources.md +++ b/site/_posts/2012-07-01-resources.md @@ -2,6 +2,7 @@ layout: docs title: Resources prev_section: sites +next_section: upgrading --- Jekyll’s growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources. diff --git a/site/_posts/2012-07-01-upgrading.md b/site/_posts/2012-07-01-upgrading.md new file mode 100644 index 00000000..33c03a0c --- /dev/null +++ b/site/_posts/2012-07-01-upgrading.md @@ -0,0 +1,91 @@ +--- +layout: docs +title: Upgrading +prev_section: resources +--- + +Upgrading from an older version of Jekyll? A few things have changed in 1.0. + + +
    +
    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 serve` 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. + +
    +
    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 + `_config.yml` file, use `jekyll serve`. The same hold's true for + `watch: true`. Instead, use the `--watch` flag with either `jekyll serve` + or `jekyll build`.

    +
    + +### 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. + +#### As a result, the following command line flags are now deprecated: + +* `--no-server` +* `--no-auto` +* `--auto` (now `--watch`) +* `--server` +* `--url=` +* `--maruku`, `--rdiscount`, and `--redcarpet` +* `--pygments` +* `--permalink=` +* `--paginate` + +
    +
    The `--config` 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.

    +
    + +### 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`.

    +
    + +### 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 `{{ site.baseurl }}`. +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.