Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

DocPad is the easiest way to create your static website. You have the power of a CMS and simplicity of a notepad. Write your website in the markup of your choice (Markdown, HTML, Jade?), in the editor of your choice (Textmate, Sublime, Notepad?), and deploy anywhere (FTP, Git, localhost?). Total control, total simplicity.

branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

DocPad: It's Like Jekyll.

DocPad (like Jekyll) is a static website generator, unlike Jekyll it's written in CoffeeScript+Node.js instead of Ruby, and also allows the template engine complete access to the document model. This means you have unlimited power as a CMS and the simplicity of a notepad.

Huh?

  1. Say you were to create the following website structure:

    • myWebsite
      • src
        • documents
        • files
        • layouts
  2. 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!**
      
  1. 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>
    
  2. And any files that you have in src/files will be copied to the out directory. E.g. src/files/styles/style.css -> out/styles/style.css

  3. 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)

  4. 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 %>
      
  1. Cool that makes sense... now how did Hello **World!** in our document get converted into Hello <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!

Installing

  1. Install Node.js

  2. Install dependencies

    npm -g install coffee-script
    
  3. Install DocPad

    npm -g install docpad
    
  4. or... install the cutting edge version

    git clone git://github.com/balupton/docpad.git
    cd docpad
    git branch -v
    npm install
    git submodule init
    git submodule update
    npm link
    

Using

  • 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
    

Created With

Core

Renderers

Markups

  • 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

Styles

  • Stylus to CSS .css.stylus
  • CCSS to CSS .css.css|coffee

Scripts

  • CoffeeScript to JavaScript .js.coffee and JavaScript to CoffeeScript .coffee.js

Extensions

DocPad is awesomely extensible, it's easy to add support for new renderers and even add funky new functionality ontop of docpad! Check out what others are making, or learn to make your own extensions here.

Learning

To learn more about DocPad (including using and extending it) visit its wiki here

History

  • v1.2 September 29, 2011

  • 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
    • 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

  • v0.10 September 14, 2011

  • 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

  • v0.1 March 16, 2011

License

Licensed under the MIT License Copyright 2011 Benjamin Arthur Lupton

Something went wrong with that request. Please try again.