DocPad
Search…
Configuration

Configuration Files

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.

Available Configuration

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
1
# DocPad Configuration
2
docpadConfig = {
3
4
# =================================
5
# Paths Configuration
6
7
# Root Path
8
# The root path of our our project
9
rootPath: process.cwd() # default
10
11
# Package Path
12
# The project's package.json path
13
# If it is a relative path, it will have the resolved `rootPath` prepended to it
14
packagePath: 'package.json' # default
15
16
# Config Paths
17
# An array of paths that we try to extract our docpad configuration from
18
configPaths: [ # default
19
'docpad.js'
20
'docpad.coffee'
21
'docpad.json'
22
'docpad.cson'
23
]
24
25
# Plugin Paths
26
# An array of special paths which to load single plugins from
27
# (e.g., ['/a/path/to/a/docpad-plugin-special'])
28
pluginPaths: [] # default
29
30
# Plugins Paths
31
# An array of paths which to load multiple plugins from
32
pluginsPaths: [ # default
33
'node_modules'
34
'plugins'
35
]
36
37
# Reload Paths
38
# An array of special paths that when changes occur in, we reload our configuration
39
reloadPaths: [] # default
40
41
# Regenerate Paths
42
# An array of special paths that when changes occur in, we regenerate our website
43
regeneratePaths: [] # default
44
45
# Regenerate Delay
46
# The time (in milliseconds) to wait after a source file has
47
# changed before using it to regenerate. Updating over the
48
# network (e.g., via FTP) can cause a page to be partially
49
# rendered as the page is regenerated *before* the source file
50
# has completed updating: in this case increase this value.
51
regenerateDelay: 100 # default
52
53
# Out Path
54
# Where should we put our generated website files?
55
# If it is a relative path, it will have the resolved `rootPath` prepended to it
56
outPath: 'out' # default
57
58
# Src Path
59
# Where can we find our source website files?
60
# If it is a relative path, it will have the resolved `rootPath` prepended to it
61
srcPath: 'src' # default
62
63
# Documents Paths
64
# An array of paths which contents will be treated as documents
65
# If it is a relative path, it will have the resolved `srcPath` prepended to it
66
documentsPaths: [ # default
67
'render'
68
'documents'
69
]
70
71
# Files Paths
72
# An array of paths which contents will be treated as files
73
# If it is a relative path, it will have the resolved `srcPath` prepended to it
74
filesPaths: [ # default
75
'static'
76
'files'
77
'public'
78
]
79
80
# Layouts Paths
81
# An array of paths which contents will be treated as layouts
82
# If it is a relative path, it will have the resolved `srcPath` prepended to it
83
layoutsPaths: [ # default
84
'layouts'
85
]
86
87
# Ignore Paths
88
# Can be set to an array of absolute paths that we should ignore from the scanning process
89
ignorePaths: false # default
90
91
# Ignore Hidden Files
92
# Whether or not we should ignore files that start with a dot from the scanning process
93
ignoreHiddenFiles: false # default
94
95
# Ignore Common Patterns
96
# Whether or not we should ignore commonly undesired files from the scanning process
97
# (e.g., .DStore, thumbs.db, .git, files that start with a tilda, etc.)
98
ignoreCommonPatterns: true # default
99
100
# Ignore Custom Patterns
101
# Can be set to a regex of custom patterns to ignore from the scanning process
102
ignoreCustomPatterns: false # default
103
104
105
# =================================
106
# Server Configuration
107
108
# Port
109
# Use to change the port that DocPad listens to
110
# By default we will detect the appropriate port number for our environment
111
# if no environment port number is detected we will use 9778 as the port number
112
# Checked environment variables are:
113
# - PORT - Heroku, Nodejitsu, Custom
114
# - VCAP_APP_PORT - AppFog
115
# - VMC_APP_PORT - CloudFoundry
116
port: null # default
117
118
# Max Age
119
# The default caching time limit that is sent with the response to the client
120
# Can be set to `false` to disable caching
121
maxAge: 86400000 # default
122
123
# Server Express
124
# The Express.js instance that we want DocPad to use
125
# If not set, we will create our own
126
serverExpress: null # default
127
128
# Server HTTP
129
# The Node.js HTTP server instance that we want DocPad to use
130
# If not set, we will create our own
131
serverHttp: null # default
132
133
134
# =================================
135
# Middleware Configuration
136
# Which middlewares would you like us to activate
137
# Setting `extendServer` to `false` will set all of these to `false` automatically
138
139
# Extend Server
140
# Whether or not we should extend the server with our custom middleware
141
extendServer: true # default
142
143
# The standard middlewares (bodeParser, methodOverride, Express router)
144
middlewareStandard: true # default
145
146
# The standard bodyParser middleware
147
middlewareBodyParser: true # default
148
149
# The standard methodOverride middleware
150
middlewareMethodOverride: true # default
151
152
# The standard Express router middleware
153
middlewareExpressRouter: true # default
154
155
# Our own 404 middleware
156
middleware404: true # default
157
158
# Our own 500 middleware
159
middleware500: true # default
160
161
162
# =================================
163
# Logging Configuration
164
165
# Log Level
166
# Up to which level of logging should we output
167
logLevel: (if ('-d' in process.argv) then 7 else 6) # default
168
169
# Logger
170
# The caterpillar instance that we want to use
171
# If not set, we will create our own
172
logger: null # default
173
174
# Growl
175
# Whether or not we should display system notifications as things progress within DocPad
176
growl: true # default
177
178
# Catch Exceptions
179
# Whether or not DocPad should catch uncaught exceptions
180
catchExceptions: true # default
181
182
# Report Errors
183
# Whether or not we should report errors back to the DocPad Team
184
reportErrors: process.argv.join('').indexOf('test') is -1 # default (don't enable if we are running inside a test)
185
186
# Report Statistics
187
# Whether or not we should report statistics back to the DocPad Team
188
reportStatistics: process.argv.join('').indexOf('test') is -1 # default (don't enable if we are running inside a test)
189
190
# Airbrake Token
191
# The airbrake token we should use for reporting errors
192
# By default, uses the DocPad Team's token
193
airbrakeToken: null # default
194
195
# MixPanel Token
196
# The mixpanel token we should use for reporting statistics
197
# By default, uses the DocPad Team's token
198
mixpanelToken: null # default
199
200
201
# =================================
202
# Other Configuration
203
204
# Detect Encoding
205
# Should we attempt to auto detect the encoding of our files?
206
# Useful when you are using foreign encoding (e.g., GBK) for your files
207
# Only works on unix systems currently (limit of iconv module)
208
detectEncoding: false
209
210
# Render Single Extensions
211
# Whether or not we should render single extensions by default
212
renderSingleExtensions: false # default
213
214
# Render Passes
215
# How many times should we render documents that reference other documents?
216
renderPasses: 1 # default
217
218
# Check Version
219
# Whether or not to check for newer versions of DocPad
220
checkVersion: false # default
221
222
# Welcome
223
# Whether or not we should display any custom welcome callbacks
224
welcome: false # default
225
226
# Prompts
227
# Whether or not we should display any prompts
228
prompts: false # default
229
230
# Helper Url
231
# Used for subscribing to newsletter, account information, and statistics, etc.
232
helperUrl: 'https://docpad.org/helper/' # default
233
234
# Safe Mode
235
# If enabled, we will try our best to sandbox our template rendering so that they cannot modify things outside of them
236
# Not yet implemented
237
safeMode: false # default
238
239
# Collections
240
# A hash of functions that create collections
241
collections: {} # default
242
243
# Regenerate Every
244
# Performs a regenerate every x milliseconds, useful for always having the latest data
245
regenerateEvery: false # default
246
247
248
# =================================
249
# Template Configuration
250
251
# Template Data
252
# Use to define your own template data and helpers that will be accessible to your templates
253
# Complete listing of default values can be found here: http://docpad.org/docs/template-data
254
templateData: # example
255
256
# Specify some site properties
257
site:
258
# The production URL of our website
259
url: "http://website.com"
260
261
# The default title of our website
262
title: "Your Website"
263
264
# The website description (for SEO)
265
description: """
266
When your website appears in search results in say Google, the text here will be shown underneath your website's title.
267
"""
268
269
# The website keywords (for SEO) separated by commas
270
keywords: """
271
place, your, website, keywoards, here, keep, them, related, to, the, content, of, your, website
272
"""
273
274
275
# -----------------------------
276
# Helper Functions
277
278
# Get the prepared site/document title
279
# Often we would like to specify particular formatting to our page's title
280
# we can apply that formatting here
281
getPreparedTitle: ->
282
# if we have a document title, then we should use that and suffix the site's title onto it
283
if @document.title
284
"#{@document.title} | #{@site.title}"
285
# if our document does not have its own title, then we should just use the site's title
286
else
287
@site.title
288
289
# Get the prepared site/document description
290
getPreparedDescription: ->
291
# if we have a document description, then we should use that, otherwise use the site's description
292
@document.description or @site.description
293
294
# Get the prepared site/document keywords
295
getPreparedKeywords: ->
296
# Merge the document keywords with the site keywords
297
@site.keywords.concat(@document.keywords or []).join(', ')
298
299
300
# =================================
301
# Plugin Configuration
302
303
# Skip Unsupported Plugins
304
# Set to `false` to load all plugins whether or not they are compatible with our DocPad version or not
305
skipUnsupportedPlugins: true # default
306
307
# Enable Unlisted Plugins
308
# Set to false to only enable plugins that have been explicity set to `true` inside `enabledPlugins`
309
enableUnlistedPlugins: true # default
310
311
# Enabled Plugins
312
enabledPlugins: # example
313
# Disable the Pokemon Plugin
314
pokemon: false
315
316
# Enable the Digimon Plugin
317
# Unless, enableUnlistedPlugins is set to false, all plugins are enabled by default
318
digimon: true
319
320
# Configure Plugins
321
# Should contain the plugin short names on the left, and the configuration to pass the plugin on the right
322
plugins: # example
323
# Disable NIB within the Stylus Plugin
324
stylus:
325
useNib: false
326
327
328
# =================================
329
# Event Configuration
330
331
# Events
332
# Allows us to bind listeners to the events that DocPad emits
333
# Complete event listing can be found here: http://docpad.org/docs/events
334
events: # example
335
336
# Server Extend
337
# Used to add our own custom routes to the server before the docpad routes are added
338
serverExtend: (opts) ->
339
# Extract the server from the options
340
{server} = opts
341
docpad = @docpad
342
343
344
# =================================
345
# Environment Configuration
346
347
# Locale Code
348
# The code we shall use for our locale (e.g., `en`, `fr`, etc.)
349
# 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`
350
localeCode: null # default
351
352
# Environment
353
# Which environment we should load up
354
# If not set, we will default the `NODE_ENV` environment variable, if that isn't set, we will default to `development`
355
env: null # default
356
357
# Environments
358
# Allows us to set custom configuration for specific environments
359
environments: # default
360
development: # default
361
# Always refresh from server
362
maxAge: false # default
363
364
# Only do these if we are running standalone via the `docpad` executable
365
checkVersion: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # default
366
welcome: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # default
367
prompts: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # default
368
369
# Listen to port 9005 on the development environment
370
port: 9005 # example
371
}
372
373
# Export the DocPad Configuration
374
module.exports = docpadConfig
Copied!

Environment Configuration File

We also support .env environment configuration file, the format works like so:
.env
1
KEY=VALUE
2
KEY2=VALUE2
Copied!
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!

Global Configuration 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
1
{
2
port: 9779
3
}
Copied!
Last modified 2yr ago