The DocPad configuration file sits within the root of your DocPad project and is named as one of the following. Each name provides a special meaning. Here are the valid names:
docpad.js
a Node JavaScript file, will generally look like: module.exports = {/*the configuration*/}
docpad.json
a JSON file, does not allow functions, will generally look like: {/*the configuration*/}
docpad.coffee
a Node CoffeeScript file, will generally look like: module.exports = /*the configuration*/
docpad.cson
a cson file, will generally look like: /*the configuration*/
The advantage of docpad.js
and docpad.coffee
over docpad.json
and docpad.cson
is that they allow us to declare functions, as well as call functions. However, for instances where we cannot trust the contents of the configuration files you would want to use the docpad.json
or docpad.cson
as they can't do anything naughty.
The advantage of docpad.coffee
and docpad.cson
over docpad.js
and docpad.json
is that they allow us to use the CoffeeScript syntax which is a lot more lenient.
Generally, you'll usually find either a docpad.coffee
file or a docpad.cson
file.
The following code is of a docpad.coffee
file that contains every single configurable DocPad options - in reality you should only include the options that you have actually customised - using the following example for reference only.
docpad.coffee# DocPad ConfigurationdocpadConfig = {​# =================================# Paths Configuration​# Root Path# The root path of our our projectrootPath: process.cwd() # default​# Package Path# The project's package.json path# If it is a relative path, it will have the resolved `rootPath` prepended to itpackagePath: 'package.json' # default​# Config Paths# An array of paths that we try to extract our docpad configuration fromconfigPaths: [ # default'docpad.js''docpad.coffee''docpad.json''docpad.cson']​# Plugin Paths# An array of special paths which to load single plugins from# (e.g., ['/a/path/to/a/docpad-plugin-special'])pluginPaths: [] # default​# Plugins Paths# An array of paths which to load multiple plugins frompluginsPaths: [ # default'node_modules''plugins']​# Reload Paths# An array of special paths that when changes occur in, we reload our configurationreloadPaths: [] # default​# Regenerate Paths# An array of special paths that when changes occur in, we regenerate our websiteregeneratePaths: [] # default​# Regenerate Delay# The time (in milliseconds) to wait after a source file has# changed before using it to regenerate. Updating over the# network (e.g., via FTP) can cause a page to be partially# rendered as the page is regenerated *before* the source file# has completed updating: in this case increase this value.regenerateDelay: 100 # default​# Out Path# Where should we put our generated website files?# If it is a relative path, it will have the resolved `rootPath` prepended to itoutPath: 'out' # default​# Src Path# Where can we find our source website files?# If it is a relative path, it will have the resolved `rootPath` prepended to itsrcPath: 'src' # default​# Documents Paths# An array of paths which contents will be treated as documents# If it is a relative path, it will have the resolved `srcPath` prepended to itdocumentsPaths: [ # default'render''documents']​# Files Paths# An array of paths which contents will be treated as files# If it is a relative path, it will have the resolved `srcPath` prepended to itfilesPaths: [ # default'static''files''public']​# Layouts Paths# An array of paths which contents will be treated as layouts# If it is a relative path, it will have the resolved `srcPath` prepended to itlayoutsPaths: [ # default'layouts']​# Ignore Paths# Can be set to an array of absolute paths that we should ignore from the scanning processignorePaths: false # default​# Ignore Hidden Files# Whether or not we should ignore files that start with a dot from the scanning processignoreHiddenFiles: false # default​# Ignore Common Patterns# Whether or not we should ignore commonly undesired files from the scanning process# (e.g., .DStore, thumbs.db, .git, files that start with a tilda, etc.)ignoreCommonPatterns: true # default​# Ignore Custom Patterns# Can be set to a regex of custom patterns to ignore from the scanning processignoreCustomPatterns: false # default​​# =================================# Server Configuration​# Port# Use to change the port that DocPad listens to# By default we will detect the appropriate port number for our environment# if no environment port number is detected we will use 9778 as the port number# Checked environment variables are:# - PORT - Heroku, Nodejitsu, Custom# - VCAP_APP_PORT - AppFog# - VMC_APP_PORT - CloudFoundryport: null # default​# Max Age# The default caching time limit that is sent with the response to the client# Can be set to `false` to disable cachingmaxAge: 86400000 # default​# Server Express# The Express.js instance that we want DocPad to use# If not set, we will create our ownserverExpress: null # default​# Server HTTP# The Node.js HTTP server instance that we want DocPad to use# If not set, we will create our ownserverHttp: null # default​​# =================================# Middleware Configuration# Which middlewares would you like us to activate# Setting `extendServer` to `false` will set all of these to `false` automatically​# Extend Server# Whether or not we should extend the server with our custom middlewareextendServer: true # default​# The standard middlewares (bodeParser, methodOverride, Express router)middlewareStandard: true # default​# The standard bodyParser middlewaremiddlewareBodyParser: true # default​# The standard methodOverride middlewaremiddlewareMethodOverride: true # default​# The standard Express router middlewaremiddlewareExpressRouter: true # default​# Our own 404 middlewaremiddleware404: true # default​# Our own 500 middlewaremiddleware500: true # default​​# =================================# Logging Configuration​# Log Level# Up to which level of logging should we outputlogLevel: (if ('-d' in process.argv) then 7 else 6) # default​# Logger# The caterpillar instance that we want to use# If not set, we will create our ownlogger: null # default​# Growl# Whether or not we should display system notifications as things progress within DocPadgrowl: true # default​# Catch Exceptions# Whether or not DocPad should catch uncaught exceptionscatchExceptions: true # default​# Report Errors# Whether or not we should report errors back to the DocPad TeamreportErrors: process.argv.join('').indexOf('test') is -1 # default (don't enable if we are running inside a test)​# Report Statistics# Whether or not we should report statistics back to the DocPad TeamreportStatistics: process.argv.join('').indexOf('test') is -1 # default (don't enable if we are running inside a test)​# Airbrake Token# The airbrake token we should use for reporting errors# By default, uses the DocPad Team's tokenairbrakeToken: null # default​# MixPanel Token# The mixpanel token we should use for reporting statistics# By default, uses the DocPad Team's tokenmixpanelToken: null # default​​# =================================# Other Configuration​# Detect Encoding# Should we attempt to auto detect the encoding of our files?# Useful when you are using foreign encoding (e.g., GBK) for your files# Only works on unix systems currently (limit of iconv module)detectEncoding: false​# Render Single Extensions# Whether or not we should render single extensions by defaultrenderSingleExtensions: false # default​# Render Passes# How many times should we render documents that reference other documents?renderPasses: 1 # default​# Check Version# Whether or not to check for newer versions of DocPadcheckVersion: false # default​# Welcome# Whether or not we should display any custom welcome callbackswelcome: false # default​# Prompts# Whether or not we should display any promptsprompts: false # default​# Helper Url# Used for subscribing to newsletter, account information, and statistics, etc.helperUrl: 'https://docpad.org/helper/' # default​# Safe Mode# If enabled, we will try our best to sandbox our template rendering so that they cannot modify things outside of them# Not yet implementedsafeMode: false # default​# Collections# A hash of functions that create collectionscollections: {} # default​# Regenerate Every# Performs a regenerate every x milliseconds, useful for always having the latest dataregenerateEvery: false # default​​# =================================# Template Configuration​# Template Data# Use to define your own template data and helpers that will be accessible to your templates# Complete listing of default values can be found here: http://docpad.org/docs/template-datatemplateData: # example​# Specify some site propertiessite:# The production URL of our websiteurl: "http://website.com"​# The default title of our websitetitle: "Your Website"​# The website description (for SEO)description: """When your website appears in search results in say Google, the text here will be shown underneath your website's title."""​# The website keywords (for SEO) separated by commaskeywords: """place, your, website, keywoards, here, keep, them, related, to, the, content, of, your, website"""​​# -----------------------------# Helper Functions​# Get the prepared site/document title# Often we would like to specify particular formatting to our page's title# we can apply that formatting heregetPreparedTitle: -># if we have a document title, then we should use that and suffix the site's title onto itif @document.title"#{@document.title} | #{@site.title}"# if our document does not have its own title, then we should just use the site's titleelse@site.title​# Get the prepared site/document descriptiongetPreparedDescription: -># if we have a document description, then we should use that, otherwise use the site's description@document.description or @site.description​# Get the prepared site/document keywordsgetPreparedKeywords: -># Merge the document keywords with the site keywords@site.keywords.concat(@document.keywords or []).join(', ')​​# =================================# Plugin Configuration​# Skip Unsupported Plugins# Set to `false` to load all plugins whether or not they are compatible with our DocPad version or notskipUnsupportedPlugins: true # default​# Enable Unlisted Plugins# Set to false to only enable plugins that have been explicity set to `true` inside `enabledPlugins`enableUnlistedPlugins: true # default​# Enabled PluginsenabledPlugins: # example# Disable the Pokemon Pluginpokemon: false​# Enable the Digimon Plugin# Unless, enableUnlistedPlugins is set to false, all plugins are enabled by defaultdigimon: true​# Configure Plugins# Should contain the plugin short names on the left, and the configuration to pass the plugin on the rightplugins: # example# Disable NIB within the Stylus Pluginstylus:useNib: false​​# =================================# Event Configuration​# Events# Allows us to bind listeners to the events that DocPad emits# Complete event listing can be found here: http://docpad.org/docs/eventsevents: # example​# Server Extend# Used to add our own custom routes to the server before the docpad routes are addedserverExtend: (opts) -># Extract the server from the options{server} = optsdocpad = @docpad​​# =================================# Environment Configuration​# Locale Code# The code we shall use for our locale (e.g., `en`, `fr`, etc.)# If not set, we will attempt to detect the system's locale, if the locale can't be detected or if our locale file is not found for it, we will revert to `en`localeCode: null # default​# Environment# Which environment we should load up# If not set, we will default the `NODE_ENV` environment variable, if that isn't set, we will default to `development`env: null # default​# Environments# Allows us to set custom configuration for specific environmentsenvironments: # defaultdevelopment: # default# Always refresh from servermaxAge: false # default​# Only do these if we are running standalone via the `docpad` executablecheckVersion: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # defaultwelcome: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # defaultprompts: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # default​# Listen to port 9005 on the development environmentport: 9005 # example}​# Export the DocPad Configurationmodule.exports = docpadConfig
We also support .env
environment configuration file, the format works like so:
.envKEY=VALUEKEY2=VALUE2
All key-value pairs are added to the process.env
environment variable.
This is useful for setting sensitive information, like API keys, database information, and so on.
If you're using .env
using for this purpose, be sure to add .env
to your .gitignore
file!
DocPad will also create a global configuration file located at ~/.docpad.cson
(or ~/Dropbox/.docpad.cson
if you have Dropbox installed). The ~
indicates your home directory (e.g., /Users/balupton
), not your project directory.
This file is typically used to store information relating to your DocPad preferences, such as whether or not you have agreed to the TOS and subscribed to our newsletter or not, however it can also be used to load in configuration that you would like applied to all of your projects. Normally, we wouldn't touch this file, however it is useful to on the odd occasion.
For instance, if we wanted to set the default DocPad port to always be 9779
instead of 9778
, we can update the global configuration file to include:
docpad.coffee{port: 9779}