# 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](/community/plugins.md).

### 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docpad.bevry.me/core/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.