Build a web site faster with static site generators
Jekyll is a program used by someone to generate a static website out of text files. It’s a program categorized as a “static site generator.” There are many flavors, old and new, of static site generators that all yield similar benefits. Some benefits are built-in layout engines, template engines, and blogging engines that add dozens of convenient features for the web site creator. Ultimately all of these features point towards a common goal of efficiency.
It’s more efficient to write a simple blog post in Markdown than it is to write the same content in HTML. The blog written in Markdown is converted to HTML by running the Markdown file through a static site generator like Jekyll.
Let’s walk through converting Markdown to HTML using Jekyll. The first time through may not feel very efficient, but as you add more pages to your site I think you’ll quickly realize how much faster you’re adding content.
From the command line install the Ruby
gem jekyll.
$ gem install jekyll
Then create a folder somewhere on your hard drive.
$ mkdir ~/dogs
Create a Markdown file inside your web site’s new folder.
$ cd ~/dogs
$ vim index.md
Write some content in Markdown format. Add 3 dashes in the first two lines of any file you want Jekyll to process. This is a requirement unique to Jekyll.
---
---
# Web Page About Dogs
A paragraph about all kinds of dogs.
Build your entire website using the jekyll command line program.
$ jekyll build
You’ll find the generated static website in the local folder _site
$ tree
.
├── _site
│ └── index.html
└── index.md
You’ll upload the contents of the _site directory to your web site hosting
provider when you’re ready to publish your web site. Before you do that, open up
the HTML page. You will find that it doesn’t contain certain elements that
should be in every HTML web page.
$ cat _site/index.html
<h1 id="hello-world">Hello, World</h1>
<p>This is my web page</p>
This HTML is missing the DOCTYPE declaration, character encoding, and common HTML elements today’s browsers expect to find.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Dogs</title>
</head>
<body>
<h1 id="hello-world">Hello, World</h1>
<p>This is my web page</p>
</body>
</html>
In order to acheive our goal of generating a more complete HTML page from our Markdown source, we will create an HTML layout. A single HTML layout file can be reused for all of your pages. Now we can start to realize some of the benefits of using a static site generator.
Create a new folder inside of your project and be sure to name it _layouts.
Jekyll will recognize files in this folder as layout templates.
$ mkdir _layouts
Create a file inside the _layouts folder.
$ vim _layouts/default.html
And add the HTML layout you want. Insert the text {{ content }} wherever you
want your page content to show up inside the layout.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Dogs</title>
</head>
<body>
{{ content }}
</body>
</html>
Now we have to tell Jekyll to use our template.
$ vim index.md
Edit the “Frontmatter” of the Markdown file. Jekyll reads Frontmatter before it generates any pages. This is useful for many other features of the static site generator.
---
layout: default
---
# Web Page About Dogs
A paragraph about all kinds of dogs.
Now when you build your web site, the contents of _site/index.html should look
like the full HTML web page we wanted.
$ cat _site/index.html
<!DOCTYPE html>
<html lang="en">
<head>
<title>Dogs</title>
</head>
<body>
<h1 id="hello-world">Hello, World</h1>
<p>This is my web page</p>
</body>
</html>
If you really want to build and maintain a website, then I recommend you check out the full Step by Step Tutorial over at the Jekyll web site.