monad 0.0.2 → 0.0.3

data/site/docs/index.md

@@ -0,0 +1,52 @@
+---
+layout: docs
+title: Welcome
+next_section: quickstart
+permalink: /docs/home/
+---
+
+This site aims to be a comprehensive guide to Jekyll. We’ll cover topics such
+as getting your site up and running, creating and managing your content,
+customizing the way your site works and looks, deploying to various
+environments, and give you some advice on participating in the future
+development of Jekyll itself.
+
+## So what is Jekyll, exactly?
+
+Jekyll is a simple, blog-aware, static site generator. It takes a template
+directory containing raw text files in various formats, runs it through
+[Markdown](http://daringfireball.net/projects/markdown/) (or
+[Textile](http://textile.sitemonks.com/)) and
+[Liquid](http://wiki.shopify.com/Liquid)
+converters, and spits out a complete, ready-to-publish static website suitable
+for serving with your favorite web server. Jekyll also happens to be the engine
+behind [GitHub Pages](http://pages.github.com), which means you can use Jekyll
+to host your project’s page, blog, or website from GitHub’s servers **for
+free**.
+
+## ProTips™, Notes, and Warnings
+
+Throughout this guide there are a number of small-but-handy pieces of
+information that can make using Jekyll easier, more interesting, and less
+hazardous. Here’s what to look out for.
+
+<div class="note">
+  <h5>ProTips™ help you get more from Jekyll</h5>
+  <p>These are tips and tricks that will help you be a Jekyll wizard!</p>
+</div>
+
+<div class="note info">
+  <h5>Notes are handy pieces of information</h5>
+  <p>These are for the extra tidbits sometimes necessary to understand
+     Jekyll.</p>
+</div>
+
+<div class="note warning">
+  <h5>Warnings help you not blow things up</h5>
+  <p>Be aware of these messages if you wish to avoid certain death.</p>
+</div>
+
+If you come across anything along the way that we haven’t covered, or if you
+know of a tip you think others would find handy, please [file an
+issue]({{ site.repository }}/issues/new) and we’ll see about
+including it in this guide.

data/site/docs/installation.md

@@ -0,0 +1,76 @@
+---
+layout: docs
+title: Installation
+prev_section: quickstart
+next_section: usage
+permalink: /docs/installation/
+---
+
+Getting Jekyll installed and ready-to-go should only take a few minutes. If it
+ever becomes a pain in the ass, please [file an
+issue]({{ site.repository }}/issues/new) (or submit a pull request)
+describing the issue you encountered and how we might make the process easier.
+
+### Requirements
+
+Installing Jekyll is easy and straight-forward, but there are a few requirements
+you’ll need to make sure your system has before you start.
+
+- [Ruby](http://www.ruby-lang.org/en/downloads/)
+- [RubyGems](http://rubygems.org/pages/download)
+- Linux, Unix, or Mac OS X
+
+<div class="note info">
+  <h5>Running Jekyll on Windows</h5>
+  <p>
+    It is possible to get
+    <a href="http://www.madhur.co.in/blog/2011/09/01/runningjekyllwindows.html">
+    Jekyll running on Windows</a>, but the official documentation does not
+    support installation on Windows platforms.
+  </p>
+</div>
+
+## Install with RubyGems
+
+The best way to install Jekyll is via
+[RubyGems](http://docs.rubygems.org/read/chapter/3). At the terminal prompt,
+simply run the following command to install Jekyll:
+
+{% highlight bash %}
+$ gem install jekyll
+{% endhighlight %}
+
+All of Jekyll’s gem dependencies are automatically installed by the above
+command, so you won’t have to worry about them at all. If you have problems
+installing Jekyll, check out the [troubleshooting](../troubleshooting/) page or
+[report an issue]({{ site.repository }}/issues/new) so the Jekyll
+community can improve the experience for everyone.
+
+<div class="note info">
+  <h5>Installing Xcode Command-Line Tools</h5>
+  <p>
+    If you run into issues installing Jekyll's dependencies which make use of
+    native extensions and are using Mac OS X, you will need to install Xcode
+    and the Command-Line Tools it ships with. Download in
+    <code>Preferences &#8594; Downloads &#8594; Components</code>.
+  </p>
+</div>
+
+## Optional 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. These extras
+include LaTeX support, and the use of alternative content rendering engines.
+Check out [the extras page](../extras/) for more information.
+
+<div class="note">
+  <h5>ProTip™: Enable Syntax Highlighting</h5>
+  <p>
+    If you’re the kind of person who is using Jekyll, then chances are you’ll
+    want to enable syntax highlighting using Pygments. You should really
+    <a href="../templates/#code_snippet_highlighting">check out how to do
+    that</a> before you go any further.
+  </p>
+</div>
+
+Now that you’ve got everything installed, let’s get to work!

data/site/docs/migrations.md

@@ -0,0 +1,257 @@
+---
+layout: docs
+title: Blog migrations
+prev_section: datafiles
+next_section: templates
+permalink: /docs/migrations/
+---
+
+If you’re switching to Jekyll from another blogging system, Jekyll’s importers
+can help you with the move. Most methods listed on this page require read access
+to the database from your old system to generate posts for Jekyll. Each method
+generates `.markdown` posts in the `_posts` directory based on the entries in
+the foreign system.
+
+## Preparing for migrations
+
+Because the importers have many of their own dependencies, they are made
+available via a separate gem called
+[`jekyll-import`](https://github.com/jekyll/jekyll-import). To use them, all
+you need to do is install the gem, and they will become available as part of
+Jekyll's standard command line interface.
+
+{% highlight bash %}
+$ gem install jekyll-import --pre
+{% endhighlight %}
+
+<div class="note warning">
+  <h5>Jekyll-import requires you to manually install some dependencies.</h5>
+  <p markdown="1">If you are importing your blog from Drupal 6,7, Joomla,
+  Mephisto, Movable Type, Textpattern, or Typo (with mysql db), you need to install
+  `mysql` and `sequel` gems. If you are importing from a WordPress database, you
+  need to install `mysql2` and `sequel` gems, and if you are importing from Enki
+  or Typo (with postgresql db) you need to install `pg` and `sequel` gems.</p>
+</div>
+
+You should now be all set to run the importers below. If you ever get stuck, you
+can see help for each importer:
+
+{% highlight bash %}
+$ jekyll help import           # => See list of importers
+$ jekyll help import IMPORTER  # => See importer specific help
+{% endhighlight %}
+
+Where IMPORTER is the name of the specific importer.
+
+<div class="note info">
+  <h5>Note: Always double-check migrated content</h5>
+  <p>
+
+    Importers may not distinguish between published or private posts, so
+    you should always check that the content Jekyll generates for you appears as
+    you intended.
+
+  </p>
+</div>
+
+<!-- TODO all these need to be fixed -->
+
+## WordPress
+
+### WordPress export files
+
+If hpricot is not already installed, you will need to run `gem install hpricot`.
+Next, export your blog using the WordPress export utility. Assuming that the
+exported file is saved as `wordpress.xml`, here is the command you need to run:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/wordpressdotcom";
+    JekyllImport::WordpressDotCom.process({ :source => "wordpress.xml" })'
+{% endhighlight %}
+
+<div class="note">
+  <h5>ProTip™: WordPress.com Export Tool</h5>
+  <p markdown="1">If you are migrating from a WordPress.com account, you can
+  access the export tool at the following URL:
+  `https://YOUR-USER-NAME.wordpress.com/wp-admin/export.php`.</p>
+</div>
+
+### Using WordPress MySQL server connection
+
+If you want to import using a direct connection to the WordPress MySQL server,
+here's how:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/wordpress";
+    JekyllImport::WordPress.process({:dbname => "database", :user => "user", :pass => "pass"})'
+{% endhighlight %}
+
+If you are using Webfaction and have to set up an [SSH
+tunnel](http://docs.webfaction.com/user-guide/databases.html?highlight=mysql#starting-an-ssh-tunnel-with-ssh),
+be sure to make the hostname (`127.0.0.1`) explicit, otherwise MySQL may block
+your access based on `localhost` and `127.0.0.1` not being equivalent in its
+authentication system:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/wordpress";
+    JekyllImport::WordPress.process({:host => "127.0.0.1", :dbname => "database", :user => "user", :pass => "pass"})'
+{% endhighlight %}
+
+### Further WordPress migration alternatives
+
+While the above methods work, they do not import much of the metadata that is
+usually stored in WordPress posts and pages. If you need to export things like
+pages, tags, custom fields, image attachments and so on, the following resources
+might be useful to you:
+
+- [Exitwp](https://github.com/thomasf/exitwp) is a configurable tool written in
+  Python for migrating one or more WordPress blogs into Jekyll (Markdown) format
+  while keeping as much metadata as possible. Exitwp also downloads attachments
+  and pages.
+- [A great
+  article](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/) with a
+  step-by-step guide for migrating a WordPress blog to Jekyll while keeping most
+  of the structure and metadata.
+- [wpXml2Jekyll](https://github.com/theaob/wpXml2Jekyll) is an executable
+  windows application for creating Markdown posts from your WordPress XML file.
+
+## Drupal
+
+If you’re migrating from [Drupal](http://drupal.org), there are two migrators
+for you, depending upon your Drupal version:
+- [Drupal 6](https://github.com/jekyll/jekyll-import/blob/v0.1.0.beta1/lib/jekyll/jekyll-import/drupal6.rb)
+- [Drupal 7](https://github.com/jekyll/jekyll-import/blob/v0.1.0.beta1/lib/jekyll/jekyll-import/drupal7.rb)
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal6";
+    JekyllImport::Drupal6.process("dbname", "user", "pass")'
+# ... or ...
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal7";
+    JekyllImport::Drupal7.process("dbname", "user", "pass")'
+{% endhighlight %}
+
+If you are connecting to a different host or need to specify a table prefix for
+your database, you may optionally add those two parameters to the end of either
+Drupal migrator execution:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal6";
+    JekyllImport::Drupal6.process("dbname", "user", "pass", "host", "table_prefix")'
+# ... or ...
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal7";
+    JekyllImport::Drupal7.process("dbname", "user", "pass", "host", "table_prefix")'
+{% endhighlight %}
+
+## Movable Type
+
+To import posts from Movable Type:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/mt";
+    JekyllImport::MT.process("database", "user", "pass")'
+{% endhighlight %}
+
+## Typo
+
+To import posts from Typo:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/typo";
+    JekyllImport::Typo.process("database", "user", "pass")'
+{% endhighlight %}
+
+This code has only been tested with Typo version 4+.
+
+## TextPattern
+
+To import posts from TextPattern:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/textpattern";
+    JekyllImport::TextPattern.process("database_name", "username", "password", "hostname")'
+{% endhighlight %}
+
+You will need to run the above from the parent directory of your `_import`
+folder. For example, if `_import` is located in `/path/source/_import`, you will
+need to run this code from `/path/source`. The hostname defaults to `localhost`,
+all other variables are required. You may need to adjust the code used to filter
+entries. Left alone, it will attempt to pull all entries that are live or
+sticky.
+
+## Mephisto
+
+To import posts from Mephisto:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/mephisto";
+    JekyllImport::Mephisto.process("database", "user", "password")'
+{% endhighlight %}
+
+If your data is in Postgres, you should do this instead:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/mephisto";
+    JekyllImport::Mephisto.postgres({:database => "database", :username=>"username", :password =>"password"})'
+{% endhighlight %}
+
+## Blogger (Blogspot)
+
+To import posts from Blogger, see [this post about migrating from Blogger to
+Jekyll](http://blog.coolaj86.com/articles/migrate-from-blogger-to-jekyll.html). If
+that doesn’t work for you, you might want to try some of the following
+alternatives:
+
+- [@kennym](https://github.com/kennym) created a [little migration
+  script](https://gist.github.com/1115810), because the solutions in the
+  previous article didn't work out for him.
+- [@ngauthier](https://github.com/ngauthier) created [another
+  importer](https://gist.github.com/1506614) that imports comments, and does so
+  via blogger’s archive instead of the RSS feed.
+- [@juniorz](https://github.com/juniorz) created [yet another
+  importer](https://gist.github.com/1564581) that works for
+  [Octopress](http://octopress.org). It is like [@ngauthier’s
+  version](https://gist.github.com/1506614) but separates drafts from posts, as
+  well as importing tags and permalinks.
+
+## Posterous
+
+To import posts from your primary Posterous blog:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/posterous";
+    JekyllImport::Posterous.process("my_email", "my_pass")'
+{% endhighlight %}
+
+For any other Posterous blog on your account, you will need to specify the
+`blog_id` for the blog:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/posterous";
+    JekyllImport::Posterous.process("my_email", "my_pass", "blog_id")'
+{% endhighlight %}
+
+There is also an [alternative Posterous
+migrator](https://github.com/pepijndevos/jekyll/blob/patch-1/lib/jekyll/migrators/posterous.rb)
+that maintains permalinks and attempts to import images too.
+
+## Tumblr
+
+To import posts from Tumblr:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/tumblr";
+    JekyllImport::Tumblr.process(url, format, grab_images, add_highlights, rewrite_urls)'
+# url    - String: your blog's URL
+# format - String: the output file extension. Use "md" to have your content
+#          converted from HTML to Markdown. Defaults to "html".
+# grab_images    - Boolean: whether to download images as well. Defaults to false.
+# add_highlights - Boolean: whether to wrap code blocks (indented 4 spaces) in a Liquid
+                   "highlight" tag. Defaults to false.
+# rewrite_urls   - Boolean: whether to write pages that redirect from the old Tumblr paths
+                   to the new Jekyll paths. Defaults to false.
+{% endhighlight %}
+
+## Other Systems
+
+If you have a system for which there is currently no migrator, consider writing
+one and sending us [a pull request](https://github.com/jekyll/jekyll-import).

data/site/docs/pages.md

@@ -0,0 +1,86 @@
+---
+layout: docs
+title: Creating pages
+prev_section: posts
+next_section: variables
+permalink: /docs/pages/
+---
+
+In addition to [writing posts](../posts/), another thing you may want to do with
+your Jekyll site is create static pages. By taking advantage of the way Jekyll
+copies files and directories, this is easy to do.
+
+## Homepage
+
+Just about every web server configuration you come across will look for an HTML
+file called `index.html` (by convention) in the site's root folder and display
+that as the homepage. Unless the web server you’re using is configured to look
+for some different filename as the default, this file will turn into the
+homepage of your Jekyll-generated site.
+
+<div class="note">
+  <h5>ProTip™: Use layouts on your homepage</h5>
+  <p>
+    Any HTML file on your site can use layouts and/or includes, even the
+    homepage. Common content, like headers and footers, make excellent
+    candidates for extraction into a layout.
+  </p>
+</div>
+
+## Where additional pages live
+
+Where you put HTML files for pages depends on how you want the pages to work.
+There are two main ways of creating pages:
+
+- Place named HTML files for each page in your site's root folder.
+- Create a folder in the site's root for each page, and place an index.html file
+  in each page folder.
+
+Both methods work fine (and can be used in conjunction with each other),
+with the only real difference being the resulting URLs.
+
+### Named HTML files
+
+The simplest way of adding a page is just to add an HTML file in the root
+directory with a suitable name for the page you want to create. For a site with
+a homepage, an about page, and a contact page, here’s what the root directory
+and associated URLs might look like:
+
+{% highlight bash %}
+.
+|-- _config.yml
+|-- _includes/
+|-- _layouts/
+|-- _posts/
+|-- _site/
+|-- about.html    # => http://yoursite.com/about.html
+|-- index.html    # => http://yoursite.com/
+└── contact.html  # => http://yoursite.com/contact.html
+{% endhighlight %}
+
+### Named folders containing index HTML files
+
+There is nothing wrong with the above method, however some people like to keep
+their URLs free from things like filename extensions. To achieve clean URLs for
+pages using Jekyll, you simply need to create a folder for each top-level page
+you want, and then place an `index.html` file in each page’s folder. This way
+the page URL ends up being the folder name, and the web server will serve up the
+respective `index.html` file. Here's an example of what this structure might
+look like:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _includes/
+├── _layouts/
+├── _posts/
+├── _site/
+├── about/
+|   └── index.html  # => http://yoursite.com/about/
+├── contact/
+|   └── index.html  # => http://yoursite.com/contact/
+└── index.html      # => http://yoursite.com/
+{% endhighlight %}
+
+This approach may not suit everyone, but for people who like clean URLs it’s
+simple and it works. In the end the decision is yours!