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.jsa Node JavaScript file, will generally look like:module.exports = {/*the configuration*/}docpad.jsona JSON file, does not allow functions, will generally look like:{/*the configuration*/}docpad.coffeea Node CoffeeScript file, will generally look like:module.exports = /*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 3yr ago