Merge pull request #751 from mojombo/new-cmds-docs

Documentation for new command structure & opts
This commit is contained in:
Parker Moore 2013-01-16 16:43:38 -08:00
commit 5848476960
12 changed files with 218 additions and 155 deletions

View File

@ -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)

View File

@ -71,6 +71,9 @@
<li class="{% if page.title == "Troubleshooting" %}current{% endif %}">
<a href="{{ site.url }}/docs/troubleshooting">Troubleshooting</a>
</li>
<li class="{% if page.title == "Sites using Jekyll" %}current{% endif %}">
<a href="{{ site.url }}/docs/sites">Sites using Jekyll</a>
</li>
<li class="{% if page.title == "Resources" %}current{% endif %}">
<a href="{{ site.url }}/docs/resources">Resources</a>
</li>

View File

@ -9,6 +9,8 @@ Jekyll allows you to concoct your sites in any way you can dream up, and its
## Configuration Settings
### Global Configuration
The table below lists the available settings for Jekyll, and the various <code class="option">options</code> (specifed in the configuration file) and <code class="flag">flags</code> (specified on the command-line) that control them.
<table>
@ -19,6 +21,26 @@ The table below lists the available settings for Jekyll, and the various <code c
</tr>
</thead>
<tbody>
<tr class='setting'>
<td>
<p class='name'><strong>Site Source</strong></p>
<p class='description'>Changes the directory where Jekyll will look to transform files</p>
</td>
<td class="align-center">
<p><code class="option">source: [string]</code></p>
<p><code class="flag">--source [source]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Site Destination</strong></p>
<p class='description'>Changes the directory where Jekyll will write files to</p>
</td>
<td class="align-center">
<p><code class="option">destination: [string]</code></p>
<p><code class="flag">--destination</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Safe</strong></p>
@ -29,140 +51,6 @@ The table below lists the available settings for Jekyll, and the various <code c
<p><code class="flag">--safe</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Regeneration</strong></p>
<p class='description'>Enables or disables Jekyll from recreating the site when files are modified.</p>
</td>
<td class="align-center">
<p><code class="option">auto: [boolean]</code></p>
<p><code class="flag">--auto</code></p>
<p><code class="flag">--no-auto</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Local Server</strong></p>
<p class='description'>Fires up a server that will host your <code>_site</code> directory</p>
</td>
<td class="align-center">
<p><code class="option">server: [boolean]</code></p>
<p><code class="flag">--server</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Local Server Port</strong></p>
<p class='description'>Changes the port that the Jekyll server will run on</p>
</td>
<td class="align-center">
<p><code class="option">server_port: [integer]</code></p>
<p><code class="flag">--server [port]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Base URL</strong></p>
<p class='description'>Serve website from a given base URL</p>
</td>
<td class="align-center">
<p><code class="option">baseurl: [BASE_URL]</code></p>
<p><code class="flag">--base-url [url]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>URL</strong></p>
<p class='description'>Sets <code>site.url</code>, useful for environment switching</p>
</td>
<td class="align-center">
<p><code class="option">url: [URL]</code></p>
<p><code class="flag">--url [URL]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Site Destination</strong></p>
<p class="description">Changes the directory where Jekyll will write files to</p>
</td>
<td class='align-center'>
<p><code class="option">destination: [dir]</code></p>
<p><code class="flag">jekyll [dest]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Site Source</strong></p>
<p class="description">Changes the directory where Jekyll will look to transform files</p>
</td>
<td class='align-center'>
<p><code class="option">source: [dir]</code></p>
<p><code class="flag">jekyll [source] [dest]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Markdown</strong></p>
<p class="description">Uses RDiscount or <code>[engine]</code> instead of Maruku.</p>
</td>
<td class='align-center'>
<p><code class="option">markdown: [engine]</code></p>
<p><code class="flag">--rdiscount</code></p>
<p><code class="flag">--kramdown</code></p>
<p><code class="flag">--redcarpet</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Pygments</strong></p>
<p class="description">Enables highlight tag with Pygments.</p>
</td>
<td class='align-center'>
<p><code class="option">pygments: [boolean]</code></p>
<p><code class="flag">--pygments</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Future</strong></p>
<p class="description">Publishes posts with a future date</p>
</td>
<td class='align-center'>
<p><code class="option">future: [boolean]</code></p>
<p><code class="flag">--no-future</code></p>
<p><code class="flag">--future</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>LSI</strong></p>
<p class="description">Produces an index for related posts.</p>
</td>
<td class='align-center'>
<p><code class="option">lsi: [boolean]</code></p>
<p><code class="flag">--lsi</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Permalink</strong></p>
<p class="description">Controls the URLs that posts are generated with. Please refer to the <a href="../permalinks">Permalinks</a> page for more info.</p>
</td>
<td class='align-center'>
<p><code class="option">permalink: [style]</code></p>
<p><code class="flag">--permalink=[style]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Pagination</strong></p>
<p class="description">Splits your posts up over multiple subdirectories called "page2", "page3", ... "pageN"</p>
</td>
<td class='align-center'>
<p><code class="option">paginate: [per_page]</code></p>
<p><code class="flag">--paginate [per_page]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Exclude</strong></p>
@ -181,6 +69,98 @@ The table below lists the available settings for Jekyll, and the various <code c
<p><code class="option">include: [dir1, file1, dir2]</code></p>
</td>
</tr>
</tbody>
</table>
### Build Command Options
<table>
<thead>
<tr>
<th>Setting</th>
<th><span class="option">Options</span> and <span class="flag">Flags</span></th>
</tr>
</thead>
<tbody>
<tr class='setting'>
<td>
<p class='name'><strong>Regeneration</strong></p>
<p class='description'>Enables auto-regeneration of the site when files are modified. Off by default.</p>
</td>
<td class="align-center">
<p><code class="flag">--watch</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>URL</strong></p>
<p class='description'>Sets <code>site.url</code>, useful for environment switching</p>
</td>
<td class="align-center">
<p><code class="option">url: [URL]</code></p>
<p><code class="flag">--url [URL]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Markdown</strong></p>
<p class="description">Uses RDiscount or <code>[engine]</code> instead of Maruku.</p>
</td>
<td class='align-center'>
<p><code class="option">markdown: [engine]</code></p>
<p><code class="flag">--markdown [rdiscount|kramdown|redcarpet]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Pygments</strong></p>
<p class="description">Enables highlight tag with Pygments.</p>
</td>
<td class='align-center'>
<p><code class="option">pygments: [boolean]</code></p>
<p><code class="flag">--pygments</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Future</strong></p>
<p class="description">Publishes posts with a future date</p>
</td>
<td class='align-center'>
<p><code class="option">future: [boolean]</code></p>
<p><code class="flag">--future</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>LSI</strong></p>
<p class="description">Produces an index for related posts.</p>
</td>
<td class='align-center'>
<p><code class="option">lsi: [boolean]</code></p>
<p><code class="flag">--lsi</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Permalink</strong></p>
<p class="description">Controls the URLs that posts are generated with. Please refer to the <a href="../permalinks">Permalinks</a> page for more info.</p>
</td>
<td class='align-center'>
<p><code class="option">permalink: [style]</code></p>
<p><code class="flag">--permalink [style]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Pagination</strong></p>
<p class="description">Splits your posts up over multiple subdirectories called "page2", "page3", ... "pageN"</p>
</td>
<td class='align-center'>
<p><code class="option">paginate: [per_page]</code></p>
<p><code class="flag">--paginate [per_page]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Limit Posts</strong></p>
@ -188,10 +168,56 @@ The table below lists the available settings for Jekyll, and the various <code c
</td>
<td class='align-center'>
<p><code class="option">limit_posts: [max_posts]</code></p>
<p><code class="flag">--limit_posts=[max_posts]</code></p>
<p><code class="flag">--limit_posts [max_posts]</code></p>
</td>
</tr>
</tbody>
</table>
### 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.
<table>
<thead>
<tr>
<th>Setting</th>
<th><span class="option">Options</span> and <span class="flag">Flags</span></th>
</tr>
</thead>
<tbody>
<tr class='setting'>
<td>
<p class='name'><strong>Local Server Port</strong></p>
<p class='description'>Changes the port that the Jekyll server will run on</p>
</td>
<td class="align-center">
<p><code class="option">port: [integer]</code></p>
<p><code class="flag">--port [port]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Local Server Hostname</strong></p>
<p class='description'>Changes the hostname that the Jekyll server will run on</p>
</td>
<td class="align-center">
<p><code class="option">host: [string]</code></p>
<p><code class="flag">--host [hostname]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Base URL</strong></p>
<p class='description'>Serve website from a given base URL</p>
</td>
<td class="align-center">
<p><code class="option">baseurl: [BASE_URL]</code></p>
<p><code class="flag">--baseurl [url]</code></p>
</td>
</tr>
</tbody>
</table>
@ -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

