Upgrade
Last updated
Was this helpful?
Last updated
Was this helpful?
To upgrade your DocPad installation from an older version to the latest, check out the as well as the upgrade manuals below.
Changes affecting configuration:
Removed the following configuration options: documentsPath
, filesPath
, and layoutsPath
. Use their array-based alternatives instead: documentsPaths
, filesPaths
, and layoutsPaths
.
Changes affecting templates:
Removed require
from templateData
. Instead, specify it in your docpad.cson
or server.coffee
file instead
Removed database
, documents
, collections
, blocks
from templatedata
. Instead, use their helper based alternatives: getDatabase()
, getCollection('documents')
, getCollection('collectionName')
, getBlock('blockName')
Changes affecting everyone:
Removed the prototypes String::startsWith
, String::finishesWith
, Array::hasCount
, Array::has
as no one ever used them
Plugin versions have been bumped to 2.x
for DocPad v6.x compatibility. You should update all your DocPad plugins versions in your package.json
to 2.0.x
(e.g., "docpad-plugin-eco": "2.0.x"
) then run npm install
to install the new versions of the plugins
Changes affecting plugin developers:
Removed docpadInstance.documents
. Use docpadInstance.getCollection('documents')
instead.
Plugin tests are now run via npm test
on your plugin directory, allowing you to use whatever test runner you want
DocPad and the tester helpers have moved from Mocha to , you'll probably want to do the same
For end-users this will have minimal effect, as @document
inside the templateData
will have all the same attributes. However, any function calls will now only be accessible via the new @documentModel
. This is because @documentModel
is the backbone model, and @document
is the JSONified version of the backbone model (e.g., @document
is the same as @documentModel.toJSON()
).
For end-users this will have an effect wherever @database
is used, as that is now represented by the new Query-Engine v1.1 collection, which has several changes. The most significant re @database.find
is now @database.findAll
, and that they now only have a synchronous interfacee. E.g. the @database.findAll
selector (err, results) ->
should now be results = @database.findAll(selector)
For plugin developers, this affects any docpad.documents
, docpad.partials
, and docpad.layouts
calls with the same advice as those for end-users.
For plugin developers, there have been several important changes:
All plugins must now have docpad-plugin
inside the keywords
property of their package.json
file. It is also highly recommended to ensure your plugin's name follows the docpad-plugin-#{pluginName}
convention as this may become mandatory at a later date.
Skeletons are no longer cached, which means that you can no longer create a new website using a skeleton while offline. While this can be a pain, it was an essential change in order to improve stability and reduce complexity of the code base.
A document's title
will no longer default to the document's filename
if not set. Instead a new property called name
exists, which can be set by your document meta data. This is so the title
property can be used for Page Titles (e.g., <title>
) whereas the name
property can be used for navigation listings etc.
For those using DocPad as a module, DocPad now supports a next
callback on its constructor, allowing you to do new DocPad(config,next)
. Anything that depends on a DocPad action being completed should go inside the next
callback. While this is optional, it has proven helpful in eliminating timing problems.
CoffeeScript v1.1.2 does not work with Node 0.5 or 0.6, you have to use v1.1.3 or higher. To do this, re-install CoffeeScript with npm install -g coffee-script
For plugin developers:
Plugins have been revised to become more future proof and configurable. Plugins must be in their own directory, with the following format: plugins/${pluginName}/${pluginName}.plugin.coffee
Plugin dependencies should no longer be in the DocPad's or your project's package.json
file, but instead in their plugin directory's package.json
(e.g., plugins/${pluginName}/package.json
); this file is optional, but recommended.
If a plugin's package.json
exists, as well as its main
property, DocPad will use that as the plugin file's location instead of the location in step 2.1.
Plugin configuration should be moved to their package.json
file, to the key docpad.plugin
which should be an object. This is then customisable by DocPad's package.json
as well as the website's via docpad.plugin.#{pluginName}
. The configuration of a plugin is available via the @config
property.
To access DocPad within a plugin, you should now use @docpad
rather than having it passed through as an argument, this applies for logger too (now use @logger
).
A lot of DocPad configuration has been moved to @docpad.config
Install DocPad with the new global dependencies npm install -g coffee-script docpad
Any of your documents
or layouts
which use the eco templating engine should have the extension .eco
appended (e.g., layouts/default.html
to layouts/default.html.eco
)
Any of your documents
or layouts
which utilise a markup language should have the extension .html
prepended (e.g., documents/something-in-markdown.md
to documents/something-in-markdown.html.md
)
These changes allow for some new incredibly powerful possibilities, such as allowing other templating engines other than eco, and allowing for multiple and more explicit markups to be applied to the files.
Documents, Partials and Layouts (which extend from the File Class) are now
For plugin developers this affects how you will retrieve and set attributes for documents - which now use the instead of directly reading and writing to and from the attributes directly (e.g., document.relatedDocuments = []
now becomes document.set(relatedDocuments:[])
instead)
has been updated from version 0.6 to version 1.1
Plugins are now handled via instead of being directly handled by DocPad and end-users. This is the most significant change and affects everybody.
For end-users, you will need to add the plugins you use to your website's package.json
file. You can refer the for how to do this. Once added to your website's package.json
file, run a npm install
to install them.
You can now feel free to publish your plugin via npm (e.g., npm publish
) and add your plugin to the so others can install it themselves (e.g., npm install docpad-plugin-#{pluginName}
).
The DocPad core has been cleaned up a lot, and as such so has the way plugin events are triggered. We now utilise and instead of the old triggerPluginEvent
. This means that for now, plugin priorities are discarded - however they may be added back in the future (so leave them in there if you have them).
Plugin rendering has had a significant change, which is you should no longer use file.content
to read and update the current document's content. Instead a new argument called content
wil be passed, and it should be written to as well. This is a breaking change, and all renderers must be updated to facilitate this change. To learn the new way, then check out the wiki page.
When an error occurs, the error will now be sent back to DocPad using the service. If you would like this disabled then you can turn it off by setting reportErrors
to false
in your DocPad configuration.
A lot of unstable or less-popular plugins have been moved out to the new repository. The plugins moved are: admin
, authenticate
, autoupdate
, buildr
, html2jade
, move
, php
, rest
, roy
, and ruby
. If you would like to continue using them, you will have to download them manually from the docpad-extras
repository and insert them into your website's plugins
directory.
A lot of property names of the File
class have changed. The File
class is used for all documents and layouts, which would likely affect you when rendering properties from documents inside your templates e.g. @document.title
. This change was made to better correlate the names with their values (before the correlation was quite ambiguous).
For plugin developers, the way you extend from the BasePlugin
, and the way you module.exports
your plugin has changed.
DocPad v2 also brings a bunch of new cool features, check out the changelog on the for more info, and the for information on how to use some of these new features :-)
The Bootstrap Skeleton is now the