docpad/docpad

Empower your website frontends with layouts, meta-data, pre-processors (markdown, jade, coffeescript, etc.), partials, skeletons, file watching, querying, and an amazing plugin system. DocPad will streamline your web development process allowing you to craft powerful static sites quicker than ever before.

DocPad. Streamlined web development.

Hi! I'm DocPad, I streamline the web development process and help close the gap between experts and beginners. I've been used in production by big and small companies for over a year and a half now to create plenty of amazing and powerful web sites and applications quicker than ever before. What makes me different is instead of being a box to cram yourself into and hold you back, I'm a freeway to what you want to accomplish, just getting out of your way and allowing you to create stuff quicker than ever before without limits. Leave the redundant stuff up to me, so you can focus on the awesome stuff.

Discover my features below, or skip ahead to the installation instructions to get started with a fully functional pre-made website in a few minutes from reading this.

Watch the Screencast!

Features

Out of the box

• Completely file based, meaning there are no pesky databases that need to be installed, and for version control you get to use systems like Git and SVN, which you're already used to (You can still hook in remote data sources if you want, DocPad doesn't impose any limits on you, ever)
• Choose from plenty of community maintained pre-made websites to use for your next project instead of starting from scratch every time
• Write your documents in any language, markup, templating engine, or pre-processor you wish (we're truly agnostic thanks to your plugin system). You can even mix and match them when needed by combining their extensions in a rails-like fashion (e.g. coffee-with-some-eco.js.coffee.eco)
• Changes to your website are automatically recompiled through our built-in watch system
• Add metadata to the top of your files to be used by templating engines to display non-standard information such as titles and descriptions for your documents
• Display custom listings of content with our powerful Query Engine available to your templating engines
• Abstract out generic headers and footers into layouts using our nested layout system
• For simple static websites easily deploy your generated website to any web server like apache or github pages. For dynamic projects deploy them to servers like heroku to take advantage of custom routing with express.js. Deploy guide here
• Built-in server to save you from having to startup your own, for dynamic deployments this even supports things like clean urls, custom routes and server-side logic
• Robust architecture and powerful plugin system means that you are never boxed in. Unlike traditional CMS systems, you can always extend DocPad to do whatever you need it to do, and you can even write to bundle common custom functionality and distribute them through the amazing node package manager npm
• Built-in support for dynamic documents (e.g. search pages, signup forms, etc), so you can code pages that change on each request by just adding dynamic: true to your document's meta data (exposes the express.js req and res objects to your templating engine)
• You can use it standalone, or even easily include it within your existing systems with our API

With our amazing community maintained plugins

• Use the Live Reload plugin to automatically refresh your web browser whenever a change is made, this is amazing
• Pull in remote RSS/Atom/JSON feeds into your templating engines allowing you to display your latest twitter updates or github projects easily and effortlessly using the Feedr Plugin
• Support for every templating engine and pre-processor under the sun, including (but not limited to) CoffeeScript, CoffeeKup, ECO, HAML, Handlebars, Jade, Less, Markdown, PHP, Ruby, SASS and Stylus - the full listing is here
• Use the Partials Plugin to abstract common pieces of code into their own individual file that can be included as much as you want
• Syntax highlight code blocks automatically with either our Highlight.js Plugin or Pygments Plugin
• Get SEO friendly clean URLs with our Clean URLs Plugin (dynamic deployments only)
• Lint your code automatically with our Ling Plugins: jshint and coffeelint
• Concatenate and minify your JavaScript and CSS assets making page loads faster for your users with our Minify Plugins: htmlmin and grunt
• Install common javascript libraries like jQuery, Backbone and Underscore directly from the command line - (under construction, coming soon)
• Automatically translate your entire website into other languages with our Translation Plugin - under construction, coming soon
• Add an admin interface to your website allowing you to edit, save and preview your changes on live websites then push them back to your source repository with the Admin Plugins
• Pretty much if DocPad doesn't already do something, it is trivial to write a plugin to do it. DocPad can accomplish anything; it never holds you back, and there are no limits.
• Many other plugins not listed here that are still definitely worth checking out! :)

