tutes-dump/site-tutorials/jekyll.html

194 lines
10 KiB
HTML
Raw Normal View History

2020-07-11 06:11:19 -04:00
<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>&#60;title&#62;{{ page.title }}&#60;/title&#62;</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>