API - DocPad

Search…
API
This page will go over using DocPad as a module, and the API available to you.
Technical API
​DocPad has auto-generated Technical API from its source code, check it out!​
Install DocPad
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.
Create your DocPad Instance
Firstly, you need to create your DocPad instance, you can do this like so:
1
var docpadInstanceConfiguration = {};
2
require('docpad').createInstance(docpadInstanceConfiguration, function(err,docpadInstance){
3
    if (err)  return console.log(err.stack);
4
    // ...
5
});
Copied!
Rendering individual files
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.
Render some text with DocPad
1
var renderOpts = {
2
    text: 'here is some **markdown**',
3
    filename:'markdown',
4
    renderSingleExtensions:true
5
};
6
docpadInstance.action('render', renderOpts, function(err,result){
7
    console.log(result);
8
});
Copied!
Render a file path with DocPad
1
var renderOpts = {
2
    path: '/some/file.html.md',
3
    renderSingleExtensions:true
4
};
5
docpadInstance.action('render', renderOpts, function(err,result){
6
    console.log(result);
7
});
Copied!
DocPad CLI Actions
Here is how you would normalise common tasks you would typically achieve with the DocPad command line interface.
Performing a generation
1
// `generateOpts` is optional
2
var generateOpts = {
3
    collection: docpad.getCollection("myChangedPages"),  // only regenerate a subset
4
    reset:true                                           // default
5
};
6
// Which means it doesn't have to be included in the function call below
7
docpadInstance.action('generate', generateOpts, function(err,result){
8
    if (err)  return console.log(err.stack);
9
    console.log('OK');
10
});
Copied!
Start the DocPad server
1
docpadInstance.action('server', function(err,result){
2
    if (err)  return console.log(err.stack);
3
    console.log('OK');
4
});
Copied!
Generate and Start the DocPad Server
You can combine actions by separating them with a space, like so:
1
docpadInstance.action('generate server', function(err,result){
2
    if (err)  return console.log(err.stack);
3
    console.log('OK');
4
});
Copied!
Perform an initial generation, then watch files and regenerate when a change occurs
1
docpadInstance.action('generate watch', function(err,result){
2
    if (err)  return console.log(err.stack);
3
    console.log('OK');
4
});
Copied!
Using the Database
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.
Get the database
1
database = docpadInstance.getDatabase()
Copied!
Create a Document and File
1
document = docpadInstance.createDocument(data, options)
2
file = docpadInstance.createFile(data, options)
Copied!
Create a Document and File, then add it to the Database
1
database = docpadInstance.getDatabase()
2
document = docpadInstance.createDocument(data, options)
3
file = docpadInstance.createFile(data, options)
4
database.add(document)
5
database.add(file)
Copied!
Parse a Document and File Directory
1
// options = {path}
2
// next(err, files)
3
docpadInstance.parseDocumentDirectory(options, next)
4
docpadInstance.parseFileDirectory(options, next)
Copied!
Querying
1
// Get files, returns a cached live collection
2
resultCollection = docpadInstance.getFiles(query, sorting, paging)
3
​
4
// Get a file
5
resultModel = docpadInstance.getFile(query, sorting, paging)
6
​
7
// Get files at path (forwards onto getFiles)
8
resultCollection = docpadInstance.getFilesAtPath(path, sorting, paging)
9
​
10
// Get a file at a relative or absolute path or URL
11
resultModel = docpadInstance.getFileAtPath(path, sorting, paging)
12
​
13
// Get a file by its id
14
resultModel = docpadInstance.getFileById(id, {collection:null})
15
​
16
// Get a file by a route, useful when doing server requests
17
docpadInstance.getFileByRoute(url, function(err, resultModel){
18
    if ( err )  console.log(err.stack)
19
})
Copied!
​For more information about Querying, check out this FAQ Entry.​
Using with Express
If you already have an Express.js application, you can do the following to just stick DocPad straight ontop of it:
1
// Create Server and Express Application
2
var express = require('express');
3
var http = require('http');
4
var app = express();
5
var server = http.createServer(app).listen(8080);
6
​
7
// Add our Application Middlewares
8
app.use(app.router);
9
​
10
// Add DocPad to our Application
11
var docpadInstanceConfiguration = {
12
    // Give it our express application and HTTP server
13
    serverExpress: app,
14
    serverHttp: server,
15
​
16
    // Tell it not to load the standard middlewares (as we handled that above)
17
    middlewareStandard: false
18
};
19
var docpadInstance = require('docpad').createInstance(docpadInstanceConfiguration, function(err){
20
    if (err)  return console.log(err.stack);
21
​
22
    // Tell DocPad to perform a generation, extend our server with its routes, and watch for changes
23
    docpadInstance.action('generate server watch', function(err){
24
        if (err)  return console.log(err.stack);
25
    });
26
});
27
​
28
// Continue with your application
29
// ...
Copied!
Here is some code for manually rendering a document (inside src/render) with a custom route:
1
app.get '/alias-for-home', (req,res,next) ->
2
    req.templateData = {
3
        weDidSomeCustomRendering: true
4
    };
5
    var document = docpadInstance.getFile({relativePath:'home.html.md'});
6
    docpadInstance.serveDocument({document, req, res, next});
Copied!
​
​
Start - Previous
Performance
Next - Core
Command Line Interface
Last modified 2yr ago
Copy link
Contents
Technical API
Install DocPad
Create your DocPad Instance
Rendering individual files
DocPad CLI Actions
Using the Database
Using with Express