diff --git a/History.txt b/History.txt index 1588111b..b03fefc0 100644 --- a/History.txt +++ b/History.txt @@ -1,4 +1,6 @@ == HEAD + * Major Enhancements + * Refactored jekyll commands into subcommands: build, serve, and migrate. (#690) * Minor Enhancements * Add glob support to include, exclude option (#743) * Layout of Page or Post defaults to 'page' or 'post', respectively (#580) diff --git a/site/_includes/docs_contents.html b/site/_includes/docs_contents.html index ad3f3e16..7e7637f3 100644 --- a/site/_includes/docs_contents.html +++ b/site/_includes/docs_contents.html @@ -71,6 +71,9 @@
  • Troubleshooting
    • +
  • + Sites using Jekyll +
  • Resources
    • diff --git a/site/_posts/2012-07-01-configuration.md b/site/_posts/2012-07-01-configuration.md index a942914b..7fcb34fe 100644 --- a/site/_posts/2012-07-01-configuration.md +++ b/site/_posts/2012-07-01-configuration.md @@ -9,6 +9,8 @@ Jekyll allows you to concoct your sites in any way you can dream up, and it’s ## Configuration Settings +### Global Configuration + The table below lists the available settings for Jekyll, and the various options (specifed in the configuration file) and flags (specified on the command-line) that control them. @@ -19,6 +21,26 @@ The table below lists the available settings for Jekyll, and the various + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +
    +

    Site Source

    +

    Changes the directory where Jekyll will look to transform files

    +     		+

    source: [string]

    +

    --source [source]

    +
    +

    Site Destination

    +

    Changes the directory where Jekyll will write files to

    +     		+

    destination: [string]

    +

    --destination

    +

    Safe

    @@ -29,140 +51,6 @@ The table below lists the available settings for Jekyll, and the various --safe
    -

    Regeneration

    -

    Enables or disables Jekyll from recreating the site when files are modified.

    -     		-

    auto: [boolean]

    -

    --auto

    -

    --no-auto

    -
    -

    Local Server

    -

    Fires up a server that will host your _site directory

    -     		-

    server: [boolean]

    -

    --server

    -
    -

    Local Server Port

    -

    Changes the port that the Jekyll server will run on

    -     		-

    server_port: [integer]

    -

    --server [port]

    -
    -

    Base URL

    -

    Serve website from a given base URL

    -     		-

    baseurl: [BASE_URL]

    -

    --base-url [url]

    -
    -

    URL

    -

    Sets site.url, useful for environment switching

    -     		-

    url: [URL]

    -

    --url [URL]

    -
    -

    Site Destination

    -

    Changes the directory where Jekyll will write files to

    -     		-

    destination: [dir]

    -

    jekyll [dest]

    -
    -

    Site Source

    -

    Changes the directory where Jekyll will look to transform files

    -     		-

    source: [dir]

    -

    jekyll [source] [dest]

    -
    -

    Markdown

    -

    Uses RDiscount or [engine] instead of Maruku.

    -     		-

    markdown: [engine]

    -

    --rdiscount

    -

    --kramdown

    -

    --redcarpet

    -
    -

    Pygments

    -

    Enables highlight tag with Pygments.

    -     		-

    pygments: [boolean]

    -

    --pygments

    -
    -

    Future

    -

    Publishes posts with a future date

    -     		-

    future: [boolean]

    -

    --no-future

    -

    --future

    -
    -

    LSI

    -

    Produces an index for related posts.

    -     		-

    lsi: [boolean]

    -

    --lsi

    -
    -

    Permalink

    -

    Controls the URLs that posts are generated with. Please refer to the Permalinks page for more info.

    -     		-

    permalink: [style]

    -

    --permalink=[style]

    -
    -

    Pagination

    -

    Splits your posts up over multiple subdirectories called "page2", "page3", ... "pageN"

    -     		-

    paginate: [per_page]

    -

    --paginate [per_page]

    -

    Exclude

    @@ -181,6 +69,98 @@ The table below lists the available settings for Jekyll, and the various include: [dir1, file1, dir2]
    + +### Build Command Options + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    SettingOptions and Flags
    +

    Regeneration

    +

    Enables auto-regeneration of the site when files are modified. Off by default.

    +     		+

    --watch

    +
    +

    URL

    +

    Sets site.url, useful for environment switching

    +     		+

    url: [URL]

    +

    --url [URL]

    +
    +

    Markdown

    +

    Uses RDiscount or [engine] instead of Maruku.

    +     		+

    markdown: [engine]

    +

    --markdown [rdiscount|kramdown|redcarpet]

    +
    +

    Pygments

    +

    Enables highlight tag with Pygments.

    +     		+

    pygments: [boolean]

    +

    --pygments

    +
    +

    Future

    +

    Publishes posts with a future date

    +     		+

    future: [boolean]

    +

    --future

    +
    +

    LSI

    +

    Produces an index for related posts.

    +     		+

    lsi: [boolean]

    +

    --lsi

    +
    +

    Permalink

    +

    Controls the URLs that posts are generated with. Please refer to the Permalinks page for more info.

    +     		+

    permalink: [style]

    +

    --permalink [style]

    +
    +

    Pagination

    +

    Splits your posts up over multiple subdirectories called "page2", "page3", ... "pageN"

    +     		+

    paginate: [per_page]

    +

    --paginate [per_page]

    +

    Limit Posts

    @@ -188,10 +168,56 @@ The table below lists the available settings for Jekyll, and the various

    limit_posts: [max_posts]

    -

    --limit_posts=[max_posts]

    +

    --limit_posts [max_posts]
    +### Serve Command Options + +In addition to the options below, the `serve` sub-command can accept any of the options +for the `build` sub-command, which are then applied to the site build which occurs right +before your site is served. + + + + + + + + + + + + + + + + + + + + +
    SettingOptions and Flags
    +

    Local Server Port

    +

    Changes the port that the Jekyll server will run on

    +     		+

    port: [integer]

    +

    --port [port]

    +
    +

    Local Server Hostname

    +

    Changes the hostname that the Jekyll server will run on

    +     		+

    host: [string]

    +

    --host [hostname]

    +
    +

    Base URL

    +

    Serve website from a given base URL

    +     		+

    baseurl: [BASE_URL]

    +

    --baseurl [url]

    +
    @@ -206,9 +232,10 @@ Jekyll runs with the following configuration options by default. Unless alternat {% highlight yaml %} safe: false -auto: false +watch: false server: false -server_port: 4000 +host: 0.0.0.0 +port: 4000 baseurl: / url: http://localhost:4000 diff --git a/site/_posts/2012-07-01-deployment-methods.md b/site/_posts/2012-07-01-deployment-methods.md index 7716e5f8..80b55ae3 100644 --- a/site/_posts/2012-07-01-deployment-methods.md +++ b/site/_posts/2012-07-01-deployment-methods.md @@ -53,7 +53,7 @@ TMP_GIT_CLONE=$HOME/tmp/myrepo PUBLIC_WWW=/var/www/myrepo git clone $GIT_REPO $TMP_GIT_CLONE -jekyll --no-auto $TMP_GIT_CLONE $PUBLIC_WWW +jekyll build $TMP_GIT_CLONE $PUBLIC_WWW rm -Rf $TMP_GIT_CLONE exit {% endhighlight %} diff --git a/site/_posts/2012-07-01-extras.md b/site/_posts/2012-07-01-extras.md index 1af24d10..7bbff0b9 100644 --- a/site/_posts/2012-07-01-extras.md +++ b/site/_posts/2012-07-01-extras.md @@ -91,7 +91,7 @@ sudo gem install rdiscount And then run Jekyll with the following option: {% highlight bash %} -jekyll --rdiscount +jekyll build --markdown rdiscount {% endhighlight %} Or, specify RDiscount as the markdown engine in your `_config.yml` file to have Jekyll run with that option by default (so you don’t have to specify the flag every time). diff --git a/site/_posts/2012-07-01-home.md b/site/_posts/2012-07-01-home.md index 9c27eeef..34de7bb1 100644 --- a/site/_posts/2012-07-01-home.md +++ b/site/_posts/2012-07-01-home.md @@ -19,7 +19,7 @@ For the impatient, here's how to get Jekyll up and running. ~ $ mkdir -p my/new/site ~ $ cd my/new/site ~ $ vim index.html -~/my/new/site $ jekyll --server +~/my/new/site $ jekyll serve # => Now browse to http://localhost:4000 {% endhighlight %} diff --git a/site/_posts/2012-07-01-sites.md b/site/_posts/2012-07-01-sites.md new file mode 100644 index 00000000..f28c0280 --- /dev/null +++ b/site/_posts/2012-07-01-sites.md @@ -0,0 +1,28 @@ +--- +layout: docs +title: Sites using Jekyll +prev_section: troubleshooting +next_section: resources +--- + +It’s interesting to see what designs and features others have come up +with. Below are some Jekyll-powered blogs which were hand-picked for +learning purposes. + +- [Tom Preston-Werner](http://tom.preston-werner.com/) + ([source](http://github.com/mojombo/mojombo.github.com)) +- [Nick Quaranto](http://quaran.to/) + ([source](https://github.com/qrush/qrush.github.com)) +- [Roger Chapman](http://rogchap.com/) + ([source](https://github.com/rogchap/rogchap.github.com)) +- [GitHub Official Teaching Materials](http://teach.github.com) + ([source](https://github.com/github/teach.github.com)) +- [Rasmus Andersson](http://rsms.me/) + ([source](https://github.com/rsms/rsms.github.com)) +- [Scott Chacon](http://schacon.github.com) + ([source](https://github.com/schacon/schacon.github.com)) + +If you would like to explore more examples, you can find a list of sites +and their sources on the ["Sites" page in the Jekyll wiki][jekyll-sites]. + +[jekyll-sites]: https://github.com/mojombo/jekyll/wiki/Sites diff --git a/site/_posts/2012-07-01-structure.md b/site/_posts/2012-07-01-structure.md index 78212f03..87362b44 100644 --- a/site/_posts/2012-07-01-structure.md +++ b/site/_posts/2012-07-01-structure.md @@ -88,7 +88,7 @@ An overview of what each of these does:

    Other Files/Folders

    -

    Every other directory and file except for those listed above—such as css and images folders, favicon.ico files, and so forth—will be transferred over verbatim to the generated site. There's plenty of sites already using Jekyll if you're curious as to how they're laid out.

    +

    Every other directory and file except for those listed above—such as css and images folders, favicon.ico files, and so forth—will be transferred over verbatim to the generated site. There's plenty of sites already using Jekyll if you're curious as to how they're laid out.

    diff --git a/site/_posts/2012-07-01-troubleshooting.md b/site/_posts/2012-07-01-troubleshooting.md index e6a592f2..08dac8e8 100644 --- a/site/_posts/2012-07-01-troubleshooting.md +++ b/site/_posts/2012-07-01-troubleshooting.md @@ -50,7 +50,7 @@ On Debian or Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path in ## Base-URL Problems -If you are using base-url option like `jekyll --server --base-url '/blog'` then make sure that you access the site at `http://localhost:4000/blog/index.html`. Just accessing `http://localhost:4000/blog` will not work. +If you are using base-url option like `jekyll serve --baseurl '/blog'` then make sure that you access the site at `http://localhost:4000/blog/index.html`. Just accessing `http://localhost:4000/blog` will not work. ## Configuration problems diff --git a/site/_posts/2012-07-01-usage.md b/site/_posts/2012-07-01-usage.md index c1cfa5b1..ae1b07e1 100644 --- a/site/_posts/2012-07-01-usage.md +++ b/site/_posts/2012-07-01-usage.md @@ -8,28 +8,31 @@ next_section: structure The Jekyll gem makes a `jekyll` executable available to you in your Terminal window. You can use this command in a number of ways: {% highlight bash %} -jekyll +jekyll build #=> The current folder will get generated into ./_site -jekyll +jekyll build --destination #=> The current folder will get generated into -jekyll +jekyll build --source --destination #=> The folder will get generated into +jekyll build --watch +#=> The current folder will get generated into ./_site, +# and watch for changes and regenerate automatically. {% endhighlight %} Jekyll also comes with a built-in development server that will allow you to preview what the generated site will look like in your browser locally. {% highlight bash %} -jekyll --server +jekyll serve #=> A development server will run at http://localhost:4000/ -jekyll --server --auto +jekyll serve --watch #=> As above, but watch for changes and regenerate automatically too. {% endhighlight %} -These are just some of the many [configuration options](../configuration) available. All configuration options can either be specified as flags on the command line, or alternatively (and more commonly) they can be specified in a `_config.yml` file at the root of the source directory. Jekyll will automatically configuration options from this file when run, so placing the following two lines in the configuration file will mean that running `jekyll` would be equivalent to running `jekyll --server --auto`: +These are just some of the many [configuration options](../configuration) available. All configuration options can either be specified as flags on the command line, or alternatively (and more commonly) they can be specified in a `_config.yml` file at the root of the source directory. Jekyll will automatically configuration options from this file when run, so placing the following one line in the configuration file will mean that running `jekyll build` or `jekyll serve` would be equivalent to running `jekyll [build|serve] --source _source --destination _deploy`: {% highlight yaml %} -auto: true -server: true +source: _source +destination: _deploy {% endhighlight %} For more about the possible configuration options, see the [configuration](../configuration) page. diff --git a/site/_posts/2012-07-01-variables.md b/site/_posts/2012-07-01-variables.md index b04c14f5..01091474 100644 --- a/site/_posts/2012-07-01-variables.md +++ b/site/_posts/2012-07-01-variables.md @@ -68,7 +68,7 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr

    site.[CONFIGURATION_DATA]

    -

    All variables set in your _config.yml are available through the site variable. For example, if you have url: http://mysite.com in your configuration file, then in your posts and pages it can be accessed using {{ "{{ site.url " }}}}. Jekyll does not parse changes to _config.yml in auto mode, you have to restart Jekyll to see changes to variables.

    +

    All variables set in your _config.yml are available through the site variable. For example, if you have url: http://mysite.com in your configuration file, then in your posts and pages it can be accessed using {{ "{{ site.url " }}}}. Jekyll does not parse changes to _config.yml in watch mode, you have to restart Jekyll to see changes to variables.

    diff --git a/site/index.html b/site/index.html index 86711cd8..c0a35828 100644 --- a/site/index.html +++ b/site/index.html @@ -16,19 +16,19 @@ overview: true

    No more databases, comment moderation, or pesky updates to install—just your content.

    - How Jekyll works → + How Jekyll works →

    Static

    Markdown (or Textile), Liquid, HTML & CSS go in. Static sites come out ready for deployment.

    - Jekyll template guide → + Jekyll template guide →

    Blog-aware

    Permalinks, categories, pages, posts, and custom layouts are all first-class citizens here.

    - Migrate your blog → + Migrate your blog →
    @@ -54,7 +54,7 @@ overview: true

    ~/my/awesome/site $ - jekyll --server + jekyll serve

    # => Now browse to http://localhost:4000