View File

@ -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 %}

View File

@ -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 dont have to specify the flag every time).

View File

@ -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 %}

View File

@ -0,0 +1,28 @@
---
layout: docs
title: Sites using Jekyll
prev_section: troubleshooting
next_section: resources
---
Its 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

View File

@ -88,7 +88,7 @@ An overview of what each of these does:
<p>Other Files/Folders</p>
</td>
<td>
<p>Every other directory and file except for those listed above—such as <code>css</code> and <code>images</code> folders, <code>favicon.ico</code> 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.</p>
<p>Every other directory and file except for those listed above—such as <code>css</code> and <code>images</code> folders, <code>favicon.ico</code> files, and so forth—will be transferred over verbatim to the generated site. There's plenty of <a href="../sites">sites already using Jekyll</a> if you're curious as to how they're laid out.</p>
</td>
</tr>
</tbody>

View File

@ -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

View File

@ -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 <destination>
jekyll build --destination <destination>
#=> The current folder will get generated into <destination>
jekyll <source> <destination>
jekyll build --source <source> --destination <destination>
#=> The <source> folder will get generated into <destination>
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.

View File

@ -68,7 +68,7 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
</tr>
<tr>
<td><p><code>site.[CONFIGURATION_DATA]</code></p></td>
<td><p>All variables set in your <code>_config.yml</code> are available through the <code>site</code> variable. For example, if you have <code>url: http://mysite.com</code> in your configuration file, then in your posts and pages it can be accessed using <code>{{ "{{ site.url " }}}}</code>. Jekyll does not parse changes to <code>_config.yml</code> in <code>auto</code> mode, you have to restart Jekyll to see changes to variables.</p></td>
<td><p>All variables set in your <code>_config.yml</code> are available through the <code>site</code> variable. For example, if you have <code>url: http://mysite.com</code> in your configuration file, then in your posts and pages it can be accessed using <code>{{ "{{ site.url " }}}}</code>. Jekyll does not parse changes to <code>_config.yml</code> in <code>watch</code> mode, you have to restart Jekyll to see changes to variables.</p></td>
</tr>
</tbody>
</table>