People love DocPad

All sorts of people love DocPad, from first time web developers to even industry leaders and experts. In fact, people even migrate to DocPad from other systems as they love it so much. Here are some our favourite tweets of what people are saying about DocPad :)

Install

Click here for our latest Install Instructions.

Quick Start

Click here to skip ahead to our latest Quick Start Guide.

What next?

Here are some quick links to help you get started:

• Getting Started
• Frequently Asked Questions
• Showcase and Examples
• Guides and Tutorials
• Deployment Guide
• Extension Guide
• Plugins
• Troubleshooting
• Support

History

Discover the release history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

• Benjamin Lupton — view contributions
• Michael Duane Mooring — view contributions
• Rob Loach — view contributions

Sponsors

These amazing people have contributed finances to this project:

• Jean-Luc Geering
• Nikolas Jeker
• Lee Discoll
• Ángel González
• Scott Kempson
• Myplanet Digital
• Meeho!
• Prismatik
• hybris

Become a sponsor!

Contributors

These amazing people have contributed code to this project:

• Aaron Powell — view contributions
• Adrian Olaru — view contributions
• Adrian Olaru — view contributions
• Alex Mesarosh — view contributions
• Andrew Patton — view contributions
• Anton W — view contributions
• Anton Wilhelm
• Aron Gabor — view contributions
• Bahtiar Gadimov — view contributions
• Ben Barber — view contributions
• Benjamin Lupton — view contributions
• Bruno Heridet — view contributions
• Changwoo Park — view contributions
• Chase Colman — view contributions
• Craig Smith — view contributions
• Darío Villanueva — view contributions
• Eduardo Lavaque — view contributions
• Firede
• Homme Zwaagstra — view contributions
• Ivan Klimchuk — view contributions
• JT Turner — view contributions
• Ke Zhu
• Ke Zhu
• Lukasz Gornicki
• Luke Hagan — view contributions
• Michael Duane Mooring — view contributions
• Morgan Larosa — view contributions
• Nathan Friedly — view contributions
• Neil Taylor — view contributions
• Nick Crohn — view contributions
• Nick Matantsev — view contributions
• Olivier Bazoud — view contributions
• Paul Armstrong — view contributions
• Pavan Gupta — view contributions
• Peter Flannery — view contributions
• Prayag Verma — view contributions
• Richard A — view contributions
• Rob Loach — view contributions
• Shih-Yung Lee — view contributions
• Sorin Ionescu — view contributions
• Stefanos Grammenos — view contributions
• Steve Mc — view contributions
• Sven Vetsch — view contributions
• Tatu Tamminen — view contributions
• Todd Anglin — view contributions
• Vladislav Botvin — view contributions
• Zearin — view contributions
• alexwoehr — view contributions
• asyncapi-bot — view contributions
• eldios — view contributions
• pavangupta — view contributions
• ruemic — view contributions
• vsopvsop — view contributions

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Participants

Also thanks to all the countless others who have continued to raise DocPad even higher by submitting plugins, issues reports, discussion topics, IRC chat messages, and praise on twitter. We love you.

License

Unless stated otherwise all works are:

• Copyright © 2012+ Bevry Pty Ltd
• Copyright © Benjamin Lupton

and licensed under:

• MIT License

docpad's Issues

Skeleton: Getting Started (currently bootstrap)

Brainstorm the development of the getting started skeleton here.

Skeleton: Blog

Need a good blog skeleton

Broken angle brakets in code sections

In code sections angle brakets like the following

<x>

get finally displayed as

<x>

and the HTML source for it is

<pre><code>&amp;<span class="keyword">lt</span>;<span class="keyword">x</span>&amp;<span class="keyword">gt</span>;</code></pre>

The < and > should not be taken apart as it breaks the interpretation of these HTML entities.

Header section parsing

A working doc:

---
layout: post
title: "xyz"
tags:
    - abc
date: '2011-03-24'

---

content

A doc that breaks the page/design:

---
layout: post
title: "xyz"
tags:
    - abc
date: '2011-03-24'

---

---

content

The parsing should be improved in a way, that the 3th appearance of --- is considered to be normal content.

