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


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, e-commerce, 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 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.

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.


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 hand-authoring 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]( 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
      <p>For immediate release. 
      <strong>Boulder, Colorado, 1 January 2012</strong> 
      The new year began with a bang....</p>
      <p>At city hall a local first nation elder was invited to offer residents 
          a greeting of <em>Heebee</em>, or "Hello" in Arapaho, and recorded 
          for the <a href="">city Web page</a>.</p>
      <p>One resident said his New Year resolutions were to:</p>
          <li>Lose weight</li>
          <li>Go camping for at least one week in the summer</li>
          <li>Pay off one credit card</li>

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 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 Related topics), 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/* 

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:

          <meta charset="UTF-8"> 
              <title>Minimalism - Home</title> 
              <link rel="icon" href="images/favicon.gif" type="image/x-icon"/> 
              <!--[if lt IE 9]> 
                  <script src="//">
              <link rel="shortcut icon" href="images/favicon.gif" type="image/x-icon"/>
              <link rel="stylesheet" type="text/css" href="css/styles.css"/>

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:

<title>{{ resource.meta.title }}</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:

      <link rel="icon" href="{{ media_url('images/favicon.gif') }}" type="image/x-icon"/>
      <link rel="shortcut icon" href="{{ media_url('images/favicon.gif') }}" 
          type="image/x-icon"/> <link rel="stylesheet" 
              href="{{ media_url('css/styles.css') }}" type="text/css"/>

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:

      <a class="photo_hover3" href="#"> 
          <img src="{{ media_url('images/picture1.jpg') }}" width="240" 
              height="214" alt="picture1"/></a>

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.

Filling in content

You can easily to mark places in the template where you want to fill in page-specific 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
      <!--start intro--> 
      {% block intro %} 
      <section id="intro"> 
              <h1>"Simplicity is the ultimate sophistication"
                  <span>- Leonardo da Vinci</span>
              <h2>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.</h2> 
      {% 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 %} 
      <section id="intro"> 
      <h1><i>Strange Case of Dr Jekyll and Mr Hyde</i>
          <span>—R.L. Stevenson</span></h1>
          <h2>"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."</h2>
      {% endblock intro %}
      {% block group1 %}
      <section class="group1">
          <h3>The author</h3>
          <p><b>Robert Louis Balfour Stevenson</b> (13 November 1850 – 3 December 1894) 
              was a Scottish novelist, poet, essayist and travel writer. His best known 
              books include <i>Treasure Island</i>, <i>Kidnapped</i>, and 
              <i>Strange Case of Dr Jekyll and Mr Hyde</i>.</p> 
          <a class="photo_hover3" href="#">
              <img src="//  
                  width="220" height="329" alt="R.L. Stevenson"/></a> 
          <a href="#"><span class="button">Read more</span></a>
      {% endblock group1 %}

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 %} 
      <section id="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 %} 
      <section class="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 %} 
          <a class="photo_hover3" href="#">
              <img src="// 
                  width="220" height="329" alt="R.L. Stevenson"/>
          <a href="#"><span class="button">Read more</span></a> 
      {% 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.


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.

Downloadable resources

Related topics

Zone=Web development, Open source
ArticleTitle=Build rapid and lightweight static websites with Hyde