View File

@ -16,19 +16,19 @@ overview: true
<p>
No more databases, comment moderation, or pesky updates to install—just <em>your content</em>.
</p>
<a href="https://github.com/mojombo/jekyll/wiki/Usage" class="">How Jekyll works &rarr;</a>
<a href="{% post_url 2012-07-01-usage %}" class="">How Jekyll works &rarr;</a>
</div>
<div class="grid4">
<h2>Static</h2>
<p><a href="http://daringfireball.net/projects/markdown/">Markdown</a> (or <a href="http://textile.sitemonks.com/">Textile</a>), <a href="http://liquidmarkup.org/">Liquid</a>, HTML <span class="amp">&amp;</span> CSS go in. Static sites come out ready for deployment.</p>
<a href="https://github.com/mojombo/jekyll/wiki/Template-Data" class="">Jekyll template guide &rarr;</a>
<a href="{% post_url 2012-07-01-templates %}" class="">Jekyll template guide &rarr;</a>
</div>
<div class="grid4">
<h2>Blog-aware</h2>
<p>
Permalinks, categories, pages, posts, and custom layouts are all first-class citizens here.
</p>
<a href="https://github.com/mojombo/jekyll/wiki/Blog-Migrations" class="">Migrate your blog &rarr;</a>
<a href="{% post_url 2012-07-01-migrations %}" class="">Migrate your blog &rarr;</a>
</div>
<div class="clear"></div>
</div>
@ -54,7 +54,7 @@ overview: true
<p class="line">
<span class="path">~/my/awesome/site</span>
<span class="prompt">$</span>
<span class="command">jekyll --server</span>
<span class="command">jekyll serve</span>
</p>
<p class="line">
<span class="output"># => Now browse to http://localhost:4000</span>