monad 0.0.2 → 0.0.3

data/site/docs/configuration.md

@@ -0,0 +1,373 @@
+---
+layout: docs
+title: Configuration
+prev_section: structure
+next_section: frontmatter
+permalink: /docs/configuration/
+---
+
+Jekyll allows you to concoct your sites in any way you can dream up, and it’s
+thanks to the powerful and flexible configuration options that this is possible.
+These options can either be specified in a `_config.yml` file placed in your
+site’s root directory, or can be specified as flags for the `jekyll` executable
+in the terminal.
+
+## Configuration Settings
+
+### Global Configuration
+
+The table below lists the available settings for Jekyll, and the various <code
+class="option">options</code> (specified in the configuration file) and <code
+class="flag">flags</code> (specified on the command-line) that control them.
+
+<div class="mobile-side-scroller">
+<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>Site Source</strong></p>
+        <p class='description'>Change the directory where Jekyll will read files</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">source: DIR</code></p>
+        <p><code class="flag">-s, --source DIR</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Site Destination</strong></p>
+        <p class='description'>Change the directory where Jekyll will write files</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">destination: DIR</code></p>
+        <p><code class="flag">-d, --destination DIR</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Safe</strong></p>
+        <p class='description'>Disable <a href="../plugins/">custom plugins</a>.</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">safe: BOOL</code></p>
+        <p><code class="flag">--safe</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Exclude</strong></p>
+        <p class="description">Exclude directories and/or files from the conversion</p>
+      </td>
+      <td class='align-center'>
+        <p><code class="option">exclude: [DIR, FILE, ...]</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Include</strong></p>
+        <p class="description">
+          Force inclusion of directories and/or files in the conversion.
+          <code>.htaccess</code> is a good example since dotfiles are excluded
+          by default.
+        </p>
+      </td>
+      <td class='align-center'>
+        <p><code class="option">include: [DIR, FILE, ...]</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Time Zone</strong></p>
+        <p class="description">
+            Set the time zone for site generation. This sets the <code>TZ</code>
+            environment variable, which Ruby uses to handle time and date
+            creation and manipulation. Any entry from the
+            <a href="http://en.wikipedia.org/wiki/Tz_database">IANA Time Zone
+            Database</a> is valid, e.g. <code>America/New_York</code>. The default
+            is the local time zone, as set by your operating system.
+        </p>
+      </td>
+      <td class='align-center'>
+        <p><code class="option">timezone: TIMEZONE</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Encoding</strong></p>
+        <p class="description">
+            Set the encoding of files by name. Only available for Ruby
+            1.9 or later).
+            The default value is nil, which use Ruby default,
+            <code>ASCII-8BIT</code>.
+            Available encoding for the ruby in use, can be shown by
+            command <code>ruby -e 'puts Encoding::list.join("\n")'</code>
+        </p>
+      </td>
+      <td class='align-center'>
+        <p><code class="option">encoding: ENCODING</code></p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+### Build Command Options
+
+<div class="mobile-side-scroller">
+<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'>Enable auto-regeneration of the site when files are modified.</p>
+      </td>
+      <td class="align-center">
+        <p><code class="flag">-w, --watch</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Configuration</strong></p>
+        <p class="description">Specify config files instead of using <code>_config.yml</code> automatically. Settings in later files override settings in earlier files.</p>
+      </td>
+      <td class='align-center'>
+        <p><code class="flag">--config FILE1[,FILE2,...]</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Drafts</strong></p>
+        <p class="description">Process and render draft posts.</p>
+      </td>
+      <td class='align-center'>
+        <p><code class="flag">--drafts</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Future</strong></p>
+        <p class="description">Publish posts with a future date.</p>
+      </td>
+      <td class='align-center'>
+        <p><code class="option">future: BOOL</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">Produce an index for related posts.</p>
+      </td>
+      <td class='align-center'>
+        <p><code class="option">lsi: BOOL</code></p>
+        <p><code class="flag">--lsi</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Limit Posts</strong></p>
+        <p class="description">Limit the number of posts to parse and publish.</p>
+      </td>
+      <td class='align-center'>
+        <p><code class="option">limit_posts: NUM</code></p>
+        <p><code class="flag">--limit_posts NUM</code></p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+### 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.
+
+<div class="mobile-side-scroller">
+<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'>Listen on the given port.</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">port: PORT</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'>Listen at the given hostname.</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">host: HOSTNAME</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 the website from the given base URL</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">baseurl: URL</code></p>
+        <p><code class="flag">--baseurl URL</code></p>
+      </td>
+    </tr>
+    <tr class='setting'>
+      <td>
+        <p class='name'><strong>Detach</strong></p>
+        <p class='description'>Detach the server from the terminal</p>
+      </td>
+      <td class="align-center">
+        <p><code class="option">detach: BOOL</code></p>
+        <p><code class="flag">-B, --detach</code></p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+<div class="note warning">
+  <h5>Do not use tabs in configuration files</h5>
+  <p>
+    This will either lead to parsing errors, or Jekyll will revert to the
+    default settings. Use spaces instead.
+  </p>
+</div>
+
+## Default Configuration
+
+Jekyll runs with the following configuration options by default. Unless
+alternative settings for these options are explicitly specified in the
+configuration file or on the command-line, Jekyll will run using these options.
+
+<div class="note warning">
+  <h5>There are two unsupported kramdown options</h5>
+  <p>
+    Please note that both <code>remove_block_html_tags</code> and
+    <code>remove_span_html_tags</code> are currently unsupported in Jekyll due to the
+    fact that they are not included within the kramdown HTML converter.
+  </p>
+</div>
+
+{% highlight yaml %}
+source:      .
+destination: ./_site
+plugins:     ./_plugins
+layouts:     ./_layouts
+include:     ['.htaccess']
+exclude:     []
+keep_files:  ['.git','.svn']
+timezone:    nil
+encoding:    nil
+
+future:      true
+show_drafts: nil
+limit_posts: 0
+pygments:    true
+
+relative_permalinks: true
+
+permalink:     date
+paginate_path: 'page:num'
+
+markdown:      maruku
+markdown_ext:  markdown,mkd,mkdn,md
+textile_ext:   textile
+
+excerpt_separator: "\n\n"
+
+safe:        false
+watch:       false    # deprecated
+server:      false    # deprecated
+host:        0.0.0.0
+port:        4000
+baseurl:     /
+url:         http://localhost:4000
+lsi:         false
+
+maruku:
+  use_tex:    false
+  use_divs:   false
+  png_engine: blahtex
+  png_dir:    images/latex
+  png_url:    /images/latex
+
+rdiscount:
+  extensions: []
+
+redcarpet:
+  extensions: []
+
+kramdown:
+  auto_ids: true
+  footnote_nr: 1
+  entity_output: as_char
+  toc_levels: 1..6
+  smart_quotes: lsquo,rsquo,ldquo,rdquo
+  use_coderay: false
+
+  coderay:
+    coderay_wrap: div
+    coderay_line_numbers: inline
+    coderay_line_numbers_start: 1
+    coderay_tab_width: 4
+    coderay_bold_every: 10
+    coderay_css: style
+
+redcloth:
+  hard_breaks: true
+{% endhighlight %}
+
+
+## Markdown Options
+
+The various Markdown renderers supported by Jekyll sometimes have extra options available.
+
+### Redcarpet
+
+Redcarpet can be configured by providing an `extensions` sub-setting, whose value should be an array of strings. Each string should be the name of one of the `Redcarpet::Markdown` class's extensions; if present in the array, it will set the corresponding extension to `true`.
+
+Jekyll handles two special Redcarpet extensions:
+
+- `no_fenced_code_blocks` --- By default, Jekyll sets the `fenced_code_blocks` extension (for delimiting code blocks with triple tildes or triple backticks) to `true`, probably because GitHub's eager adoption of them is starting to make them inescapable. Redcarpet's normal `fenced_code_blocks` extension is inert when used with Jekyll; instead, you can use this inverted version of the extension for disabling fenced code.
+
+    Note that you can also specify a language for highlighting after the first delimiter:
+
+        ```ruby
+        # ...ruby code
+        ```
+
+    With both fenced code blocks and pygments enabled, this will statically highlight the code; without pygments, it will add a `class="LANGUAGE"` attribute to the `<code>` element, which can be used as a hint by various JavaScript code highlighting libraries.
+- `smart` --- This pseudo-extension turns on SmartyPants, which converts straight quotes to curly quotes and runs of hyphens to em (`---`) and en (`--`) dashes.
+
+All other extensions retain their usual names from Redcarpet, and no renderer options aside from `smart` can be specified in Jekyll. [A list of available extensions can be found in the Redcarpet README file.][redcarpet_extensions] Make sure you're looking at the README for the right version of Redcarpet: Jekyll currently uses v2.2.x, and extensions like `footnotes` and `highlight` weren't added until after version 3.0.0. The most commonly used extensions are:
+
+- `tables`
+- `no_intra_emphasis`
+- `autolink`
+
+[redcarpet_extensions]: https://github.com/vmg/redcarpet/blob/v2.2.2/README.markdown#and-its-like-really-simple-to-use

