monad 0.0.2 → 0.0.3

data/site/docs/templates.md

@@ -0,0 +1,319 @@
+---
+layout: docs
+title: Templates
+prev_section: migrations
+next_section: permalinks
+permalink: /docs/templates/
+---
+
+Jekyll uses the [Liquid](http://wiki.shopify.com/Liquid) templating language to
+process templates. All of the standard Liquid [tags](http://wiki.shopify.com/Logic) and
+[filters](http://wiki.shopify.com/Filters) are
+supported. Jekyll even adds a few handy filters and tags of its own to make
+common tasks easier.
+
+## Filters
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Description</th>
+      <th><span class="filter">Filter</span> and <span class="output">Output</span></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to XML Schema</strong></p>
+        <p>Convert a Date into XML Schema (ISO 8601) format.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ site.time | date_to_xmlschema }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>2008-11-17T13:07:54-08:00</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to RFC-822 Format</strong></p>
+        <p>Convert a Date into the RFC-822 format used for RSS feeds.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ site.time | date_to_rfc822 }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>Mon, 17 Nov 2008 13:07:54 -0800</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to String</strong></p>
+        <p>Convert a date to short format.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ site.time | date_to_string }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>17 Nov 2008</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to Long String</strong></p>
+        <p>Format a date to long format.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ site.time | date_to_long_string }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>17 November 2008</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>XML Escape</strong></p>
+        <p>Escape some text for use in XML.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ page.content | xml_escape }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>CGI Escape</strong></p>
+        <p>
+          CGI escape a string for use in a URL. Replaces any special characters
+          with appropriate %XX replacements.
+        </p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ “foo,bar;baz?” | cgi_escape }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>foo%2Cbar%3Bbaz%3F</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>URI Escape</strong></p>
+        <p>
+          URI escape a string.
+        </p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ “'foo, bar \\baz?'” | uri_escape }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>foo,%20bar%20%5Cbaz?</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Number of Words</strong></p>
+        <p>Count the number of words in some text.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ page.content | number_of_words }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>1337</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Array to Sentence</strong></p>
+        <p>Convert an array into a sentence. Useful for listing tags.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ page.tags | array_to_sentence_string }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>foo, bar, and baz</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Textilize</strong></p>
+        <p>Convert a Textile-formatted string into HTML, formatted via RedCloth</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ page.excerpt | textilize }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Markdownify</strong></p>
+        <p>Convert a Markdown-formatted string into HTML.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ page.excerpt | markdownify }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+## Tags
+
+### Includes
+
+If you have small page fragments that you wish to include in multiple places on
+your site, you can use the `include` tag.
+
+{% highlight ruby %}
+{% raw %}{% include footer.html %}{% endraw %}
+{% endhighlight %}
+
+Jekyll expects all include files to be placed in an `_includes` directory at the
+root of your source directory. This will embed the contents of
+`<source>/_includes/footer.html` into the calling file.
+
+<div class="note">
+  <h5>ProTip™: Use variables as file name</h5>
+  <p>
+
+    The name of the file you wish to embed can be literal (as in the example above),
+    or you can use a variable, using liquid-like variable syntax as in
+    <code>{% raw %}{% include {{my_variable}} %}{% endraw %}</code>.
+
+    Note that unlike usual liquid variable syntax, you cannot have spaces inside the curly braces.
+
+  </p>
+</div>
+
+You can also pass parameters to an include:
+
+{% highlight ruby %}
+{% raw %}{% include footer.html param="value" %}{% endraw %}
+{% endhighlight %}
+
+These parameters are available via Liquid in the include:
+
+{% highlight ruby %}
+{% raw %}{{ include.param }}{% endraw %}
+{% endhighlight %}
+
+### Code snippet highlighting
+
+Jekyll has built in support for syntax highlighting of [over 100
+languages](http://pygments.org/languages/) thanks to
+[Pygments](http://pygments.org/). To use Pygments, you must have Python installed on your
+system and set `pygments` to `true` in your site's configuration file.
+
+To render a code block with syntax highlighting, surround your code as follows:
+
+{% highlight text %}
+{% raw %}
+{% highlight ruby %}
+def foo
+  puts 'foo'
+end
+{% endhighlight %}
+{% endraw %}
+{% endhighlight %}
+
+The argument to the `highlight` tag (`ruby` in the example above) is the
+language identifier. To find the appropriate identifier to use for the language
+you want to highlight, look for the “short name” on the [Lexers
+page](http://pygments.org/docs/lexers/).
+
+#### Line numbers
+
+There is a second argument to `highlight` called `linenos` that is optional.
+Including the `linenos` argument will force the highlighted code to include line
+numbers. For instance, the following code block would include line numbers next
+to each line:
+
+{% highlight text %}
+{% raw %}
+{% highlight ruby linenos %}
+def foo
+  puts 'foo'
+end
+{% endhighlight %}
+{% endraw %}
+{% endhighlight %}
+
+#### Stylesheets for syntax highlighting
+
+In order for the highlighting to show up, you’ll need to include a highlighting
+stylesheet. For an example stylesheet you can look at
+[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css). These
+are the same styles as used by GitHub and you are free to use them for your own
+site. If you use `linenos`, you might want to include an additional CSS class
+definition for the `.lineno` class in `syntax.css` to distinguish the line
+numbers from the highlighted code.
+
+### Post URL
+
+If you would like to include a link to a post on your site, the `post_url` tag
+will generate the correct permalink URL for the post you specify.
+
+{% highlight text %}
+{% raw %}
+{% post_url 2010-07-21-name-of-post %}
+{% endraw %}
+{% endhighlight %}
+
+There is no need to include the file extension when using the `post_url` tag.
+
+You can also use this tag to create a link to a post in Markdown as follows:
+
+{% highlight text %}
+{% raw %}
+[Name of Link]({% post_url 2010-07-21-name-of-post %})
+{% endraw %}
+{% endhighlight %}
+
+### Gist
+
+Use the `gist` tag to easily embed a GitHub Gist onto your site:
+
+{% highlight text %}
+{% raw %}
+{% gist 5555251 %}
+{% endraw %}
+{% endhighlight %}
+
+You may also optionally specify the filename in the gist to display:
+
+{% highlight text %}
+{% raw %}
+{% gist 5555251 result.md %}
+{% endraw %}
+{% endhighlight %}
+
+The `gist` tag also works with private gists, which require the gist owner's
+github username:
+
+{% highlight text %}
+{% raw %}
+{% gist parkr/931c1c8d465a04042403 %}
+{% endraw %}
+{% endhighlight %}
+
+The private gist syntax also supports filenames.

data/site/docs/troubleshooting.md

@@ -0,0 +1,150 @@
+---
+layout: docs
+title: Troubleshooting
+prev_section: deployment-methods
+next_section: sites
+permalink: /docs/troubleshooting/
+---
+
+If you ever run into problems installing or using Jekyll, here's a few tips
+that might be of help. If the problem you’re experiencing isn’t covered below,
+please [report an issue]({{ site.repository }}/issues/new) so the
+Jekyll community can make everyone’s experience better.
+
+## Installation Problems
+
+If you encounter errors during gem installation, you may need to install
+the header files for compiling extension modules for ruby 1.9.1. This
+can be done on Ubuntu or Debian by running:
+
+{% highlight bash %}
+sudo apt-get install ruby1.9.1-dev
+{% endhighlight %}
+
+On Red Hat, CentOS, and Fedora systems you can do this by running:
+
+{% highlight bash %}
+sudo yum install ruby-devel
+{% endhighlight %}
+
+On [NearlyFreeSpeech](http://nearlyfreespeech.net/) you need to run the
+command with the following environment variable:
+
+{% highlight bash %}
+RB_USER_INSTALL=true gem install jekyll
+{% endhighlight %}
+
+On OSX, you may need to update RubyGems:
+
+{% highlight bash %}
+sudo gem update --system
+{% endhighlight %}
+
+If you still have issues, you may need to [use XCode to install Command Line
+Tools](http://www.zlu.me/blog/2012/02/21/install-native-ruby-gem-in-mountain-lion-preview/)
+that will allow you to install native gems using the following command:
+
+{% highlight bash %}
+sudo gem install jekyll
+{% endhighlight %}
+
+To install RubyGems on Gentoo:
+
+{% highlight bash %}
+sudo emerge -av dev-ruby/rubygems
+{% endhighlight %}
+
+On Windows, you may need to install [RubyInstaller
+DevKit](http://wiki.github.com/oneclick/rubyinstaller/development-kit).
+
+## Problems running Jekyll
+
+On Debian or Ubuntu, you may need to add `/var/lib/gems/1.8/bin/` to your path
+in order to have the `jekyll` executable be available in your Terminal.
+
+## Base-URL Problems
+
+If you are using base-url option like:
+
+{% highlight bash %}
+jekyll serve --baseurl '/blog'
+{% endhighlight %}
+
+… then make sure that you access the site at:
+
+{% highlight bash %}
+http://localhost:4000/blog/index.html
+{% endhighlight %}
+
+It won’t work to just access:
+
+{% highlight bash %}
+http://localhost:4000/blog
+{% endhighlight %}
+
+## Configuration problems
+
+The order of precedence for conflicting [configuration settings](../configuration/)
+is as follows:
+
+1.  Command-line flags
+2.  Configuration file settings
+3.  Defaults
+
+That is: defaults are overridden by options specified in `_config.yml`,
+and flags specified at the command-line will override all other settings
+specified elsewhere.
+
+## Markup Problems
+
+The various markup engines that Jekyll uses may have some issues. This
+page will document them to help others who may run into the same
+problems.
+
+### Maruku
+
+If your link has characters that need to be escaped, you need to use
+this syntax:
+
+{% highlight text %}
+![Alt text](http://yuml.me/diagram/class/[Project]->[Task])
+{% endhighlight %}
+
+If you have an empty tag, i.e. `<script src="js.js"></script>`, Maruku
+transforms this into `<script src="js.js" />`. This causes problems in
+Firefox and possibly other browsers and is [discouraged in
+XHTML.](http://www.w3.org/TR/xhtml1/#C_3) An easy fix is to put a space
+between the opening and closing tags.
+
+### RedCloth
+
+Versions 4.1.1 and higher do not obey the notextile tag. [This is a known
+bug](http://aaronqian.com/articles/2009/04/07/redcloth-ate-my-notextile.html)
+and will hopefully be fixed for 4.2. You can still use 4.1.9, but the
+test suite requires that 4.1.0 be installed. If you use a version of
+RedCloth that does not have the notextile tag, you may notice that
+syntax highlighted blocks from Pygments are not formatted correctly,
+among other things. If you’re seeing this just install 4.1.0.
+
+### Liquid
+
+The latest version, version 2.0, seems to break the use of `{{ "{{" }}` in
+templates. Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the
+following error:
+
+{% highlight bash %}
+'{{ "{{" }}' was not properly terminated with regexp: /\}\}/  (Liquid::SyntaxError)
+{% endhighlight %}
+
+### Excerpts
+
+Since v1.0.0, Jekyll has had automatically-generated post excerpts. Since
+v1.1.0, Jekyll also passes these excerpts through Liquid, which can cause
+strange errors where references don't exist or a tag hasn't been closed. If you
+run into these errors, try setting `excerpt_separator: ""` in your
+`_config.yml`, or set it to some nonsense string.
+
+<div class="note">
+  <h5>Please report issues you encounter!</h5>
+  <p>If you come across a bug, please <a href="{{ site.repository }}/issues/new">create an issue</a> on GitHub describing the problem and any work-arounds you find so we can document it here for others.</p>
+</div>