​DocPad has auto-generated Technical API from its source code, check it out!​
Besides having Node.js installed, you'll want to install DocPad locally to your project, you can do this by running npm install --save docpad
in your command line. This will install DocPad into ./node_modules/docpad
and make it accessible via Node.js's require function (e.g., require('docpad')
)
If you are wanting to utilise DocPad for rendering, you'll also want to install some rendering Plugins.
Firstly, you need to create your DocPad instance, you can do this like so:
var docpadInstanceConfiguration = {};require('docpad').createInstance(docpadInstanceConfiguration, function(err,docpadInstance){if (err) return console.log(err.stack);// ...});
You can use DocPad as a module to render individual files very easily. This allows you to utilise DocPad for all the rendering inside your application, instead of having to write and maintain specific wrappers for each rendering engine yourself.
var renderOpts = {text: 'here is some **markdown**',filename:'markdown',renderSingleExtensions:true};docpadInstance.action('render', renderOpts, function(err,result){console.log(result);});
var renderOpts = {path: '/some/file.html.md',renderSingleExtensions:true};docpadInstance.action('render', renderOpts, function(err,result){console.log(result);});
Here is how you would normalise common tasks you would typically achieve with the DocPad command line interface.
// `generateOpts` is optionalvar generateOpts = {collection: docpad.getCollection("myChangedPages"), // only regenerate a subsetreset:true // default};// Which means it doesn't have to be included in the function call belowdocpadInstance.action('generate', generateOpts, function(err,result){if (err) return console.log(err.stack);console.log('OK');});
docpadInstance.action('server', function(err,result){if (err) return console.log(err.stack);console.log('OK');});
You can combine actions by separating them with a space, like so:
docpadInstance.action('generate server', function(err,result){if (err) return console.log(err.stack);console.log('OK');});
docpadInstance.action('generate watch', function(err,result){if (err) return console.log(err.stack);console.log('OK');});
DocPad using Backbone.js for its Models, and QueryEngine for its Collections. Providing a powerful database that you can query in a noSQL type fashion.
database = docpadInstance.getDatabase()
document = docpadInstance.createDocument(data, options)file = docpadInstance.createFile(data, options)
database = docpadInstance.getDatabase()document = docpadInstance.createDocument(data, options)file = docpadInstance.createFile(data, options)database.add(document)database.add(file)
// options = {path}// next(err, files)docpadInstance.parseDocumentDirectory(options, next)docpadInstance.parseFileDirectory(options, next)
// Get files, returns a cached live collectionresultCollection = docpadInstance.getFiles(query, sorting, paging)​// Get a fileresultModel = docpadInstance.getFile(query, sorting, paging)​// Get files at path (forwards onto getFiles)resultCollection = docpadInstance.getFilesAtPath(path, sorting, paging)​// Get a file at a relative or absolute path or URLresultModel = docpadInstance.getFileAtPath(path, sorting, paging)​// Get a file by its idresultModel = docpadInstance.getFileById(id, {collection:null})​// Get a file by a route, useful when doing server requestsdocpadInstance.getFileByRoute(url, function(err, resultModel){if ( err ) console.log(err.stack)})
​For more information about Querying, check out this FAQ Entry.​
If you already have an Express.js application, you can do the following to just stick DocPad straight ontop of it:
// Create Server and Express Applicationvar express = require('express');var http = require('http');var app = express();var server = http.createServer(app).listen(8080);​// Add our Application Middlewaresapp.use(app.router);​// Add DocPad to our Applicationvar docpadInstanceConfiguration = {// Give it our express application and HTTP serverserverExpress: app,serverHttp: server,​// Tell it not to load the standard middlewares (as we handled that above)middlewareStandard: false};var docpadInstance = require('docpad').createInstance(docpadInstanceConfiguration, function(err){if (err) return console.log(err.stack);​// Tell DocPad to perform a generation, extend our server with its routes, and watch for changesdocpadInstance.action('generate server watch', function(err){if (err) return console.log(err.stack);});});​// Continue with your application// ...
Here is some code for manually rendering a document (inside src/render
) with a custom route:
app.get '/alias-for-home', (req,res,next) ->req.templateData = {weDidSomeCustomRendering: true};var document = docpadInstance.getFile({relativePath:'home.html.md'});docpadInstance.serveDocument({document, req, res, next});