data/site/docs/contributing.md

@@ -0,0 +1,128 @@
+---
+layout: docs
+title: Contributing
+prev_section: upgrading
+next_section: history
+permalink: /docs/contributing/
+---
+
+So you've got an awesome idea to throw into Jekyll. Great! Please keep the
+following in mind:
+
+* If you're creating a small fix or patch to an existing feature, just a simple
+  test will do. Please stay in the confines of the current test suite and use
+  [Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and
+  [RR](http://github.com/btakita/rr/tree/master).
+* If it's a brand new feature, make sure to create a new
+  [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps
+  where appropriate. Also, whipping up some documentation in your fork's `site`
+  would be appreciated, and once merged it will be transferred over to the main
+  `site`, jekyllrb.com.
+* If your contribution changes any Jekyll behavior, make sure to update the
+  documentation. It lives in `site/docs`. If the docs are missing information,
+  please feel free to add it in. Great docs make a great project!
+* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby)
+  when modifying Ruby code.
+* Please do your best to submit **small pull requests**. The easier the proposed
+  change is to review, the more likely it will be merged.
+* When submitting a pull request, please make judicious use of the pull request
+  body. A description of what changes were made, the motivations behind the
+  changes and [any tasks completed or left to complete](http://git.io/gfm-tasks)
+  will also speed up review time.
+
+<div class="note warning">
+  <h5>Contributions will not be accepted without tests</h5>
+  <p>
+    If you’re creating a small fix or patch to an existing feature, just
+    a simple test will do.
+  </p>
+</div>
+
+Test Dependencies
+-----------------
+
+To run the test suite and build the gem you'll need to install Jekyll's
+dependencies. Jekyll uses Bundler, so a quick run of the `bundle` command and
+you're all set!
+
+{% highlight bash %}
+$ bundle
+{% endhighlight %}
+
+Before you start, run the tests and make sure that they pass (to confirm your
+environment is configured properly):
+
+{% highlight bash %}
+$ bundle exec rake test
+$ bundle exec rake features
+{% endhighlight %}
+
+Workflow
+--------
+
+Here's the most direct way to get your work merged into the project:
+
+* Fork the project.
+* Clone down your fork:
+
+{% highlight bash %}
+git clone git://github.com/<username>/jekyll.git
+{% endhighlight %}
+
+* Create a topic branch to contain your change:
+
+{% highlight bash %}
+git checkout -b my_awesome_feature
+{% endhighlight %}
+
+
+* Hack away, add tests. Not necessarily in that order.
+* Make sure everything still passes by running `rake`.
+* If necessary, rebase your commits into logical chunks, without errors.
+* Push the branch up:
+
+{% highlight bash %}
+git push origin my_awesome_feature
+{% endhighlight %}
+
+* Create a pull request against mojombo/jekyll:master and describe what your
+  change does and the why you think it should be merged.
+
+Updating Documentation
+----------------------
+
+We want the Jekyll documentation to be the best it can be. We've
+open-sourced our docs and we welcome any pull requests if you find it
+lacking.
+
+You can find the documentation for jekyllrb.com in the
+[site]({{ site.repository }}/tree/master/site) directory of
+Jekyll's repo on GitHub.com.
+
+All documentation pull requests should be directed at `master`.  Pull
+requests directed at another branch will not be accepted.
+
+The [Jekyll wiki]({{ site.repository }}/wiki) on GitHub 
+can be freely updated without a pull request as all 
+GitHub users have access.
+
+Gotchas
+-------
+
+* If you want to bump the gem version, please put that in a separate commit.
+  This way, the maintainers can control when the gem gets released.
+* Try to keep your patch(es) based from the latest commit on mojombo/jekyll.
+  The easier it is to apply your work, the less work the maintainers have to do,
+  which is always a good thing.
+* Please don't tag your GitHub issue with \[fix\], \[feature\], etc. The maintainers
+  actively read the issues and will label it once they come across it.
+
+<div class="note">
+  <h5>Let us know what could be better!</h5>
+  <p>
+    Both using and hacking on Jekyll should be fun, simple, and easy, so if for
+    some reason you find it’s a pain, please <a
+    href="{{ site.repository }}/issues/new">create an issue</a> on
+    GitHub describing your experience so we can make it better.
+  </p>
+</div>