Build rapid and lightweight static websites with Hyde - IBM

Build rapid and lightweight static websites with
Hyde
Remove the mystery from content management with a
website development toolkit based on the plain file system
Uche Ogbuji
Principal Consultant
Fourthought Inc.
Skill Level: Intermediate
Date: 05 Feb 2013
Web publishing frameworks are great, but sometimes they're just too much
and you want a simple, static site that you can rely on for good and consistent
performance. Static site generators are a useful hybrid for those occasions when
you want the convenience of a web publishing framework without the overhead.
Hyde is a popular site generator that provides powerful templating, based on
Django, and metadata management. It's implemented in Python but does not
strictly require Python knowledge. In this article, learn to use Hyde to accelerate
development of static websites.
Overview
Early in the history of the Web, most pages were just pages on a file system on a
server somewhere. As the Web became more sophisticated, with dynamic sites, ecommerce,
large-scale publishing, and applications on the Web, it became more and
more common to switch from simple files to sophisticated web content management
systems (CMS) and publishing tools. These days many thousands of sites run on:
• IBM® WebSphere®
• Other Java® frameworks or .NET
• Popular, alternative web publishing frameworks, such as Ruby on Rails and
Django
• Community-oriented CMSs, such as WordPress
It has become almost expected that anything but the simplest sites requires a CMS
with modern facilities and workflow.
But many old-timers on the Web, such as I am, remember some of the advantages
of the simpler, old days. For one thing, serving static files requires less server
© Copyright IBM Corporation 2013 Trademarks
Build rapid and lightweight static websites with Hyde Page 1 of 9

developerWorks® ibm.com/developerWorks/
horsepower. Another issue is backups and content portability. When you choose a
CMS or web publishing framework, you rely on it to make sense of your content. With
your content tied up in database tables, you can't easily reach in and grab a file to
share. The move to a different infrastructure can be a daunting task. You also have to
rely on specialized tools for backup and restore.
The characteristic underlying these issues is transparency. Web publishing
frameworks and CMSs are generally not transparent, which means a lot of special
knowledge is required to understand how they store, manage, and serve up content.
To some extent, this requirement is inevitable on all but the simplest websites, but
recently emerging projects offer some frameworks benefits, without losing the core
element of processing and publishing simple files on a server. One popular such
framework is Jekyll. Some developers built on the core ideas of Jekyll, but using a
different set of building blocks created the open-source Hyde project. Hyde is now my
web publishing system of choice. It is simple yet offers a great deal of power, and it
limits most of its business to processing simple files to generate a static site, resulting
in a great deal of efficiency and flexibility.
Getting started with Hyde
Hyde is a system written in Python that allows you to manage content and templates
in a directory on the file system of your web development machine. You create or
update the content using a regular text editor and command-line tools, or you can
use an IDE if you like. When you're ready to see how it looks, Hyde can generate the
site and serve it up locally using a test web server. When you are satisfied with how
the site looks in test mode, you can push the static, generated files to your production
web server for Apache, Lighttpd, Nginx, or any web server that can serve files at
lightning speeds.
Installation and setup
If you do web development on Mac or Linux systems, you already have the main
thing you need, Python. Python is also easy to install on Microsoft® Windows®
and most other platforms. To install Hyde in your Python library, invoke sudo
easy_install hyde or pip install hyde, depending on your setup. When you do
so, the hyde command should be available. To start, set up Hyde in a directory with a
skeleton set of files for a typical website with this command:
hyde -s $PATH_TO_DIRECTORY create
Replace $PATH_TO_DIRECTORY with the directory where you want to work on content
and template files.
The above command uses a default layout for a site, but Hyde allows you to pick
other site layouts. This option is useful if you want to use some well-known toolkit or
setup for your site, for example, if you use the Twitter Bootstrap framework, or if you
know the target site will be a weblog.
Build rapid and lightweight static websites with Hyde Page 2 of 9

