Installing and Getting Started with DocPad on Windows

Javascript , Static Site Generation Add comments

This blogpost is written in the context of using DocPad with No Skeleton and the ECO (Embedded CoffeeScript Templates) templating engine.

Whilst contributing to the Adobe open source project Topcoat.io I had the chance to get up close and personal with DocPad.

DocPad is a next generation web architecture; allowing for

  • Content management via the file system
  • Rendering via plugins, and
  • Static site generation for deployment anywhere.

It's built with Node.js and Express.js, making it naturally fast and easily extendable.

During my time using DocPad I had some issues which I was able to easily overcome so I thought I would document these here so that other in the same position can hopefully find my blog and save themselves some time by trying out these possible workarounds and get to know and use DocPad as it truely is a great toolkit for any web developer looking to get their hands dirty with static site generation.

OK, so I started out by following the DocPad documentation available here: http://docpad.org/docs/begin
There is also an introduction which I recommend you follow here too: http://docpad.org/docs/overview

So lets get started.

Issue # 1
The first issue I encountered was when I was trying to access my local website at http://localhost:9778 (note DocPad does all this for you so don't worry about the setup too much just yet).  I was receiving a 404 and the console was also telling me the same.

I simply exited my console (using conEmu) and re-opened and tried running the command "docpad run" and the site became available.  All good.

Issue # 2
Again, when I added the about.html page and refreshed the browser I had to terminate DocPad and re-launch as it didn't seem to be rendering the templates.

Issue # 3
As part of the "Adding Assets" section I tried to add the DocPad image located at http://d.pr/i/cfmt+ but unfortunately I was again getting a 404 Not found: /images/logo.gif and guess what.  Yes I simply terminated DocPad and re-launched with the docpad run command and the image appeared.

The reason it seemed to not find the image is because the generator, again, didn't pick up that the new folder and image file I had just added to the /src directory.

I checked the /out directory and hey presto the images folder and image were finally there afterwards.


Issue #4
Another generation issue, maybe I'm missing something but when adding the stylesheet I also had to terminate and re-launch DocPad.
It may be that when new folders / files are added you need to do this each time but afterwards they will get picked up and become part of the generation process.  I may have missed this point in the documentation but for now I'll stop reporting any similar issues otherwise this post may have to be broken into multiple parts :-)


Issue #5
When abstracting logic for the page title into the template helper I encountered an issue where docpad was shutting down with the message

warning: Something went wrong while rendering: about.html.md
Object #<Object> has no method 'getPreparedTitle'
info: Shutting down... cya next time!


This turned out to be a relatively easy fix.  As the guide is using CoffeeScript format to define the configuration you need to ensure that the indentation is correct.  The

{{getPreparedTitle()}} method definition needs to have the same indentation level as the "site:" attribute to ensure it's available under the "templateData" scope.  That's it.


Issue #6
When adding the custom collection via the configuration file I updated the code from the example to include the sorting argument.  When I reloaded DocPad threw the following error:

warning: Something went wrong while rendering: about.html.md
unexpected TERMINATOR
info: Shutting down... cya next time!


Again, this was simply a matter of ensuring the result from the QueryEngine is converted to a standard JavaScript Array using the ".toJSON():" function.

So instead of using:

<% for page in @getCollection('html').findAllLive({isPage:true},[{filename:1}]) %>


Should have been:

<% for page in @getCollection('html').findAllLive({isPage:true},[{filename:1}]).toJSON(): %>



Note:
Each time the livereload plugin refreshed the browser or I refreshed manually the console was displaying a warning to say that there was no favicon.ico file available.  The generated markup didn't reference this so I simply ignored it for now.  I will digg into why this is the case and report back in a later post.

Next I'll follow up with a post about using DocPad with the Jade templating engine and my experience with that.

 

Bookmark and Share

2 responses to “Installing and Getting Started with DocPad on Windows”

  1. Benjamin Lupton Says:
    That's really strange you had soo many 404 not founds occur. Happy to remote in sometime and find out what was going on.

    The favicon 404's are normal if you do not have a favicon file, as the browser will always do a request to /favicon.ico, unless of course it's location was specified elsewhere via an appropriate HTML entity.
  2. ivan Says:
    Man thanks for sharing this, i have problems installing docpad on windows 8 , do you have some guide or something? thanks

Leave a Reply

Leave this field empty:

Powered by Mango Blog. Design and Icons by N.Design Studio