Doc: Better "Extending" docs

Someone really needs to spend a day or two upgrading https://github.com/balupton/docpad/wiki/Extending to be awesome.

@bevry has some funding available to help this task along (for whoever wants to pick it up).

How to do multilingual websites?

As a User, I want the ability to localise my content, so that my Visitors can experience my website in their language

Open to suggestions on how such a plugin can be executed

---

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.

GitHub Pages Deploy Plugin

After a generate has finished, it should wipe the gh-pages branch, copy the contents of the original out directory into it, add the changes, commit them, and check back to the original branch.

As a User, I want the ability to create a wiki, so that I ...

Blocked.... needs value add, and needs use case.

Core: Adding scaffolding support

Not sure how this will work.... open to discussion.

As a User, I want the includes/partials, so that I can abstract out common code

It would be great if I could directly include another template into a layout. Something that works kind of like Rails or django.

Plugin: CCSS

It'd be cool if the coffeescript plugin supported ccss (https://github.com/aeosynth/ccss) so you could do your whole website in coffeescript!

Plugin: Buildr

Adding support for Buildr during generation would be nice, as whenever a generation happens it could rebundle and compress your css and javascript files, as well as compress your images in the out dir.

Core: Restructuring to allow for REST Interface

DocPad could do with some restructuring to support a REST interface.

published: false in YAML header

Hi Benjamin

Following Jekyll convention, may I suggest that we add an optional published variable in the YAML header of documents files ? When set to false, this will avoid parsing and copying a draft from src to out.

Thanks for the work you've accomplished so far.

News: Hiring and Funding Available :-)

My company @bevry has a few docpad related tasks that up for delegation. Check out https://gist.github.com/1192028 for more details.

Jade and HAML could be templating engines too

This would be quite involved, as it would mean taking the templating engine out of the core and inserting it into a plugin.

It would also mean breaking the barriers between templating engines and markup languages. Which may not be that difficult as we do have priorities, though it does require a fair bit of brainstorming.

Plugin: Stylus

Core: Better Plugin Detection

To support more intense and more involved plugins, when scanning the plugins directory, we should only load in files which end in the extension .plugin.coffee or .plugin.js. Instead of all .js and .coffee files.

Core: Windows support

Windows support would be awesome.

@bevry has some funding available for whoever wants to undergo this task

Plugin: Administration Infrastructure

Requirements

• Login via github
• Github will check the contributors to see if you have write access
• If a document is a wiki document, everyone has write access (still need to login via github though)
• Saving changes will happen with git commits, with specifying the git author (as we have their github details)
• Editing panel will be fixed at the bottom, when logged in, they click edit, this will open a file editor with a dropdown of documents and a ACE editor
• Editing may or may not support nowpad
• They will be able to see their changes rendered in realtime via an exposed REST API
• They will only be able to edit documents
• Edits on wiki documents will be santized
• Create new documents
• Dependent on jQuery

Out of scope

• Editing layouts
• Editing files
• Use Cloud9 for those

Depends on

• plugin infrastructure #16

Modules to develop

• rest plugin
• admin UI and accompanying backend interface
• github auth
• github/git api hooks

Hiring?

Yes. Details to come.

Plugin: PDF Renderer

Plugin: Table of Contents

The ability to generate a table of contents would be useful.

Perhaps made available through a (configurable) helper function.

Perhaps delivered as a plugin so that different implementations could exist for different types of output.

HTML5 adds a complication for document structure in its use of sections, so a straightforward analysis of H1-H6 headings may not be enough for all users.

Automatically init submodules if they aren't already

As a User, I want server-side syntax highlighting, as pygments rocks

Probably could be left for the client side, though up for experimentation.

Just keeps refreshing when watch is turned on

WordPress Importer

As a User, I want the ability to import my wordpress data, so that migration will be a lot easier

See obazoud@e21b10f for reference.

Pull request here: #78

---

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.

Add plugin infrastucture

There needs to be a way to customise inject extra functionality into docpad.

Implement a proper CLI (--help, generate [thing]) etc.

Starting in my home directory, I naively typed:

