Tutorial

This tutorial will step you through the process of creating a simple informational site with Dudley. It assumes you've already installed Node.JS and have root access to a Unix-like machine (Linux, MacOS-X, *BSD, etc.)

Dudley is a simple tool. It scans an input directory looking for files that begin with an underbar. It runs these files through a templating engine writing the results to a file in the output directory. Files that don't begin with an underbar are copied without processing.

Dudley uses 'themes' to store boilerplate content you may want to re-use from project to project. In this tutorial, we're going to use the bootstrap theme.

Each dudley project should have a _horse.json file at the top level of the input directory. This file contains site information and processing defaults.

In this tutorial, we're going to build a simple web site by installing dudley, creating the input content, running dudley and then observing what it created.

Step 1. Install Dudley

Installing Dudley is simple. Just issue the following npm command: 

sudo npm install -g dudley

NPM will take a few moments to install the package.

Step 2. Create Some Content

Let's start by creating a directory to contain our content: 

mkdir content

Once you've created the content directory, use your favourite text editor to copy these files into it:

File: _index.html

<div class="jumbotron">
  <div class="container">
    <h1>{{title}}</h1>
    {{#if subtitle}}<p>{{subtitle}}</p>{{/if}}
  </div>
</div>

<div class="container">
  <div class="row">
    <div class="col-md-12 item">
      <h2>Some Example Content</h2>
      <p>
        So this is just some sample content that was converted from an HTML
        fragment into a "real" HTML web page with Dudley. By default, html
        files that begin with underscores are processed using Handlebars and
        have a web scaffolding placed around it.
      </p>

      <p>
        Files whose names begin with an underscore are just copied from the
        source directory to the destination directory. Here's a link to
        <a href="static.html">static.html</a>, a file that <i>shouldn't</i>
        be run through the templating engine.
      </p>
      </div>
    </div>
  </div>
</div>

File: static.html

<!DOCTYPE html>
<html>
  <body>
    <h1>Static Test</h1>
    <p>
      This is an example of a static html file that isn't run through
      the dudley processor. The fun content is over
      at <a href="index.html">index.html</a>, though.
    </p>
  </body>
</html>

Step 3. Create the _dudley.json File

The _dudley.json file contains information about the site we're generating. In this case, it contains the site's title and sub-title, which are passed directly to the template processor. It uses the theme property to tell the processor to use the bootstrap theme.

Finally, it uses the ignore property to tell the processor to ignore the _dudley.json file. If we hadn't told the processor to ignore this file, it would have processed it, creating a file called dudley.json in the destination directory.

File: static.html

{
  "title": "Tutorial",
  "subtitle": "Because sometimes it's easier to learn by doing.",
  "theme": "bootstrap",
  "ignore": [ "_dudley.json" ]
}

Step 4. Run the dudley Command

To run dudley, use this command from the directory containing the content directory: 

dudley --source content --destination static --theme bootstrap

Step 5. Enjoy!

Ater invoking dudley, you should find a directory called static with index.html and static.html files from the content we provided. You should also find css and js directories from the template directory.

Most web browsers allow you to browse file:/// URLs, so you should be able to open a web browser session with the command: 

cd static
google-chrome file://index.html

This example uses the Chrome browser, but you should be able to substitute your favourite browser in the command line.

Conclusion

So what did we learn here?

  • Dudley generates static files from static files. It's not a full fledged CMS, but it could be used as part of one.
  • Dudley takes content from one directory, processes it and puts the result in a different directory.
  • Dudley content input directories use a _dudley.json file to store site info and processing directives.
  • Dudley's output comes from both the theme you specify and the content you provide.