Initially web development was pretty easy, you just wrote a bunch of files and you got your website. These days, it's a lot more complicated than that. Things like databases, synchronisation, legacy frameworks and languages all slow the entire process down into a painful crawl. It doesn't have to be like that.
DocPad takes that good ol' simple approach of writing files and wraps it with the best modern innovations, providing an awesome intuitive, liberating and empowering solution for HTML5 web design & development.
-
Say you were to create the following website structure:
- myWebsite - src - documents - layouts - public
-
And you were to create the following files:
-
A layout at
src/layouts/default.html.eco
, which contains<html> <head><title><%=@document.title%></title></head> <body> <%-@content%> </body> </html>
-
And another layout at
src/layouts/post.html.eco
, which contains:--- layout: default --- <h1><%=@document.title%></h1> <div><%-@content%></div>
-
And a document at
src/documents/posts/hello.html.md
, which contains:--- layout: post title: Hello World! --- Hello **World!**
-
-
Then when you generate your website with docpad you will get a html file at
out/posts/hello.html
, which contains:<html> <head><title>Hello World!</title></head> <body> <h1>Hello World!</h1> <div>Hello <strong>World!</strong></div> </body> </html>
-
And any files that you have in
src/public
will be copied to theout
directory. E.g.src/public/styles/style.css
->out/styles/style.css
-
Allowing you to easily generate a website which only changes (and automatically updates) when a document changes (which when you think about it; is the majority of websites)
-
Cool, now what was with the
<%=...%>
and<%-...%>
parts which were substituted away?-
This is possible because we parse the documents and layouts through a template rendering engine. The template rendering engine used in this example was Eco (hence the
.eco
extensions of the layouts). Templating engines allows you to do some pretty nifty things, in fact we could display all the titles and links of our posts with the following:<% for document in @documents: %> <% if document.url.indexOf('/posts') is 0: %> <a href="<%= document.url %>"><%= document.title %></a><br/> <% end %> <% end %>
-
-
Cool that makes sense... now how did
Hello **World!**
in our document get converted intoHello <strong>World!</strong>
?- That was possible as that file was a Markdown file (hence the
.md
extension it had). Markdown is fantastic for working with text based documents, as it really allows you to focus in on your content instead of the syntax for formatting the document!
- That was possible as that file was a Markdown file (hence the
- Markdown to HTML
.html.md|markdown
- Eco to anything
.anything.eco
- CoffeeKup to anything
.anything.ck|coffeekup|coffee
and HTML to CoffeeKup.ck|coffeekup|coffee.html
- Jade to anything
.anything.jade
and HTML to Jade.jade.html
- HAML to anything
.anything.haml
- CoffeeScript to JavaScript
.js.coffee
and JavaScript to CoffeeScript.coffee.js
- Roy to JavaScript
.js.roy
- YAML with
--- yaml
(default) - CoffeeScript with
--- coffee
- Runs on Node.js 0.4, 0.5, and 0.6
- Can run on windows
- Dynamic documents
- Allows you to have documents that re-render on each request
- Ability to extend the server yourself
- This allows you to utilise docpad while adding in your own server-side logic
- Version checking
- Always stay up to date
- Mix and match renderers; e.g.
file.html.md.eco
- Easy plugin infrastructure
DocPad is getting pretty popular these days... you can check out a bunch of websites already using it here, and discover the awesomely handsome crew behind the community here. Ocassionally we also hold events and competitions where you can learn more about docpad, hack with others together, and win some cool stuff! Nifty.
On that note, DocPad is awesomely extensible. You can download other people's plugins and use them in real quick, or even write your own in matters of minutes.
Thanks. DocPad loves you.
-
Install dependencies
npm install -g coffee-script
-
Install DocPad
npm install -g docpad
-
If you also want growl notifications (OSX), then install the growl command line tool here
Getting errors? Try troubleshooting
-
Firstly, make a directory for your new website and cd into it
mkdir my-new-website cd my-new-website
-
To get started, simply run the following - it will run all the other commands at once
docpad run
-
To generate a basic website structure in the current working directory if we don't already have one
docpad scaffold
-
To regenerate the rendered website
docpad generate
-
To regenerate the rendered website automatically whenever we make a change to a file
docpad watch
-
To run the docpad server which allows you to access the generated website in a web browser
docpad server
Getting errors? Try troubleshooting
-
v2.5 December 15, 2011
- Swapped out Dominic Baggott's Markdown.js for Isaac Z. Schlueter's Github-Flavored-Markdown
- Now adds support for inline html in markdown files
- Closes #107
- Now adds support for inline html in markdown files
- Fixed plugin installation on windows
- Had to disable the AutoUpdate and Html2Jade plugins
- Had to use the global npm instance on windows
- Closes #111
- Fixed the error:
Object #<Object> has no method 'error'
- Fixes #106
- Fixed
html2jade
on windows- Closes #110
- Can now pass over options to the coffeekup renderer inside the coffee plugin
- E.g. set
docpad: plugins: coffee: coffeekup: format: true
to have tidy html output - Thanks to Changwoo Park
- E.g. set
- Disabled the following plugins by default
- Admin
- Authenticate
- Rest
- AutoUpdate
- Buildr
- Html2Jade
- Updated depdencies
- Commander 0.3.x -> 0.5.x - changelog
- Growl 1.1.x -> 1.2.x - changelog
- NPM 1.0.x -> 1.1.x
- Jade 0.17.x -> 0.19.x - changelog
- Stylus 0.19.x -> 0.20.x - changelog
- Nib 0.2.x -> 0.3.x - changelog
- Swapped out Dominic Baggott's Markdown.js for Isaac Z. Schlueter's Github-Flavored-Markdown
-
v2.4 November 26, 2011
- AutoUpdate plugin
- Automatically refreshes the user's current page when the website is regenerated
- Very useful for development, though you probably want to disable it for production
- Enabled by default
- AutoUpdate plugin
-
v2.3 November 18, 2011
- Heroku support
- Added
extendServer
configuration option- Now, by default, even if the server is provided, we will extend it. If you do not want this, set this configuration option to
false
.
- Now, by default, even if the server is provided, we will extend it. If you do not want this, set this configuration option to
- Made it easier to load docpad as an easier
- Instead of crashing when an uncaught error happens, it'll output it and keep running as often they are not major problems.
- The log messages and next handling in
docpad.action
has been cleaned up- Now those log messages are contained within the default next handler, so if you provide a custom default next handler you'll have to do your own success log messages
- NPM is now installed locally
- This is to ensure it's availability on cloud servers
- DocPad will now try and figure out the node executable location to provide greater compatibility on cloud servers
- If the plugin installations are taking a while, you'll get informed of this, rather than just staring at a blank blinking cursor
- Roy plugin
- Adds Roy to JavaScript support
.js.roy
- Adds Roy to JavaScript support
-
v2.2 November 14, 2011
- Windows support!
- Now uses Benjamin Lupton's Watchr as the watcher library
- Provides windows support
- Now uses Tim Caswell's Haml.js as the haml library
- Provides windows support
- Bug fixes
- Works with zero documents
- Works with empty
package.json
- Fixed mime-type problems with documents
-
v2.1 November 10, 2011
- Support for dynamic documents
- These are re-rendered on each request, must use the docpad server
- See the search example in the kitchensink skeleton
- Removed deprecated
@Document
,@Documents
, and@Site
from thetemplateData
(the variables available to the templates). Use their lowercase equivalants instead. This can cause backwards compatibility problems with your templates, the console will notify you if there is a problem. - Fixed
docpad --version
returningnull
instead of the docpad version
- Support for dynamic documents
-
v2.0 November 8, 2011
- Upgrade guide for 1.x users
- Tested and working on Node 0.4, 0.5, and 0.6
- Windows support is still to come - track it's progress here
- Configurable via
package.json
- DocPad is now configurable via it's and your website's
package.json
file
- DocPad is now configurable via it's and your website's
- New plugin architecture
- Plugins must now be isolated in their own directory
- Plugins can now have their own
package.json
file- Use this for specifying plugin configuration, dependencies, etc
- Plugin events have been renamed to before/after
- New before/after events have been added
docpad
andlogger
are now local variables, rather than passed arguments- Arguments are still kept for backwards compatibility - this may change
- Generation changes
- Rendering is now a 2-pass process
- Contextualize is now a sub-step of parse, instead of it's own main step
- Better simplicity, less complexity
- Documents can now have multiple urls
- These are customisable via the document's
urls
array property
- These are customisable via the document's
- Plugin Changes
- REST plugin supports saving document data via POST (disabled by default)
- Administration plugin adds front-end admin functionality (disabled by default)
- See the client side editing example in the kitchensink skeleton
- SASS plugin
- Adds SASS to CSS support
- Uses TJ Holowaychuk's Sass.js
- Adds SASS to CSS support
- Coffee Plugin
- Removed CoffeeCSS support as was playing up
-
v1.4 October 22, 2011
- Template engines now have access to node.js's
require
- Less Plugin
- Added LessCSS to CSS support
- Uses Alexis Sellier's Less.js
- Added LessCSS to CSS support
- Fixed NPM warning about incorrect property name
- Logged errors will now also output their stacktraces for easier debugging
- If an error occurs during rendering of a document, docpad will let us know which document it happened on
- Template engines now have access to node.js's
-
v1.3 October 3, 2011
- Parsing is now split into two parts
parsing
andcontextualizing
- Contextualizing is used to determine the result filename, and title if title was not set
- The code is now more concise
- File class moved to
lib/file.coffee
- Prototypes moved to
lib/prototypes.coffee
- Version checking moved to bal-util
- File class moved to
- File properties have changed
basename
is extensionlessfilename
now contains the file's extnesionsid
is now therelativeBase
instead of theslug
extensionRendered
is the result extensionfilenameRendered
is the result filename: `"#{basename}.#{extensionRendered}"title
if now set tofilenameRendered
if not set
- Added support for different meta parsers, starting with CoffeeScript and YAML support. YAML is still the default meta parser.
- The YAML dependency is specifically set now to v0.2.1 as the newer version has a bug in it.
- Fixed multiple renderers for a single document. E.g.
file.html.md.eco
- Now also supports using
###
along with---
for wrapping the meta data - Supports the
public
alias for thefiles
directory
- Parsing is now split into two parts
-
v1.2 September 29, 2011
- Plugins now conform to a .plugin.coffee naming standard
- Dependencies now allow for minor patches
- Stylus Plugin
- Added Stylus to CSS support
- Uses TJ Holowaychuk's Stylus
- Added Stylus to CSS support
- Jade Plugin
- Added HTML to Jade support
- Uses Don Park's Html2Jade
- Added HTML to Jade support
- Coffee Plugin
- Added CoffeeCSS to CSS support
- Uses James Campos's CCSS
- Added CoffeeCSS to CSS support
- Fixed incorrect date sorting for documents
- Thanks to Olivier Bazoud for the heads up
-
v1.1 September 28, 2011
- Added Buildr Plugin so you can now bundle your scripts and styles together :-)
- The
action
method now supports an optional callback- Thanks to #41 by Aaron Powell
- Added a try..catch around the version detection to ensure it never kills docpad if something goes wrong
- Skeletons have been removed from the repository due to circular references. The chosen skeleton is now pulled during the skeleton action. We also now perform a recursive git submodule init and update, as well as a npm install if necessary.
-
v1.0 September 20, 2011
- Upgrade guide for v0.x users
- The concept of template engines and markup languages have been merged into the concept of renderers
- Coffee Plugin
- Added CoffeeKup to anything and HTML to CoffeeKup support
- Added CoffeeScript to JavaScript and JavaScript to CoffeeScript support
- Added a Commander.js based CLI
- Thanks to ~eldios
- Added support for Growl notificaitons
- Added asynchronous version comparison
-
v0.10 September 14, 2011
- Plugin infrastructure
- Better logging through Caterpillar
- HAML Plugin
- Added HAML to anything support
- Uses TJ Holowaychuk's HAML
- Added HAML to anything support
- Jade Plugin
- Added Jade to anything support
- Uses TJ Holowaychuk's Jade
- Added Jade to anything support
-
v0.9 July 6, 2011
- No longer uses MongoDB/Mongoose! We now use Query-Engine which doesn't need any database server :)
- Watching files now working even better
- Now supports clean urls :)
-
v0.8 May 23, 2011
- Now supports mutliple skeletons
- Structure changes
-
v0.7 May 20, 2011
- Now supports multiple docpad instances
-
v0.6 May 12, 2011
- Moved to CoffeeScript
- Removed highlight.js (should be a plugin or client-side feature)
-
v0.5 May 9, 2011
- Pretty big clean
-
v0.4 May 9, 2011
- The CLI is now working as documented
-
v0.3 May 7, 2011
- Got the generation and server going
-
v0.2 March 24, 2011
- Prototyping with disenchant
-
v0.1 March 16, 2011
- Initial commit with bergie
DocPad wouldn't be possible if it wasn't for the following libaries (in alphabetical order)
-
Alexis Sellier's Less.js - Leaner CSS
-
Andrew Schaaf's Watch-Tree - Node.js file watching made easy
-
Benjamin Lupton's Bal-Util - Node.js made easy
-
Benjamin Lupton's Caterpillar - Logging made easy
-
Benjamin Lupton's Query-Engine - The MongoDB Query-Engine without the Database
-
Benjamin Lupton's Watchr - Node.js recursive directory watching made easy
-
Brandon Bloom's Html2CoffeeKup - HTML to CoffeeKup Converter
-
Brian McKenna's Roy - JavaScript melded with static language features
-
Don Park's Html2Jade - HTML to Jade Converter
-
Isaac Z. Schlueter's Github-Flavored-Markdown - Github's flavor of markdown
-
Isaac Z. Schlueter's NPM - The node package manager
-
James Campos' CCSS - CSS as CoffeeScript
-
Jeremy Ashkenas' CoffeeScript - JavaScript made easy
-
Jeremy Ashkenas/DocumentCloud's Underscore - The utility-belt library for JavaScript
-
Maurice Machado's CoffeeKup - Markup as CoffeeScript
-
Sam Stephenson's Eco - Embedded CoffeeScript templates
-
Tim Caswell's Haml.js - Markup haiku
-
TJ Holowaychuk's Commander.js - Console apps made easy
-
TJ Holowaychuk's Express.js - The "Server" in Server Side Javascript
-
TJ Holowaychuk's Jade - A robust, elegant, feature rich template engine
-
TJ Holowaychuk's Node-Growl - Notifications made easy
-
TJ Holowaychuk's Sass.js - Syntactically awesome stylesheets
-
TJ Holowaychuk/LearnBoost's Stylus - Expressive, robust, feature-rich CSS language
-
TJ Holowaychuk's YAML - Data made easy
-
Ryan Dahl's Node.js - Server Side Javascript
Licensed under the MIT License Copyright 2011 Benjamin Arthur Lupton