forked from pifty/tutes-dump
194 lines
10 KiB
HTML
Executable File
194 lines
10 KiB
HTML
Executable File
<h1>Blogging with Jekyll</h1>
|
|
<hr />
|
|
|
|
<h2>Contents</h2>
|
|
<ul>
|
|
<li><a href="#introduction">Introduction</a></li>
|
|
<ul><li><a href="#advantages">Advantages to using Jekyll</li></ul>
|
|
<li><a href="#gettingstarted">Getting started</a></li>
|
|
<li><a href="#liquid">Using the Liquid templating language</a></li>
|
|
<ul>
|
|
<li><a href="#output">Output markup</a></li>
|
|
<li><a href="#tag">Tag markup</a></li>
|
|
</ul>
|
|
<li><a href="#templates">Creating templates</a></li>
|
|
<ul>
|
|
<li><a href="#defaulttemplate">Default template</a></li>
|
|
<li><a href="#posttemplate">Post template</a></li>
|
|
<li><a href="#othertemplates">Other templates</a></li>
|
|
</ul>
|
|
<li><a href="#index">Creating the index page</a></li>
|
|
<li><a href="#post">Writing a post</a></li>
|
|
<li><a href="#build">Building the site</a></li>
|
|
</ul>
|
|
|
|
<h2><a id="introduction" />Introduction</h2>
|
|
|
|
From the <a href="http://wiki.github.com/mojombo/jekyll">Jekyll wiki</a>:
|
|
|
|
<blockquote>Jekyll is a simple, blog aware, static site generator.
|
|
It takes a template directory (representing the raw form of a website),
|
|
runs it through Textile or Markdown and Liquid converters, and spits out
|
|
a complete, static website suitable for serving with Apache or your
|
|
favorite web server.</blockquote>
|
|
|
|
Jekyll is installed on SDF, making it a particularly useful tool for MOTD
|
|
users but also for any user wishing to host a weblog on his SDF webspace.
|
|
|
|
<h3><a id="advantages" />Advantages to using Jekyll</h3>
|
|
|
|
<ul>
|
|
<li><b>No databases required.</b> Jekyll converts marked up text files
|
|
to HTML files.</li>
|
|
<li><b>No dynamic pages.</b> With Jekyll your site will be composed solely
|
|
of static HTML files. No CGI is necessary, reducing the load on SDF
|
|
servers.</li>
|
|
<li><b>Ease and simplicity of use.</b> Using Jekyll does not require any
|
|
programming knowledge, and the learning curve is very shallow. At the
|
|
same time, the user does not sacrifice any control to wizards and GUIs.
|
|
</li>
|
|
</ul>
|
|
|
|
<h2><a id="gettingstarted" />Getting started</h2>
|
|
|
|
<p>Create a source directory with the following structure:</p>
|
|
|
|
<ul>
|
|
<li><b><code>_config.yml</code></b> This is the configuration file. Any
|
|
settings put in here could also be declared as arguments after the
|
|
<code>jekyll</code> command, but that would be a little messy. A complete
|
|
explanation of options can be found <a href="http://wiki.github.com/mojombo/jekyll/configuration">here</a>.</li>
|
|
<li><b><code>_layouts/</code></b> This directory contains the layouts to
|
|
be used throughout the site. The following files should be placed in this
|
|
directory, and more layouts can be added later. They are not actual HTML
|
|
files.</li>
|
|
<ul>
|
|
<li><b><code>default.html</code></b> This is the layout that will be
|
|
used by every page on the site. It will determine the overall look and
|
|
layout.</li>
|
|
<li><b><code>post.html</code></b> This layout will be applied to the
|
|
posts on the blog.</li>
|
|
</ul>
|
|
<li><b><code>_posts/</code></b> This directory is home to all posts. Posts
|
|
are named <code>YYYY-MM-DD-title-of-post.textile</code>, assuming
|
|
Textile formatting is used.</li>
|
|
<li><b><code>index.html</code></b> This is obviously the index file. Despite
|
|
the file name extension, it requires a special layout so that it can be
|
|
interpreted by the Liquid engine.</li>
|
|
</ul>
|
|
|
|
<p>Inside the <code>_config.yml</code> file, set the destination value to the directory that should contain the generated site:</p>
|
|
|
|
<blockquote><code>
|
|
destination: /absolute/path/to/html
|
|
</code></blockquote>
|
|
|
|
MOTD users may wish to put instead:
|
|
|
|
<blockquote><code>
|
|
destination: /absolute/path/to/html/motd
|
|
</code></blockquote>
|
|
|
|
<p>Replace <code>/absolute/path/to</code> with the path to your home directory.
|
|
Type <code>echo $HOME</code> in the shell if you're unsure.</p>
|
|
|
|
|
|
<h2><a id="liquid" />Using the Liquid templating engine</h2>
|
|
Liquid is a templating engine with which all files ending in <code>.html</code>
|
|
will be processed. These files can have normal HTML that will be interpreted
|
|
literally. Liquid only cares about text in between <code>{{</code> and <code>
|
|
}}</code> and in between <code>{%</code> and <code>%}</code>. The former
|
|
denotes output markup, meaning that whatever is placed within the brackets
|
|
can produce text. The latter denotes tag markup, which does not produce text
|
|
but is used for comments, conditional statements, and loops.
|
|
|
|
<h3><a id="output" />Output markup</h3>
|
|
Output markup is fairly simple. The basic format is
|
|
<code>{{ variable | filter }}</code>. The variables are typically built into
|
|
Jekyll, so one usually doesn't have to worry about declaring them. <code>site
|
|
</code> is a variable that stores site-wide information in sub-variables. For
|
|
example, <code>site.posts</code> is a list of all the site's posts. Each post
|
|
has its own <code>post</code> variable, which includes information
|
|
such as <code>post.title</code>, <code>post.url</code>, and
|
|
<code>post.date</code> Another important variable is <code>content</code>,
|
|
which is used in templates to denote where the content will be inserted. A
|
|
complete list of template data can be found
|
|
<a href="http://wiki.github.com/mojombo/jekyll/template-data">here</a>.
|
|
Filters are used to manipulate theoutput of variables. When a filter is not
|
|
specified (<code>{{ variable }}</code>), the variable is simply printed.
|
|
Liquid has a bunch of built-in filters that can be found, along with a whole
|
|
summary of using Liquid,
|
|
<a href="http://wiki.github.com/tobi/liquid/liquid-for-designers">here</a>.
|
|
Jekyll also has some of its own filters, such as <code>number_of_words</code>
|
|
and <code>array_to_sentence_string</code>, which turns an array variable into
|
|
a list of words seperated by commas and an "and." The complete list can be
|
|
found <a href="http://wiki.github.com/mojombo/jekyll/liquid-extensions">
|
|
here</a>, along with Jekyll's extra tags.
|
|
|
|
<h3><a id="tag" />Tag markup</h3>
|
|
The most basic tag is <code>{% comment %}</code> / <code>{% endcomment %}
|
|
</code>. Anything in between those tags is ignored. Conditional statements
|
|
are possible with <code>{% if condition %}</code> / <code>{% endif %}</code>.
|
|
For loops are especially useful with Jekyll. Use them with <code>{% for item
|
|
in array %}</code> / <code>{% endfor %}</code>.
|
|
|
|
<h2><a id="templates" />Creating templates</h2>
|
|
Let's actually get started with the blog. The first thing we need are the
|
|
templates.
|
|
|
|
<h3><a id="defaulttemplate" />Default template</h3>
|
|
Remember that the templates are stored in the <code>_layouts/</code> folder
|
|
and that the default template is named <code>default.html</code>. Here we
|
|
can put all of the HTML headers once and be done with them. This includes
|
|
any meta information, a link to a stylesheet, a link to a feed, etc. For
|
|
the title, we can use
|
|
<code><title>{{ page.title }}</title></code>. This way the
|
|
title for every page will automatically get inserted. Once all of the
|
|
headers are done, we can add some layout that will get used on every page.
|
|
Finally, <code>{{ content }}</code> must go where dynamic content of the
|
|
site will be inserted.
|
|
|
|
<h3><a id="posttemplate" />Post template</h3>
|
|
<code>post.html</code> determines the layout for post pages. Here we first
|
|
encounter YAML front matter. YAML stands for "YAML Ain't a Markup Language,"
|
|
Any YAML content is placed between <code>---</code> and <code>---</code>
|
|
(each on their own line)
|
|
at the beginning of a document. In this front matter we
|
|
can set variables in the format, <code>variable: value</code>. The only
|
|
variable we need to set for the post template is <code>layout: default</code>.
|
|
This tells Jekyll to insert this template into <code>{{ content }}</code>
|
|
in the default layout. We'll also want to add a <code>{{ content }}</code> to
|
|
the post template. This is where the actual post will get inserted. We also
|
|
might want to add somethings like <code>{{ page.title }}</code> and
|
|
<code>{{ page.date | date: "%A %d %B %Y" }}</code>, which will format the
|
|
post's date as <code>Weekday Day Month Year</code>.
|
|
|
|
<h3><a id="othertemplates" />Other templates</h3>
|
|
Finally, once getting the hang of creating template, one can add new ones,
|
|
such as <code>static.html</code> for static pages without a date.
|
|
|
|
<h2><a id="index" />Creating the index page</h2>
|
|
The web site will of course need an index page, <code>index.html</code>. As
|
|
usual, this will get interpreted by Liquid. But first we'll need to add the
|
|
front matter. The layout should probably be default again. If any of the
|
|
layouts use <code>{{ page.title }}</code>, we can define the title of the
|
|
home page now with <code>title: This Is My Title</code>. After the YAML
|
|
front matter, we'll probably want a list of the posts. This can be done
|
|
with a for loop: <code>{% for post in site.posts %}</code>. Format the HTML
|
|
content inside the loop in any way, maybe using <code>{{ post.date }}</code>
|
|
and <code>{{ post.title }}</code>.
|
|
|
|
<h2><a id="post" />Writing a post</h2>
|
|
<p>We have some different choices for the markup language for the posts, but we'll use Textile because it works just fine. Remember to name the file <code>YYYY-MM-DD-title-of-post.textile</code> and to put it in the <code>_posts/</code> directory. Again we'll start with the front matter. This time, we'll want <code>layout: post</code>, so that the output of the post will get inserted at <code>{{ content }}</code> in the post template. If <code>{{ page.title }}</code> was used anywhere else, the title must be declared now. Whatever comes after the YAML content must be in the Textile format, which is very easy to learn. A good reference can be found <a href="http://redcloth.org/hobix.com/textile/">here</a>.</p>
|
|
|
|
<p>One thing to watch out for is that any newline is interpreted as a new paragraph, so don't hit "return" unless you mean it.</p>
|
|
|
|
<h2><a id="build" />Building the site</h2>
|
|
<p>Once we have our templates, index, and posts done, we can finally build the site. To do so, use the command <code>jekyll</code> in your source directory to generate the static HTML site, followed by <code>mkhomepg -p</code> to set the proper permissions on any newly-created files.</p>
|
|
|
|
<p>Congratulations, you now have a Jekyll-powered blog. All of this may have seemed complicated, but once you get the hang of it, maintaining your new site will be a breeze!</p>
|
|
|
|
<hr />
|
|
<pre>$Id: jekyll.html,v 1.5 2010/07/24 14:30:14 nerfling Exp $</pre>
|
|
|