monad 0.0.2 → 0.0.3

data/site/docs/posts.md

@@ -0,0 +1,181 @@
+---
+layout: docs
+title: Writing posts
+prev_section: frontmatter
+next_section: pages
+permalink: /docs/posts/
+---
+
+One of Jekyll’s best aspects is that it is “blog aware”. What does this mean,
+exactly? Well, simply put, it means that blogging is baked into Jekyll’s
+functionality. If you write articles and publish them online, this means that
+you can publish and maintain a blog simply by managing a folder of text-files on
+your computer. Compared to the hassle of configuring and maintaining databases
+and web-based CMS systems, this will be a welcome change!
+
+## The Posts Folder
+
+As explained on the [directory structure](../structure/) page, the `_posts`
+folder is where your blog posts will live. These files can be either
+[Markdown](http://daringfireball.net/projects/markdown/) or
+[Textile](http://textile.sitemonks.com/) formatted text files, and as long as
+they have [YAML front-matter](../frontmatter/), they will be converted from their
+source format into an HTML page that is part of your static site.
+
+### Creating Post Files
+
+To create a new post, all you need to do is create a new file in the `_posts`
+directory. How you name files in this folder is important. Jekyll requires blog
+post files to be named according to the following format:
+
+{% highlight bash %}
+YEAR-MONTH-DAY-title.MARKUP
+{% endhighlight %}
+
+Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit
+numbers, and `MARKUP` is the file extension representing the format used in the
+file. For example, the following are examples of valid post filenames:
+
+{% highlight bash %}
+2011-12-31-new-years-eve-is-awesome.md
+2012-09-12-how-to-write-a-blog.textile
+{% endhighlight %}
+
+### Content Formats
+
+All blog post files must begin with [YAML front- matter](../frontmatter/). After
+that, it's simply a matter of deciding which format you prefer. Jekyll supports
+two popular content markup formats:
+[Markdown](http://daringfireball.net/projects/markdown/) and
+[Textile](http://textile.sitemonks.com/). These formats each have their own way
+of marking up different types of content within a post, so you should
+familiarize yourself with these formats and decide which one best suits your
+needs.
+
+## Including images and resources
+
+Chances are, at some point, you'll want to include images, downloads, or other
+digital assets along with your text content. While the syntax for linking to
+these resources differs between Markdown and Textile, the problem of working out
+where to store these files in your site is something everyone will face.
+
+Because of Jekyll’s flexibility, there are many solutions to how to do this. One
+common solution is to create a folder in the root of the project directory
+called something like `assets` or `downloads`, into which any images, downloads
+or other resources are placed. Then, from within any post, they can be linked to
+using the site’s root as the path for the asset to include. Again, this will
+depend on the way your site’s (sub)domain and path are configured, but here some
+examples (in Markdown) of how you could do this using the `site.url` variable in
+a post.
+
+Including an image asset in a post:
+
+{% highlight text %}
+… which is shown in the screenshot below:
+![My helpful screenshot]({% raw %}{{ site.url }}{% endraw %}/assets/screenshot.jpg)
+{% endhighlight %}
+
+Linking to a PDF for readers to download:
+
+{% highlight text %}
+… you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly.
+{% endhighlight %}
+
+<div class="note">
+  <h5>ProTip™: Link using just the site root URL</h5>
+  <p>
+    You can skip the <code>{% raw %}{{ site.url }}{% endraw %}</code> variable
+    if you <strong>know</strong> your site will only ever be displayed at the
+    root URL of your domain. In this case you can reference assets directly with
+    just <code>/path/file.jpg</code>.
+  </p>
+</div>
+
+## Displaying an index of posts
+
+It’s all well and good to have posts in a folder, but a blog is no use unless
+you have a list of posts somewhere. Creating an index of posts on another page
+(or in a [template](../templates/)) is easy, thanks to the [Liquid template
+language](http://wiki.shopify.com/Liquid) and its tags. Here’s a basic example of how
+to create a list of links to your blog posts:
+
+{% highlight html %}
+<ul>
+  {% raw %}{% for post in site.posts %}{% endraw %}
+    <li>
+      <a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
+    </li>
+  {% raw %}{% endfor %}{% endraw %}
+</ul>
+{% endhighlight %}
+
+Of course, you have full control over how (and where) you display your posts,
+and how you structure your site. You should read more about [how templates
+work](../templates/) with Jekyll if you want to know more.
+
+## Post excerpts
+
+Each post automatically takes the first block of text, from the beginning of the content
+to the first occurrence of `excerpt_separator`, and sets it as the `post.excerpt`.
+Take the above example of an index of posts. Perhaps you want to include
+a little hint about the post's content by adding the first paragraph of each of your
+posts:
+
+{% highlight html %}
+<ul>
+  {% raw %}{% for post in site.posts %}{% endraw %}
+    <li>
+      <a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
+      <p>{% raw %}{{ post.excerpt }}{% endraw %}</p>
+    </li>
+  {% raw %}{% endfor %}{% endraw %}
+</ul>
+{% endhighlight %}
+
+If you don't like the automatically-generated post excerpt, it can be overridden by adding
+`excerpt` to your post's YAML front-matter. Completely disable it by setting
+your `excerpt_separator` to `""`.
+
+## Highlighting code snippets
+
+Jekyll also has built-in support for syntax highlighting of code snippets using
+Pygments, and including a code snippet in any post is easy. Just use the
+dedicated Liquid tag as follows:
+
+{% highlight text %}
+{% raw %}{% highlight ruby %}{% endraw %}
+def show
+  @widget = Widget(params[:id])
+  respond_to do |format|
+    format.html # show.html.erb
+    format.json { render json: @widget }
+  end
+end
+{% raw %}{% endhighlight %}{% endraw %}
+{% endhighlight %}
+
+And the output will look like this:
+
+{% highlight ruby %}
+def show
+  @widget = Widget(params[:id])
+  respond_to do |format|
+    format.html # show.html.erb
+    format.json { render json: @widget }
+  end
+end
+{% endhighlight %}
+
+<div class="note">
+  <h5>ProTip™: Show line numbers</h5>
+  <p>
+    You can make code snippets include line-numbers by adding the word
+    <code>linenos</code> to the end of the opening highlight tag like this:
+    <code>{% raw %}{% highlight ruby linenos %}{% endraw %}</code>.
+  </p>
+</div>
+
+These basics should be enough to get you started writing your first posts. When
+you’re ready to dig into what else is possible, you might be interested in doing
+things like [customizing post permalinks](../permalinks/) or using [custom
+variables](../variables/) in your posts and elsewhere on your site.

data/site/docs/quickstart.md

@@ -0,0 +1,32 @@
+---
+layout: docs
+title: Quick-start guide
+prev_section: home
+next_section: installation
+permalink: /docs/quickstart/
+---
+
+For the impatient, here's how to get a boilerplate Jekyll site up and running.
+
+{% highlight bash %}
+~ $ gem install jekyll
+~ $ jekyll new myblog
+~ $ cd myblog
+~/myblog $ jekyll serve
+# => Now browse to http://localhost:4000
+{% endhighlight %}
+
+That's nothing, though. The real magic happens when you start creating blog
+posts, using the front-matter to control templates and layouts, and taking
+advantage of all the awesome configuration options Jekyll makes available.
+
+<div class="note info">
+  <h5>Redcarpet is the default Markdown engine for new sites</h5>
+  <p>In Jekyll 1.1, we switched the default markdown engine for sites
+     generated with <code>jekyll new</code> to Redcarpet</p>
+</div>
+
+If you're running into problems, ensure you have all the [requirements
+installed][Installation].
+
+[Installation]: /docs/installation/

data/site/docs/resources.md

@@ -0,0 +1,46 @@
+---
+layout: docs
+title: Resources
+prev_section: sites
+next_section: upgrading
+permalink: /docs/resources/
+---
+
+Jekyll’s growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources.
+
+### Jekyll tips & tricks, and examples
+
+- [Tips for working with GitHub Pages Integration](https://gist.github.com/2890453)
+
+  Code example reuse, and keeping documentation up to date.
+
+- [Use Simple Form to integrate a simple contact
+  form](http://getsimpleform.com/)
+- [JekyllBootstrap.com](http://jekyllbootstrap.com)
+
+  Provides detailed explanations, examples, and helper-code to make
+  getting started with Jekyll easier.
+
+### Tutorials
+
+#### Integrating Jekyll with Git
+
+- [Blogging with Git, Emacs and Jekyll](http://metajack.im/2009/01/23/blogging-with-git-emacs-and-jekyll/)
+
+#### Other hacks
+
+- [Integrating Twitter with Jekyll](http://www.justkez.com/integrating-twitter-with-jekyll/)
+  > “Having migrated Justkez.com to be based on Jekyll, I was pondering how I might include my recent twitterings on the front page of the site. In the WordPress world, this would have been done via a plugin which may or may not have hung the loading of the page, might have employed caching, but would certainly have had some overheads. … Not in Jekyll.”
+- [‘My Jekyll Fork’, by Mike West](http://mikewest.org/2009/11/my-jekyll-fork)
+  > “Jekyll is a well-architected throwback to a time before WordPress, when men were men, and HTML was static. I like the ideas it espouses, and have made a few improvements to it’s core. Here, I’ll point out some highlights of my fork in the hopes that they see usage beyond this site.”
+- [‘About this Website’, by Carter Allen](http://cartera.me/2010/08/12/about-this-website/)
+  > “Jekyll is everything that I ever wanted in a blogging engine. Really. It isn’t perfect, but what’s excellent about it is that if there’s something wrong, I know exactly how it works and how to fix it. It runs on the your machine only, and is essentially an added”build" step between you and the browser. I coded this entire site in TextMate using standard HTML5 and CSS3, and then at the end I added just a few little variables to the markup. Presto-chango, my site is built and I am at peace with the world.”
+- [Generating a Tag Cloud in Jekyll](http://www.justkez.com/generating-a-tag-cloud-in-jekyll/)
+
+  A guide to implementing a tag cloud and per-tag content pages using Jekyll.
+
+- [Jekyll Extensions -= Pain](http://rfelix.com/2010/01/19/jekyll-extensions-minus-equal-pain/)
+
+  A way to [extend Jekyll](http://github.com/rfelix/jekyll_ext) without forking and modifying the Jekyll gem codebase and some [portable Jekyll extensions](http://wiki.github.com/rfelix/jekyll_ext/extensions) that can be reused and shared.
+
+- [Using your Rails layouts in Jekyll](http://numbers.brighterplanet.com/2010/08/09/sharing-rails-views-with-jekyll)

data/site/docs/sites.md

@@ -0,0 +1,29 @@
+---
+layout: docs
+title: Sites using Jekyll
+prev_section: troubleshooting
+next_section: resources
+permalink: /docs/sites/
+---
+
+It’s 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]: {{ site.repository }}/wiki/Sites

data/site/docs/structure.md

@@ -0,0 +1,190 @@
+---
+layout: docs
+title: Directory structure
+prev_section: usage
+next_section: configuration
+permalink: /docs/structure/
+---
+
+Jekyll is, at its core, a text transformation engine. The concept behind the
+system is this: you give it text written in your favorite markup language, be
+that Markdown, Textile, or just plain HTML, and it churns that through a layout
+or series of layout files. Throughout that process you can tweak how you want
+the site URLs to look, what data gets displayed in the layout, and more. This is
+all done through editing text files, and the static web site is the final
+product.
+
+A basic Jekyll site usually looks something like this:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _drafts
+|   ├── begin-with-the-crazy-ideas.textile
+|   └── on-simplicity-in-technology.markdown
+├── _includes
+|   ├── footer.html
+|   └── header.html
+├── _layouts
+|   ├── default.html
+|   └── post.html
+├── _posts
+|   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
+|   └── 2009-04-26-barcamp-boston-4-roundup.textile
+├── _data
+|   └── members.yml
+├── _site
+└── index.html
+{% endhighlight %}
+
+An overview of what each of these does:
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>File / Directory</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>_config.yml</code></p>
+      </td>
+      <td>
+        <p>
+
+          Stores <a href="../configuration/">configuration</a> data. Many of
+          these options can be specified from the command line executable but
+          it’s easier to specify them here so you don’t have to remember them.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_drafts</code></p>
+      </td>
+      <td>
+        <p>
+
+          Drafts are unpublished posts. The format of these files is without a date: <code>title.MARKUP</code>. Learn how to <a href="../drafts/">work with drafts</a>.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_includes</code></p>
+      </td>
+      <td>
+        <p>
+
+          These are the partials that can be mixed and matched by your layouts
+          and posts to facilitate reuse. The liquid tag
+          <code>{% raw %}{% include file.ext %}{% endraw %}</code>
+          can be used to include the partial in
+          <code>_includes/file.ext</code>.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_layouts</code></p>
+      </td>
+      <td>
+        <p>
+
+          These are the templates that wrap posts. Layouts are chosen on a post-
+          by-post basis in the <a href="../frontmatter/">YAML front matter</a>,
+          which is described in the next section. The liquid tag
+          <code>{% raw %}{{ content }}{% endraw %}</code>
+          is used to inject content into the web page.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_posts</code></p>
+      </td>
+      <td>
+        <p>
+
+          Your dynamic content, so to speak. The format of these files is
+          important, and must follow the format:
+          <code>YEAR-MONTH-DAY-title.MARKUP</code>.
+          The <a href="../permalinks/">permalinks</a> can be customized for each
+          post, but the date and markup language are determined solely by the
+          file name.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_data</code></p>
+      </td>
+      <td>
+        <p>
+
+          Well-formatted site data should be placed here. The jekyll engine will 
+          autoload all yaml files (ends with <code>.yml</code> or <code>.yaml</code>) 
+          in this directory. If there's a file <code>members.yml</code> under the directory, 
+          then you can access contents of the file through <code>site.data.members</code>.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_site</code></p>
+      </td>
+      <td>
+        <p>
+
+          This is where the generated site will be placed (by default) once
+          Jekyll is done transforming it. It’s probably a good idea to add this
+          to your <code>.gitignore</code> file.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>index.html</code> and other HTML, Markdown, Textile files</p>
+      </td>
+      <td>
+        <p>
+
+          Provided that the file has a <a href="../frontmatter/">YAML Front
+          Matter</a> section, it will be transformed by Jekyll. The same will
+          happen for any <code>.html</code>, <code>.markdown</code>,
+          <code>.md</code>, or <code>.textile</code> file in your site’s root
+          directory or directories not listed above.
+
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <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 copied verbatim
+          to the generated site. There are plenty of <a href="../sites/">sites
+          already using Jekyll</a> if you’re curious to see how they’re laid
+          out.
+
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>