ibm.com/developerWorks/ developerWorks®
If you switch to the newly created site directory using the default layout, you should
see the following subdirectories:
README.markdown content info.yaml layout site.yaml
Each of these entries offers a different side of Hyde.
Markdown
Not many people enjoy writing HTML, and with Hyde you can minimize how much
HTML you deal with. Most content management systems offer ways to avoid handauthoring
HTML, usually using special what-you-see-is-what-you-get (WYSIWYG)
widgets that give you a word-processor feel while generating HTML. Another
approach is well-known from wikis. You edit plain text using special characters to
indicate the various HTML markup constructs. These are called lightweight markup
languages, and one of the more popular specimens is Markdown.
Hyde builds in a processor that allows you to author web pages in Markdown rather
than HTML. I shall not undertake a full introduction to Markdown in this article, but
Listing 1 is a small example of rich content in Markdown format.
Listing 1. Example of rich content in Markdown format
For immediate release. **Boulder, Colorado, 1 January 2012** The new year began
with a bang.... At city hall a local first nation elder was invited to offer
residents a greeting of *Heebee*, or "Hello" in Arapaho, and recorded for the
[city Web page](http://www.bouldercolorado.gov/). One resident said his New Year
resolutions were to:
* Lose weight
* Go camping for at least one week in the summer
* Pay off one credit card
A Markdown processor such as the one bundled with Hyde can convert this into
HTML such as in Listing 2.
Listing 2. HTML output from Markdown content in Listing 1
For immediate release.
Boulder, Colorado, 1 January 2012
The new year began with a bang....
At city hall a local first nation elder was invited to offer residents
a greeting of Heebee, or "Hello" in Arapaho, and recorded
for the city Web page.
One resident said his New Year resolutions were to:
Lose weight
Go camping for at least one week in the summer
Pay off one credit card
Site configuration and YAML
YAML Ain't Markup Language (YAML) is a language that some programmers like to
use for configuration files. A site built with Hyde does require some configuration, for
example, to control how templates are applied. The default site.yaml file generated
by Hyde specifies a few plug-ins, indicates how some local file directories are
Build rapid and lightweight static websites with Hyde Page 3 of 9

developerWorks® ibm.com/developerWorks/
translated to paths for the web server, and provides basic metadata for some key
pages.
Templates and Jinja2
Most websites these days can benefit from some degree of templating. A template
system can help you separate common elements of your site's structure and pages
from each page's individual content. For example, if you look at a weblog, sometimes
more than half of the HTML of each page is boilerplate replicated across all entries.
A template allows you to express that 50 percent of content only once and have it
automatically applied to all the pages. A template system can also support smart
features such as automatically generating a calendar of a weblog's archives.
Hyde uses a similar template language to that of the popular Django framework,
implemented through the Jinja2 project. Each template looks like HTML with some
additional, special syntax for the template commands, as explored further below.
The templates go in the layout directory, and you add and update templates there to
manipulate the overall content outline of your site.
Your content
Most important of all is your own site's content, which you maintain in the directory
of that name. You would generally have one file for each unique web page. Each
content file starts with the page metadata and then has the HTML and template code
for the page. This directory is also where you find static files to support the site, such
as images, stylesheets, and script files.
A small example
A quick way to start with a nice-looking website is to download one of the many
free web designs that include HTML, CSS, and even scripts as needed for a site's
presentation. You can then replace the design's boilerplate with your own content and
tweak the look and feel. This is a straightforward process with Hyde, and you needn't
restrict yourself to a web design for that specific software. In this section, I chose a
regular, free HTML5/CSS3 template and adapt it for Hyde. It's called "Minimalism,"
by Marija Zaric (see Resources), and is available under the Creative Commons
Attribution (by) 3.0, so you can use it freely, even in commercial projects, as long
as you credit the author for use of the template. Your websites using the template
become derivative works of the template.
I downloaded the template package and unzipped it. It contains an index.html file.
The Hyde folder's content directory also contains a file by the same name, but it's
not actually HTML but a Jinja2 template based on base.j2. What I did was turn the
Minimalism file into a new template, by copying it as minimalism.j2. At the same time
I copied the other, support files for the template to the appropriate locations:
cp minimalism/index.html
$PATH_TO_DIRECTORY/layout/minimalism.j2 cp minimalism/css/styles.css
$PATH_TO_DIRECTORY/content/media/css/ cp minimalism/images/*
$PATH_TO_DIRECTORY/content/media/images/
Build rapid and lightweight static websites with Hyde Page 4 of 9

ibm.com/developerWorks/ developerWorks®
Turning a design template into a Jinja2 template
In a website, you'll often have the same basic layout and design for many of the
pages, with differences in content and metadata. To turn the Minimalism design
template into a Jinja2 template that you can use for multiple actual pages, figure out
what is general to all the pages and what is specific to each one. Look at the head
element from Minimalism:
Minimalism - Home
In this case, pretty much everything but the title is shared across pages, So I'll turn
just the title content into a template field from metadata:
{{ resource.meta.title }}
The head element also links to icons, styles, and other resources. Hyde manages the
correspondence between the folders for such resources and their URLs in resulting
pages, so you have to update these links to use a special Hyde function:
...
You can place the favicon.gif file inline during development. When you launch a site
into production, it's best to locate the icon image at the root of the domain, and the
explicit links become superfluous.
You also need to update any images or links to JavaScript files or other resources,
using the same pattern as in previous examples. For example, one feature image
used to show off the template looks like this after update:
At this point, Hyde can display the template just as it looks on the demo site from
which you downloaded it. But your work is not entirely done. Now you have to set up
to replace the "Lorem Ipsum" dummy text with useful content.
Build rapid and lightweight static websites with Hyde Page 5 of 9

developerWorks® ibm.com/developerWorks/
Filling in content
You can easily to mark places in the template where you want to fill in pagespecific
markup. Just add Jinja block markers. Listing 3 illustrates in a section from
minimalism.j2 .
Listing 3. Section of the "Minimalism" template illustrating Jinja block markers
{% block intro %}
"Simplicity is the ultimate sophistication"
- Leonardo da Vinci
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Donec molestie. Sed aliquam sem ut arcu. Phasellus sollicitudin.
Vestibulum condimentum facilisis nulla. In hac habitasse platea
dictumst. Nulla nonummy. Cras quis libero.
{% endblock intro %}
I added {% block intro %} and {% endblock intro %} to the template HTML. As
you can see, I left the dummy text in place. This is fine because I will override it
page by page. Listing 4 is sample page, saved as index.html, which is based on the
minimalism.j2 template but overrides two template blocks.
Listing 4. Example page based on Listing 3, but overriding two Jinja template
blocks, using HTML
--- extends: minimalism.j2
title: Strange Case of Dr Jekyll and Mr Hyde
description: Tribute to a Victorian classic --
{% block intro %}
Strange Case of Dr Jekyll and Mr Hyde
—R.L. Stevenson
"I knew myself, at the first breath of this new life,
to be more wicked, tenfold more wicked, sold a slave to my original evil;
and the thought, in that moment, braced and delighted me like wine."
{% endblock intro %}
{% block group1 %}
The author
Robert Louis Balfour Stevenson (13 November 1850 – 3 December 1894)
was a Scottish novelist, poet, essayist and travel writer. His best known
books include Treasure Island, Kidnapped, and
Strange Case of Dr Jekyll and Mr Hyde.
Read more
{% endblock group1 %}
Build rapid and lightweight static websites with Hyde Page 6 of 9

ibm.com/developerWorks/ developerWorks®
Listing 5 illustrates the use of Markdown to express part of a page's content,
using the {% filter markdown -%} instruction to invoke Hyde's built-in markdown
converter.
Listing 5. Example page based on Listing 3, but overriding two Jinja template
blocks, using Markdown
--- extends: minimalism.j2 title: Strange Case of Dr Jekyll and Mr Hyde
description: Tribute to a Victorian classic ---
{% block intro %}
{% filter markdown -%}
# *Strange Case of Dr Jekyll and Mr Hyde*
## "I knew myself, at the first breath of this new life, to be more wicked..."
{%- endfilter %}
{% endblock intro %}
{% block group1 %}
{% filter markdown -%}
### The author
**Robert Louis Balfour Stevenson** (13 November 1850 – 3 December 1894) was a
Scottish novelist, poet, essayist and travel writer. His best-known books include
*Treasure Island*, *Kidnapped*, and *Strange Case of Dr Jekyll and Mr Hyde*
{%- endfilter %}
Read more
{% endblock group1 %}
Only the content within the filter instructions are interpreted as markdown. Notice how
those bits are flush left, unlike the HTML bits, which are indented according to block
elements. This is because indentation is significant in Markdown and not in HTML.
Summary
I only scratched the surface of the features available in Jinja templates and other
components of Hyde. That works fine because Hyde is designed so that you can
begin with the simpler functions and work up to more sophisticated features as
you go along, whenever you need to enhance automation and workflow. You can
develop many simple web pages with simple blocks (which you can nest). If you need
automatically compiled weblogs and the like, Hyde's default layout provides a good
example.
Overall, Hyde gives you most of the features of content management systems and
low-level web publishing frameworks. With the file system as the backing store, very
little of your system is obscured or mysterious. I think this is a great benefit, and you
now have enough of the basics to get started and create a simple web page with
Hyde, and a web design template of your choosing.
Build rapid and lightweight static websites with Hyde Page 7 of 9

developerWorks® ibm.com/developerWorks/
Resources
Learn
• Learn about Markdown, the popular, text-based, lightweight markdown
language.
• Learn about YAML Ain't Markup Language (YAML), which is increasingly
popular for configuration files, an used in Hyde.
• More articles by this author (Uche Ogbuji, developerWorks, November 2000current):
Read articles about web development, Python, XML, XSLT, and other
technologies.
• New to Web development: Learn about the many different technologies used for
web app development that serves content in HTML, CSS, or JavaScript files to
relational databases and server-side programming.
• developerWorks Web development zone: Find articles covering various webbased
solutions. See the Web development technical library for a wide range of
technical articles and tips, tutorials, standards, and IBM Redbooks.
• Find more XML resources on the developerWorks XML zone, including Uche
Ogbuji's Thinking XML column.
• Stay current with developerWorks technical events and webcasts focused on a
variety of IBM products and IT industry topics.
• Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM
products and tools as well as IT industry trends.
• Follow developerWorks on Twitter.
• Watch developerWorks on-demand demos ranging from product installation
and setup demos for beginners, to advanced functionality for experienced
developers.
Get products and technologies
• Get started with Hyde, a static website generator that models many common
CMS features.
• Check out the Jinja2 template language and toolkit, which is similar to that in
Django.
• Grab Marija Zaric's "Minimalism" template, used for the example in this article.
• Evaluate IBM products in the way that suits you best: Download a product trial,
try a product online, use a product in a cloud environment, or spend a few hours
in the SOA Sandbox learning how to implement Service Oriented Architecture
efficiently.
Discuss
• Get involved in the My developerWorks community. Connect with other
developerWorks users while exploring the developer-driven blogs, forums,
groups, and wikis.
Build rapid and lightweight static websites with Hyde Page 8 of 9

ibm.com/developerWorks/ developerWorks®
About the author
Uche Ogbuji
Uche Ogbuji is Partner at Zepheira where he oversees creation of
sophisticated web catalogues and other richly contextual databases.
He has a long history of pioneering in advanced web technologies such
as XML, Semantic Web and Web services, open source projects such
as Akara, an open source platform for web data applications. He is a
computer engineer and writer born in Nigeria, living and working near
Boulder, Colorado, USA. You can find more about Mr. Ogbuji at his
weblog, Copia.
© Copyright IBM Corporation 2013
(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)
Build rapid and lightweight static websites with Hyde Page 9 of 9