The DocPad Configuration page now has a complete listing of available…

… DocPad Configuration

core/config.html.md

@@ -18,25 +18,249 @@ The advantage of `docpad.coffee` and `docpad.cson` over `docpad.js` and `docpad.
 Generally, you'll usually always find either a `docpad.coffee` file or a `docpad.cson` file.
 
 
-### Example `docpad.coffee` 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.
 
 ``` coffee
-# The DocPad Configuration File
-# It is simply a CoffeeScript Object which is parsed by CSON
+# DocPad Configuration
 docpadConfig = {
 
 	# =================================
-	# DocPad Configuration
+	# Paths Configuration
+
+	# Root Path
+	# The root path of our our project
+	rootPath: process.cwd()  # default
 
-	# Change the port DocPad uses from the default 9778 to 8080
-	port: 8080
+	# Package Path
+	# The project's package.json path
+	# If it is a relative path, it will have the resolved `rootPath` prepended to it
+	packagePath: 'package.json'  # default
+
+	# Config Paths
+	# An array of paths that we try to extract our docpad configuration from
+	configPaths: [  # 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 from
+	pluginsPaths: [  # default
+		'node_modules'
+		'plugins'
+	]
+
+	# Reload Paths
+	# An array of special paths that when changes occur in, we reload our configuration
+	reloadPaths: []  # default
+
+	# Regenerate Paths
+	# An array of special paths that when changes occur in, we regenerate our website
+	regeneratePaths: []  # 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 it
+	outPath: '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 it
+	srcPath: '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 it
+	documentsPaths: [  # default
+		'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 it
+	filesPaths: [  # default
+		'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 it
+	layoutsPaths: [  # default
+		'layouts'
+	]
+
+	# Ignore Paths
+	# Can be set to an array of absolute paths that we should ignore from the scanning process
+	ignorePaths: false  # default
+
+	# Ignore Hidden Files
+	# Whether or not we should ignore files that start with a dot from the scanning process
+	ignoreHiddenFiles: 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 process
+	ignoreCustomPatterns: 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 - CloudFoundry
+	port: 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 caching
+	maxAge: 86400000   # default
+
+	# Server Express
+	# The express.js instance that we want DocPad to use
+	# If not set, we will create our own
+	serverExpress: null  # default
+
+	# Server HTTP
+	# The node.js HTTP server instance that we want DocPad to use
+	# If not set, we will create our own
+	serverHttp: null  # default
+
+
 	# =================================
-	# Template Data
-	# These are variables that will be accessible via our templates
+	# 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 middleware
+	extendServer: true  # default
+
+	# The standard middlewares (bodeParser, methodOverride, express router)
+	middlewareStandard: true  # default
+
+	# The standard bodyParser middleware
+	middlewareBodyParser: true  # default
+
+	# The standard methodOverride middleware
+	middlewareMethodOverride: true  # default
+
+	# The standard express router middleware
+	middlewareExpressRouter: true  # default
+
+	# Our own 404 middleware
+	middleware404: true  # default
+
+	# Our own 500 middleware
+	middleware500: true  # default
+
+
+	# =================================
+	# Logging Configuration
+
+	# Log Level
+	# Up to which level of logging should we output
+	logLevel: (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 own
+	logger: null  # default
+
+	# Growl
+	# Whether or not we should display system notifications as things progress within DocPad
+	growl: true  # default
+
+	# Catch Exceptions
+	# Whether or not DocPad should catch uncaught exceptions
+	catchExceptions: true  # default
+
+	# Report Errors
+	# Whether or not we should report errors back to the DocPad Team
+	reportErrors: 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 Team
+	reportStatistics: 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 token
+	airbrakeToken: null  # default
 
-	templateData:
+	# MixPanel Token
+	# The mixpanel token we should use for reporting statistics
+	# By default, uses the DocPad Team's token
+	mixpanelToken: null  # default
+
+
+	# =================================
+	# Other Configuration
+
+	# Render Single Extensions
+	# Whether or not we should render single extensions by default
+	renderSingleExtensions: 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 DocPad
+	checkVersion: false  # default
+
+	# Welcome
+	# Whether or not we should display any custom welcome callbacks
+	welcome: false  # default
+
+	# Prompts
+	# Whether or not we should display any prompts
+	prompts: 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 implemented
+	safeMode: false  # default
+
+	# Collections
+	# A hash of functions that create collections
+	collections: {}  # default
+
+	# Regenerate Every
+	# Performs a regenerate every x milliseconds, useful for always having the latest data
+	regenerateEvery: 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-data
+	templateData:  # example
 
 		# Specify some site properties
 		site:
@@ -83,14 +307,18 @@ docpadConfig = {
 
 
 	# =================================
-	# Plugins
+	# Plugin Configuration
+
+	# Skip Unsupported Plugins
+	# Set to `false` to load all plugins whether or not they are compatible with our DocPad version or not
+	skipUnsupportedPlugins: true  # default
 
 	# Enable Unlisted Plugins
-	# If set to false (defaults to true), we will only enable plugins that have been explicitly set to true inside enabledPlugins
-	enabledUnlistedPlugins: true
+	# Set to false to only enable plugins that have been explicity set to `true` inside `enabledPlugins`
+	enabledUnlistedPlugins: true  # default
 
 	# Enabled Plugins
-	enabledPlugins:
+	enabledPlugins:  # example
 		# Disable the Pokemon Plugin
 		pokemon: false
 
@@ -100,19 +328,19 @@ docpadConfig = {
 
 	# Configure Plugins
 	# Should contain the plugin short names on the left, and the configuration to pass the plugin on the right
-	plugins:
-
+	plugins:  # example
 		# Disable NIB within the Stylus Plugin
 		stylus:
 			useNib: false
 
 
 	# =================================
-	# DocPad Events
+	# Event Configuration
 
-	# Here we can define handlers for events that DocPad fires
-	# You can find a full listing of events on the DocPad Wiki
-	events:
+	# Events
+	# Allows us to bind listeners to the events that DocPad emits
+	# Complete event listing can be found here: http://docpad.org/docs/events
+	events:  # example
 
 		# Server Extend
 		# Used to add our own custom routes to the server before the docpad routes are added
@@ -121,17 +349,37 @@ docpadConfig = {
 			{server} = opts
 			docpad = @docpad
 
+
 	# =================================
-	# Environments
+	# Environment Configuration
 
-	environments:
-
-		development:
+	# 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
 
-			# anything here will be merged with the top-level (production) configuration if we are running inside the development environment
+	# Environments
+	# Allows us to set custom configuration for specific environments
+	environments:  # default
+		development:  # default
+			# Always refresh from server
+			maxAge: false  # default
+
+			# Only do these if we are running standalone via the `docpad` executable
+			checkVersion: process.argv.length >= 2 and /docpad$/.test(process.argv[1])  # default
+			welcome: process.argv.length >= 2 and /docpad$/.test(process.argv[1])  # default
+			prompts: process.argv.length >= 2 and /docpad$/.test(process.argv[1])  # default
+
+			# Listen to port 9005 on the development environment
+			port: 9005  # example
 }
 
-# Export our DocPad Configuration
+# Export the DocPad Configuration
 module.exports = docpadConfig
 ```