monad 0.0.2 → 0.0.3

data/site/docs/datafiles.md

@@ -0,0 +1,63 @@
+---
+layout: docs
+title: Data Files
+prev_section: variables
+next_section: migrations
+permalink: /docs/datafiles/
+---
+
+In addition to the [built-in variables](../variables/) available from Jekyll,
+you can specify your own custom data that can be accessed via the [Liquid 
+templating system](http://wiki.github.com/shopify/liquid/liquid-for-designers).
+
+Jekyll supports loading data from [YAML](http://yaml.org/) files located in the 
+`_data` directory.
+
+This powerful features allows you to avoid repetition in your templates and to
+set site specific options without changing `_config.yml`. 
+
+Plugins/themes can also leverage Data Files to set configuration variables.
+
+## The Data Folder
+
+As explained on the [directory structure](../structure/) page, the `_data` 
+folder is where you can store additional data for Jekyll to use when generating
+your site. These files must be YAML files (using either the `.yml` or `.yaml`
+extension) and they will be accessible via `site.data`.
+
+## Example: List of members
+
+Here is a basic example of using Data Files to avoid copy-pasting large chunks of
+code in your Jekyll templates:
+
+In `_data/members.yml`:
+
+{% highlight yaml %}
+- name: Tom Preston-Werner
+  github: mojombo
+
+- name: Parker Moore
+  github: parkr
+
+- name: Liu Fengyun
+  github: liufengyun
+{% endhighlight %}
+
+This data can be accessed via `site.data.members` (notice that the filename
+determines the variable name).
+
+You can now render the list of members in a template:
+
+{% highlight html %}
+{% raw %}
+<ul>
+{% for member in site.data.members %}
+  <li>
+    <a href="https://github.com/{{ member.github }}">
+      {{ member.name }}
+    </a>
+  </li>
+{% end %}
+</ul>
+{% endraw %}
+{% endhighlight %}

data/site/docs/deployment-methods.md

@@ -0,0 +1,109 @@
+---
+layout: docs
+title: Deployment methods
+prev_section: github-pages
+next_section: troubleshooting
+permalink: /docs/deployment-methods/
+---
+
+Sites built using Jekyll can be deployed in a large number of ways due to the static nature of the generated output. A few of the most common deployment techniques are described below.
+
+## Web hosting providers (FTP)
+
+Just about any traditional web hosting provider will let you upload files to their servers over FTP. To upload a Jekyll site to a web host using FTP, simply run the `jekyll` command and copy the generated `_site` folder to the root folder of your hosting account. This is most likely to be the `httpdocs` or `public_html` folder on most hosting providers.
+
+### FTP using Glynn
+
+There is a project called [Glynn](https://github.com/dmathieu/glynn), which lets you easily generate your Jekyll powered website’s static files and
+send them to your host through FTP.
+
+## Self-managed web server
+
+If you have direct access yourself to the deployment web server yourself, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Just remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server.
+
+## Automated methods
+
+There are also a number of ways to easily automate the deployment of a Jekyll site. If you’ve got another method that isn’t listed below, we’d love it if you [contributed](../contributing/) so that everyone else can benefit too.
+
+### Git post-update hook
+
+If you store your jekyll site in [Git](http://git-scm.com/) (you are using version control, right?), it’s pretty easy to automate the
+deployment process by setting up a post-update hook in your Git
+repository, [like
+this](http://web.archive.org/web/20091223025644/http://www.taknado.com/en/2009/03/26/deploying-a-jekyll-generated-site/).
+
+### Git post-receive hook
+
+To have a remote server handle the deploy for you every time you push changes using Git, you can create a user account which has all the public keys that are authorized to deploy in its `authorized_keys` file. With that in place, setting up the post-receive hook is done as follows:
+
+{% highlight bash %}
+laptop$ ssh deployer@myserver.com
+server$ mkdir myrepo.git
+server$ cd myrepo.git
+server$ git --bare init
+server$ cp hooks/post-receive.sample hooks/post-receive
+server$ mkdir /var/www/myrepo
+{% endhighlight %}
+
+Next, add the following lines to hooks/post-receive and be sure Jekyll is
+installed on the server:
+
+{% highlight bash %}
+GIT_REPO=$HOME/myrepo.git
+TMP_GIT_CLONE=$HOME/tmp/myrepo
+PUBLIC_WWW=/var/www/myrepo
+
+git clone $GIT_REPO $TMP_GIT_CLONE
+jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW
+rm -Rf $TMP_GIT_CLONE
+exit
+{% endhighlight %}
+
+Finally, run the following command on any users laptop that needs to be able to
+deploy using this hook:
+
+{% highlight bash %}
+laptops$ git remote add deploy deployer@myserver.com:~/myrepo.git
+{% endhighlight %}
+
+Deploying is now as easy as telling nginx or Apache to look at
+`/var/www/myrepo` and running the following:
+
+{% highlight bash %}
+laptops$ git push deploy master
+{% endhighlight %}
+
+### Rake
+
+Another way to deploy your Jekyll site is to use [Rake](https://github.com/jimweirich/rake), [HighLine](https://github.com/JEG2/highline), and
+[Net::SSH](http://net-ssh.rubyforge.org/). A more complex example of deploying Jekyll with Rake that deals with multiple branches can be found in [Git Ready](https://github.com/gitready/gitready/blob/en/Rakefile).
+
+### rsync
+
+Once you’ve generated the `_site` directory, you can easily rsync it using a `tasks/deploy` shell script similar to [this deploy script here](http://github.com/henrik/henrik.nyh.se/blob/master/tasks/deploy). You’d obviously need to change the values to reflect your site’s details. There is even [a matching TextMate command](http://gist.github.com/214959) that will help you run
+this script from within Textmate.
+
+
+## Rack-Jekyll
+
+[Rack-Jekyll](http://github.com/bry4n/rack-jekyll/) is an easy way to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](http://github.com/rtomakyo/shotgun/), [rackup](http://github.com/rack/rack), [mongrel](http://github.com/mongrel/mongrel), [unicorn](http://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
+
+Read [this post](http://blog.crowdint.com/2010/08/02/instant-blog-using-jekyll-and-heroku.html) on how to deploy to Heroku using Rack-Jekyll.
+
+## Jekyll-Admin for Rails
+
+If you want to maintain Jekyll inside your existing Rails app, [Jekyll-Admin](http://github.com/zkarpinski/Jekyll-Admin) contains drop in code to make this possible. See Jekyll-Admin’s [README](http://github.com/zkarpinski/Jekyll-Admin/blob/master/README) for more details.
+
+## Amazon S3
+
+If you want to host your site in Amazon S3, you can do so with
+[s3_website](https://github.com/laurilehmijoki/s3_website) application. It will
+push your site to Amazon S3 where it can be served like any web server,
+dynamically scaling to almost unlimited traffic. This approach has the
+benefit of being about the cheapest hosting option available for
+low-volume blogs as you only pay for what you use.
+
+<div class="note">
+  <h5>ProTip™: Use GitHub Pages for zero-hassle Jekyll hosting</h5>
+  <p>GitHub Pages are powered by Jekyll behind the scenes, so if you’re looking for a zero-hassle, zero-cost solution, GitHub Pages are a great way to <a href="../github-pages/">host your Jekyll-powered website for free</a>.</p>
+</div>

data/site/docs/drafts.md

@@ -0,0 +1,20 @@
+---
+layout: docs
+title: Working with drafts
+permalink: /docs/drafts/
+---
+
+Drafts are posts without a date. They're posts you're still working on and don't want to
+publish yet. To get up and running with drafts, create a `_drafts` folder in your site's
+root (as described in the [site structure](/docs/structure/) section) and create your
+first draft:
+
+{% highlight text %}
+|-- _drafts/
+|   |-- a-draft-post.md
+{% endhighlight %}
+
+To preview your site with drafts, simply run `jekyll serve` or `jekyll build` with
+the `--drafts` switch.  Each will be assigned the value of `Time.now`
+for its date, and thus you will see them generated as the latest posts.
+

data/site/docs/extras.md

@@ -0,0 +1,56 @@
+---
+layout: docs
+title: Extras
+prev_section: plugins
+next_section: github-pages
+permalink: /docs/extras/
+---
+
+There are a number of (optional) extra features that Jekyll supports that you
+may want to install, depending on how you plan to use Jekyll.
+
+## LaTeX Support
+
+Maruku comes with optional support for LaTeX to PNG rendering via blahtex
+(Version 0.6) which must be in your `$PATH` along with `dvips`. If you need
+Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku
+fork](http://github.com/remi/maruku).
+
+## RDiscount
+
+If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead
+of [Maruku](http://github.com/bhollis/maruku) for Markdown, just make sure you have
+it installed:
+
+{% highlight bash %}
+$ [sudo] gem install rdiscount
+{% endhighlight %}
+
+And then specify RDiscount as the Markdown engine in your `_config.yml` file to
+have Jekyll run with that option.
+
+{% highlight yaml %}
+# In _config.yml
+markdown: rdiscount
+{% endhighlight %}
+
+## Kramdown
+
+You can also use [Kramdown](http://kramdown.rubyforge.org/) instead of Maruku
+for Markdown. Make sure that Kramdown is installed:
+
+{% highlight bash %}
+$ [sudo] gem install kramdown
+{% endhighlight %}
+
+Then you can specify Kramdown as the Markdown engine in `_config.yml`.
+
+{% highlight yaml %}
+# In _config.yml
+markdown: kramdown
+{% endhighlight %}
+
+Kramdown has various options for customizing the HTML output. The
+[Configuration](/docs/configuration/) page lists the default options used by
+Jekyll. A complete list of options is also available on the [Kramdown
+website](http://kramdown.rubyforge.org/options.html).

data/site/docs/frontmatter.md

@@ -0,0 +1,180 @@
+---
+layout: docs
+title: Front-matter
+prev_section: configuration
+next_section: posts
+permalink: /docs/frontmatter/
+---
+
+The front-matter is where Jekyll starts to get really cool. Any file that
+contains a [YAML](http://yaml.org/) front matter block will be processed by
+Jekyll as a special file. The front matter must be the first thing in the file
+and must take the form of valid YAML set between triple-dashed lines. Here is a
+basic example:
+
+{% highlight yaml %}
+---
+layout: post
+title: Blogging Like a Hacker
+---
+{% endhighlight %}
+
+Between these triple-dashed lines, you can set predefined variables (see below
+for a reference) or even create custom ones of your own. These variables will
+then be available to you to access using Liquid tags both further down in the
+file and also in any layouts or includes that the page or post in question
+relies on.
+
+<div class="note warning">
+  <h5>UTF-8 Character Encoding Warning</h5>
+  <p>
+    If you use UTF-8 encoding, make sure that no <code>BOM</code> header
+    characters exist in your files or very, very bad things will happen to
+    Jekyll. This is especially relevant if you’re running Jekyll on Windows.
+  </p>
+</div>
+
+<div class="note">
+  <h5>ProTip™: Front Matter Variables Are Optional</h5>
+  <p>
+    If you want to use <a href="../variables/">Liquid tags and variables</a> but
+    don’t need anything in your front-matter, just leave it empty! The set of
+    triple-dashed lines with nothing in between will still get Jekyll to process
+    your file. (This is useful for things like CSS and RSS feeds!)
+  </p>
+</div>
+
+## Predefined Global Variables
+
+There are a number of predefined global variables that you can set in the
+front-matter of a page or post.
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>layout</code></p>
+      </td>
+      <td>
+        <p>
+
+          If set, this specifies the layout file to use. Use the layout file
+          name without the file extension. Layout files must be placed in the
+          <code>_layouts</code> directory.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>permalink</code></p>
+      </td>
+      <td>
+        <p>
+
+          If you need your processed blog post URLs to be something other than
+          the default <code>/year/month/day/title.html</code> then you can set
+          this variable and it will be used as the final URL.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>published</code></p>
+      </td>
+      <td>
+        <p>
+          Set to false if you don’t want a specific post to show up when the
+          site is generated.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p style="margin-bottom: 5px;"><code>category</code></p>
+        <p><code>categories</code></p>
+      </td>
+      <td>
+        <p>
+
+          Instead of placing posts inside of folders, you can specify one or
+          more categories that the post belongs to. When the site is generated
+          the post will act as though it had been set with these categories
+          normally. Categories (plural key) can be specified as a <a
+          href="http://en.wikipedia.org/wiki/YAML#Lists">YAML list</a> or a
+          space-separated string.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>tags</code></p>
+      </td>
+      <td>
+        <p>
+
+          Similar to categories, one or multiple tags can be added to a post.
+          Also like categories, tags can be specified as a YAML list or a space-
+          separated string.
+
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+
+## Custom Variables
+
+Any variables in the front matter that are not predefined are mixed into the
+data that is sent to the Liquid templating engine during the conversion. For
+instance, if you set a title, you can use that in your layout to set the page
+title:
+
+{% highlight html %}
+<!DOCTYPE HTML>
+<html>
+  <head>
+    <title>{% raw %}{{ page.title }}{% endraw %}</title>
+  </head>
+  <body>
+    ...
+{% endhighlight %}
+
+## Predefined Variables for Posts
+
+These are available out-of-the-box to be used in the front-matter for a post.
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>date</code></p>
+      </td>
+      <td>
+        <p>
+          A date here overrides the date from the name of the post. This can be
+          used to ensure correct sorting of posts.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>

data/site/docs/github-pages.md

@@ -0,0 +1,91 @@
+---
+layout: docs
+title: GitHub Pages
+prev_section: extras
+next_section: deployment-methods
+permalink: /docs/github-pages/
+---
+
+[GitHub Pages](http://pages.github.com) are public web pages for users,
+organizations, and repositories, that are freely hosted on GitHub's
+[github.io]() domain or on a custom domain name of your choice. GitHub Pages are
+powered by Jekyll behind the scenes, so in addition to supporting regular HTML
+content, they’re also a great way to host your Jekyll-powered website for free.
+
+## Deploying Jekyll to GitHub Pages
+
+GitHub Pages work by looking at certain branches of repositories on GitHub.
+There are two basic types available: user/organization pages and project pages.
+The way to deploy these two types of sites are nearly identical, except for a
+few minor details.
+
+### User and Organization Pages
+
+User and organization pages live in a special GitHub repository dedicated to
+only the GitHub Pages files. This repository must be named after the account
+name. For example, [@mojombo’s user page
+repository](https://github.com/mojombo/mojombo.github.io) has the name
+`mojombo.github.io`.
+
+Content from the `master` branch of your repository will be used to build and
+publish the GitHub Pages site, so make sure your Jekyll site is stored there.
+
+<div class="note info">
+  <h5>Custom domains do not affect repository names</h5>
+  <p>
+    GitHub Pages are initially configured to live under the
+    <code>username.github.io</code> subdomain, which is why repositories must
+    be named this way <strong>even if a custom domain is being used</strong>.
+  </p>
+</div>
+
+### Project Pages
+
+Unlike user and organization Pages, Project Pages are kept in the same
+repository as the project they are for, except that the website content is
+stored in a specially named `gh-pages` branch. The content of this branch will
+be rendered using Jekyll, and the output will become available under a subpath
+of your user pages subdomain, such as `username.github.io/project` (unless a
+custom domain is specified—see below).
+
+The Jekyll project repository itself is a perfect example of this branch
+structure—the [master branch]({{ site.repository }}) contains the
+actual software project for Jekyll, however the Jekyll website (that you’re
+looking at right now) is contained in the [gh-pages
+branch]({{ site.repository }}/tree/gh-pages) of the same repository.
+
+### Project Page URL Structure
+
+Sometimes it's nice to preview your Jekyll site before you push your `gh-pages`
+branch to GitHub. However, the subdirectory-like URL structure GitHub uses for
+Project Pages complicates the proper resolution of URLs. Here is an approach to
+utilizing the GitHub Project Page URL structure (`username.github.io/project-name/`)
+whilst maintaining the ability to preview your Jekyll site locally.
+
+1. In `_config.yml`, set the `baseurl` option to `/project-name` -- note the
+   leading slash and the **absence** of a trailing slash.
+2. When referencing JS or CSS files, do it like this:
+   `{% raw %}{{ site.baseurl}}/path/to/css.css{% endraw %}` -- note the slash
+   immediately following the variable (just before "path").
+3. When doing permalinks or internal links, do it like this:
+   `{% raw %}{{ site.baseurl }}{{ post.url }}{% endraw %}` -- note that there
+   is **no** slash between the two variables.
+4. Finally, if you'd like to preview your site before committing/deploying using
+   `jekyll serve`, be sure to pass an **empty string** to the `--baseurl` option,
+   so that you can view everything at `localhost:4000` normally (without
+   `/project-name` at the beginning): `jekyll serve --baseurl ''`
+
+This way you can preview your site locally from the site root on localhost,
+but when GitHub generates your pages from the gh-pages branch all the URLs
+will start with `/project-name` and resolve properly.
+
+<div class="note">
+  <h5>GitHub Pages Documentation, Help, and Support</h5>
+  <p>
+    For more information about what you can do with GitHub Pages, as well as for
+    troubleshooting guides, you should check out <a
+    href="https://help.github.com/categories/20/articles">GitHub’s Pages Help
+    section</a>. If all else fails, you should contact <a
+    href="https://github.com/contact">GitHub Support</a>.
+  </p>
+</div>