npm install docpad -g
docpad --help

This resulted in my home directory being filled with scaffolding crap that I had to remove by hand. Pretending to have a CLI when you don't have -h or --help implemented is just a minor annoyance, and I could even put up with the fact that DocPad spits stuff into ./ instead of responding to docpad generate foo to create something in ./foo/ like every other scaffolding app in existence, but having a script that defaults to making a mess when it gets a unrecognized command? That's just plain rude.

I'd hate to see what would have happened if I already had stuff in ~/src/ or ~/out/.

Riley

Add twitter bootstrap skeleton for docpad / use as default

Started here: https://github.com/balupton/bootstrap.docpad

Still needs work

Docpad.server conflict

Docpad.server is used for the server object, and the create server function.

Plugin: Site Mapper

For generating seo site mappings

Plugin: LessCSS

Tumblr Importer

Jekyll Migrator

---

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.

Core: No obvious way to choose different out location

I want to have docpad generate my site in a different folder, not a subfolder of the project. There's no obvious way of doing this.

Other than that, looks nice and straighforward - thanks!

Don't copy your personal webpage as a skeleton

Either create an example website, or copy an empty folder tree.

Core: Do not copy hidden files from skeleton

When "docpad scaffold", docpad copies all files and directories.
It should not copy .git directory and overrides an existing .git

Plugin: Search

Story

Some blogs may have a lot of content, in which case search is useful. Though in most cases it isn't actually that useful as main navigation is quite typical.

Implementation

Dynamic

Can already be implemented as a dynamic document, see kitchensink example

Plugin

Search should be a extension which plugs into the serverFinished event, and utilise the server param.

It should take in urls like:

/search/query/search+title+and+content
/search/tags/tag1+tag2+tag3+three-word-tag+tag5

And generate a search results page which is displayed with a configurable layout.

---

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.

Eliminate MongoDB Requirement

Really all we need is the MongoDB selector/query engine, and not the database itself. The query engine can be coded up natively in javascript.

Related to:
http://stackoverflow.com/questions/6110606/nosql-mongodb-style-query-engine-in-node-js

typo in 'Huh? 2.6'

Where you say 'display the all titles', that should be 'display all the titles'.

Missing skeleton files

I've just installed with npm, and I can't get docpad to run due to missing skeleton files. This is the error:

Copying the skeleton [balupton] to [/me/mydocpad]
bal-util.scandir: readdir has failed on: /usr/local/lib/node_modules/docpad/lib/../skeletons/balupton
done

/usr/local/lib/node_modules/docpad/lib/docpad.coffee:569
throw err;
^
Error: ENOENT, No such file or directory

Do I need to manually pull your balupton.docpad repository? Or, is there an official set of skeleton files that's missing from the docpad repository?

(btw, this project, filepad and nowpad look very cool -- looking forward to trying them each out)

Core: Version checking at startup

We should scan the github package.json to compare versions. Should only happen if we have a Internet connection, and should be asynchronous.

Add coffeekup support

http://coffeekup.org/

Plugin: page,doc,docx,rtf,odt renderers

While it is an extreme longshot, could be interesting.

---

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.

Core: Add a growl notification if version outdated

As a User, I want a skeleton for book writing, so that I can focus on writing my book and not the setup

@disenchant's use case requires generated pages to be printable, and include page headers, footers, and page numbers.

Further reading:
http://stackoverflow.com/questions/6109893/page-numbers-with-css-html/6109932#6109932

Sample project:
https://github.com/balupton/printing.docpad

Doesn't imply it is dependent on the PDF features, as it could be a HTML book. In which case it is just structure and styling.

Make logging levels customisable

As a User, I want multiple layouts per document, so that I can export to multiple formats at once

E.g. book-chapter1.html.md could export to two layouts book-chapter.html and book-chapter.pdf.html, so it can be exported to both html and pdf at the same time.

As a User, I want support for Moustache, so that I can use my preferred markup

Core: CSON support for headers

I'm thinking that initially we should try and parse CSON for the header, if that files then we try and parse YAML. Or for CSON we utilise === instead of ---