Home / Create a static website using DocPad

You can use Docpad to create a static website. Static sites can be hosted on cloud storage services such Amazon S3. The steps listed below are for Linux, but this tool works on Windows and Mac as well.

Create a static website or blog using Docpad. The code snippets below show how to setup, view and edit the files. Since DocPad is based on Node.js, we start by installing that.

sudo apt-get update && sudo apt-get install curl build-essential openssl libssl-dev git python

curl https://raw.github.com/creationix/nvm/v0.3.0/install.sh | sh #Install Node Version Manager
source .nvm/nvm.sh #Source the file

nvm install v0.10.26 #Install the latest version of NodeJS
nvm alias default 0.10
nvm use 0.10

Here is a raw version of the script above.

Install docpad and plugins for eco, livereload, markdown, coffeescript

npm install -g npm; npm install -g docpad@6.64
npm install grunt --save-dev
docpad install eco #template engine
docpad install livereload #automatic browser refresh
docpad install marked #markdown support
docpad install coffeescript #javascript preprocessor
docpad install gist #embed code snippets from GitHub Gist

docpad run #start the process that monitors file changes and refreshes the browser

Here is a raw version of the script above.

The Beginner Guide has a good explanation of why we need the plugins. Here is a short description of what they do:

  1. Eco lets us have templates so we can reuse code
  2. livereload enables automatic browser refreshes when files are changed
  3. marked lets us use Markdown instead of HTML tags
  4. CoffeeScript is a simple language that compiles into fast or faster than the equivalent handwritten JavaScript.
  5. Gist lets you host snippets of code on GitHub and embed them in your website or blog.

The next step is to create a default layout for your website/blog. The layout this website uses is default.html.eco. Place this file under your-website-folder/src/layouts/.

Once you define the layout, you can create individual pages/posts. The pages/posts can be written in markdown and are placed under yout-website-directory/src/documents/ . An example is the index.html.md. This file extension tells docpad that this is a markdown file that needs to be compiled into an html file. The html files are placed under your-website-directory/out/.

A couple of things to note are the variables such as 'title', 'author', 'preview' etc.in index.html.md. I use these in default.html.eco as <%= @document.title %> etc. A big advantage here is that if I choose to change the layout of the file, I need to update only one file (default.html.eco) and all the pages reflect the change.

If your view the source of the HTML files that are generated under the your-website-directory/out folder, you will see the JavaScript for LiveReload. This is fine for development when you want the browser automatically refresh to see the changes. To skip this in produtction when you deploy, you can run the docpad generate --env static command.

You can also minify the HTML by removing comments and whitespace. You can do this using html-minifier. You can automate this task using a task runner such as Grunt. See this post to install and configure Grunt.

To deploy a static site generated by DocPad to Amazon S3, see this post. I prefer to save all the files online under version control. I use GitHub for this. I also hooked Travis-CI to it so that any changes to the files are also deployed to Amazon S3. This post shows you how I did that.

External Links

  1. For additional setup details visit this link.