jekyll-docs 2.5.3 → 3.0.3

data/site/_docs/posts.md

@@ -0,0 +1,237 @@
+---
+layout: docs
+title: Writing posts
+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 are generally
+[Markdown](http://daringfireball.net/projects/markdown/) or HTML, but can
+be other formats with the proper converter installed.
+All posts must have [YAML Front Matter](../frontmatter/), and 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 %}
+
+<div class="note">
+  <h5>ProTip™: Link to other posts</h5>
+  <p>
+    Use the <a href="../templates/#post-url"><code>post_url</code></a>
+    tag to link to other posts without having to worry about the URL's
+    breaking when the site permalink style changes.
+  </p>
+</div>
+
+### 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
+[Markdown](http://daringfireball.net/projects/markdown/) out of the box,
+and has [myriad extensions for other formats as well](/docs/plugins/#converters-1),
+including the popular [Textile](http://redcloth.org/textile) format. 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.
+
+<div class="note info">
+  <h5>Be aware of character sets</h5>
+  <p>
+    Content processors can modify certain characters to make them look nicer.
+    For example, the <code>smart</code> extension in Redcarpet converts standard,
+    ASCII quotation characters to curly, Unicode ones. In order for the browser
+    to display those characters properly, define the charset meta value by
+    including <code>&lt;meta charset=&quot;utf-8&quot;&gt;</code> in the
+    <code>&lt;head&gt;</code> of your layout.
+  </p>
+</div>
+
+## 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.
+
+Note that the `post` variable only exists inside the `for` loop above. If
+you wish to access the currently-rendering page/posts's variables (the
+variables of the post/page that has the `for` loop in it), use the `page`
+variable instead.
+
+## 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>
+      {% raw %}{{ post.excerpt }}{% endraw %}
+    </li>
+  {% raw %}{% endfor %}{% endraw %}
+</ul>
+{% endhighlight %}
+
+Because Jekyll grabs the first paragraph you will not need to wrap the excerpt
+in `p` tags, which is already done for you. These tags can be removed with the
+following if you'd prefer:
+
+{% highlight html %}
+{% raw %}{{ post.excerpt | remove: '<p>' | remove: '</p>' }}{% endraw %}
+{% endhighlight %}
+
+If you don't like the automatically-generated post excerpt, it can be
+explicitly overridden by adding an `excerpt` value to your post's YAML
+Front Matter. Alternatively, you can choose to define a custom
+`excerpt_separator` in the post's YAML front matter:
+
+{% highlight text %}
+---
+excerpt_separator: <!--more-->
+---
+
+Excerpt
+<!--more-->
+Out-of-excerpt
+{% endhighlight %}
+
+You can also set the `excerpt_separator` globally in your `_config.yml`
+configuration file.
+
+Completely disable excerpts by setting your `excerpt_separator` to `""`.
+
+Also, as with any output generated by Liquid tags, you can pass the
+`| strip_html` filter to remove any html tags in the output. This is
+particularly helpful if you wish to output a post excerpt as a
+`meta="description"` tag within the post `head`, or anywhere else having
+html tags along with the content is not desirable.
+
+## Highlighting code snippets
+
+Jekyll also has built-in support for syntax highlighting of code snippets using
+either Pygments or Rouge, 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,27 @@
+---
+layout: docs
+title: Quick-start guide
+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 %}
+
+If you wish to install jekyll into the current directory, you can do so by
+alternatively running `jekyll new .` instead of a new directory name.
+
+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.
+
+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
+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 FormKeep for Jekyll form backend and webhooks](https://formkeep.com/)
+- [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.”
+- [‘Build A Blog With Jekyll And GitHub Pages’, by Barry Clark](http://www.smashingmagazine.com/2014/08/01/build-blog-jekyll-github-pages/)
+  > “I recently migrated my blog from WordPress to Jekyll, a fantastic website generator that’s designed for building minimal, static blogs to be hosted on GitHub Pages. The simplicity of Jekyll’s theming layer and writing workflow is fantastic; however, setting up my website took a lot longer than expected. In this article we'll walk through: the quickest way to set up a Jekyll powered blog, how to avoid common problems with using Jekyll, how to import your content from Wordpress, and more.”
+- [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.
+
+- A way to [extend Jekyll](https://github.com/rfelix/jekyll_ext) without forking and modifying the Jekyll gem codebase and some [portable Jekyll extensions](https://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)
+
+- [Adding Ajax pagination to Jekyll](https://eduardoboucas.com/blog/2014/11/10/adding-ajax-pagination-to-jekyll.html)

data/site/_docs/sites.md

@@ -0,0 +1,29 @@
+---
+layout: docs
+title: Sites using Jekyll
+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](https://github.com/mojombo/mojombo.github.io))
+- [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://training.github.com)
+    ([source](https://github.com/github/training.github.com/tree/7049d7532a6856411e34046aedfce43a4afaf424))
+- [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))
+- [Leonard Lamprecht](http://leo.im)
+    ([source](https://github.com/leo/leo.github.io))
+
+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/static_files.md

@@ -0,0 +1,52 @@
+---
+layout: docs
+title: Static Files
+permalink: /docs/static-files/
+---
+
+In addition to renderable and convertible content, we also have **static
+files**.
+
+A static file is a file that does not contain any YAML front matter. These
+include images, PDFs, and other un-rendered content.
+
+They're accessible in Liquid via `site.static_files` and contain the
+following metadata:
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><p><code>file.path</code></p></td>
+      <td><p>
+
+        The relative path to the file.
+
+      </p></td>
+    </tr>
+    <tr>
+      <td><p><code>file.modified_time</code></p></td>
+      <td><p>
+
+        The `Time` the file was last modified.
+
+      </p></td>
+    </tr>
+    <tr>
+      <td><p><code>file.extname</code></p></td>
+      <td><p>
+
+        The extension name for the file, e.g.
+        <code>.jpg</code> for <code>image.jpg</code>
+
+      </p></td>
+    </tr>
+  </tbody>
+</table>
+</div>

data/site/_docs/structure.md

@@ -0,0 +1,211 @@
+---
+layout: docs
+title: Directory structure
+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
+├── .jekyll-metadata
+└── 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 naming convention 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 in this directory (using either the
+          <code>.yml</code>, <code>.yaml</code>, <code>.json</code> or
+          <code>.csv</code> formats and extensions) and they will be
+          accessible via `site.data`. 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>.jekyll-metadata</code></p>
+      </td>
+      <td>
+        <p>
+
+          This helps Jekyll keep track of which files have not been modified
+          since the site was last built, and which files will need to be
+          regenerated on the next build. This file will not be included in the
+          generated site. 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>