# API

### Technical API <a href="#technical-api" id="technical-api"></a>

[DocPad has auto-generated Technical API from its source code, check it out!](http://master.docpad.docpad.surge.sh/docs/)

### Install DocPad <a href="#install-docpad" id="install-docpad"></a>

Besides having [Node.js installed](https://learn.bevry.me/node/install), 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](http://nodejs.org/docs/latest/api/all.html#all_require) (e.g., `require('docpad')`)

If you are wanting to utilise DocPad for rendering, you'll also want to install some rendering [Plugins](https://docpad.bevry.me/community/plugins).

### Create your DocPad Instance <a href="#create-your-docpad-instance" id="create-your-docpad-instance"></a>

Firstly, you need to create your DocPad instance, you can do this like so:

```javascript
var docpadInstanceConfiguration = {};
require('docpad').createInstance(docpadInstanceConfiguration, function(err,docpadInstance){
    if (err)  return console.log(err.stack);
    // ...
});
```

### Rendering individual files <a href="#rendering-individual-files" id="rendering-individual-files"></a>

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 <a href="#render-some-text-with-docpad" id="render-some-text-with-docpad"></a>

```javascript
var renderOpts = {
    text: 'here is some **markdown**',
    filename:'markdown',
    renderSingleExtensions:true
};
docpadInstance.action('render', renderOpts, function(err,result){
    console.log(result);
});
```

#### Render a file path with DocPad <a href="#render-a-file-path-with-docpad" id="render-a-file-path-with-docpad"></a>

```javascript
var renderOpts = {
    path: '/some/file.html.md',
    renderSingleExtensions:true
};
docpadInstance.action('render', renderOpts, function(err,result){
    console.log(result);
});
```

### DocPad CLI Actions <a href="#docpad-cli-actions" id="docpad-cli-actions"></a>

Here is how you would normalise common tasks you would typically achieve with the DocPad command line interface.

#### Performing a generation <a href="#performing-a-generation" id="performing-a-generation"></a>

```javascript
// `generateOpts` is optional
var generateOpts = {
    collection: docpad.getCollection("myChangedPages"),  // only regenerate a subset
    reset:true                                           // default
};
// Which means it doesn't have to be included in the function call below
docpadInstance.action('generate', generateOpts, function(err,result){
    if (err)  return console.log(err.stack);
    console.log('OK');
});
```

#### Start the DocPad server <a href="#start-the-docpad-server" id="start-the-docpad-server"></a>

```javascript
docpadInstance.action('server', function(err,result){
    if (err)  return console.log(err.stack);
    console.log('OK');
});
```

#### Generate and Start the DocPad Server <a href="#generate-and-start-the-docpad-server" id="generate-and-start-the-docpad-server"></a>

You can combine actions by separating them with a space, like so:

```javascript
docpadInstance.action('generate server', function(err,result){
    if (err)  return console.log(err.stack);
    console.log('OK');
});
```

#### Perform an initial generation, then watch files and regenerate when a change occurs <a href="#perform-an-initial-generation-then-watch-files-and-regenerate-when-a-change-occurs" id="perform-an-initial-generation-then-watch-files-and-regenerate-when-a-change-occurs"></a>

```javascript
docpadInstance.action('generate watch', function(err,result){
    if (err)  return console.log(err.stack);
    console.log('OK');
});
```

### Using the Database <a href="#using-the-database" id="using-the-database"></a>

DocPad using [Backbone.js](http://backbonejs.org/) for its Models, and [QueryEngine](https://github.com/bevry/query-engine) for its Collections. Providing a powerful database that you can query in a noSQL type fashion.

#### Get the database <a href="#get-the-database" id="get-the-database"></a>

```javascript
database = docpadInstance.getDatabase()
```

#### Create a Document and File <a href="#create-a-document-and-file" id="create-a-document-and-file"></a>

```javascript
document = docpadInstance.createDocument(data, options)
file = docpadInstance.createFile(data, options)
```

#### Create a Document and File, then add it to the Database <a href="#create-a-document-and-file-then-add-it-to-the-database" id="create-a-document-and-file-then-add-it-to-the-database"></a>

```javascript
database = docpadInstance.getDatabase()
document = docpadInstance.createDocument(data, options)
file = docpadInstance.createFile(data, options)
database.add(document)
database.add(file)
```

#### Parse a Document and File Directory <a href="#parse-a-document-and-file-directory" id="parse-a-document-and-file-directory"></a>

```javascript
// options = {path}
// next(err, files)
docpadInstance.parseDocumentDirectory(options, next)
docpadInstance.parseFileDirectory(options, next)
```

#### Querying <a href="#querying" id="querying"></a>

```javascript
// Get files, returns a cached live collection
resultCollection = docpadInstance.getFiles(query, sorting, paging)

// Get a file
resultModel = 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 URL
resultModel = docpadInstance.getFileAtPath(path, sorting, paging)

// Get a file by its id
resultModel = docpadInstance.getFileById(id, {collection:null})

// Get a file by a route, useful when doing server requests
docpadInstance.getFileByRoute(url, function(err, resultModel){
    if ( err )  console.log(err.stack)
})
```

[For more information about Querying, check out this FAQ Entry.](https://docpad.org/docs/faq#what-is-findalllive)

### Using with Express <a href="#using-with-express" id="using-with-express"></a>

If you already have an Express.js application, you can do the following to just stick DocPad straight ontop of it:

```javascript
// Create Server and Express Application
var express = require('express');
var http = require('http');
var app = express();
var server = http.createServer(app).listen(8080);

// Add our Application Middlewares
app.use(app.router);

// Add DocPad to our Application
var docpadInstanceConfiguration = {
    // Give it our express application and HTTP server
    serverExpress: 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 changes
    docpadInstance.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:

```coffeescript
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});
```

[<br>](https://docpad.org/docs/showcase)