Clean URLs Plugin for DocPad
Adds support for clean URLs to DocPad
In non-static environments we work by setting the document's url to it's clean url. This means that redirection occurs on the dynamic server level.
static environment (i.e. when running DocPad with the
--env static flag, e.g. running
docpad generate --env static) we will set the
static plugin configuration option to
true. This will in addition to performing redirections via the built-in dynamic server within DocPad for speed, we will also write special static redirection HTML files to the output directory, that will redirect the user to the new clean location (e.g. the document
pages/welcome.html will now be outputted to
pages/welcome.html now being a special HTML redirect document to the clean location).
If you would like to always use the static mode, you can set the
static plugin configuration option to true with:
If you would like to disable the static mode for the static environment, you can do so with:
If you would like to disable clean urls completely (not just the static mode) in the static environment, you can do so with:
Enable this plugin configuration option to generate
'/beep/' instead of
/beep. Defaults to
You can use this plugin configuration option (defaults to
html) to tell the cleanurls plugin to use your own custom collection for which documents to apply clean URLs to.
For instance, if you are wanting to remove all clean URLs for all documents that have
cleanurls: false in the meta data, then you could do the following in your DocPad configuration file:
# Define a custom collection for cleanurls that ignores the documents we don't wantcollections:: ->@getCollection'html'findAllLivecleanurls: $ne: false# Tell our clean urls plugin to use this collectionplugins:cleanurls:collectionName: 'cleanurls'
You can customise the HTML template that is used for the redirect pages by specifying the
getRedirectTemplate option which is a function that accepts
url argument and an option
title argument and returns a string.
Simple redirects work via routes in dynamic environments, and on static environments work via generating redirect HTML pages at the location of the source relative URL. They can be defined like so:
plugins:cleanurls:simpleRedirects:'/relative-url': '/somewhere-else''/other-relative-url': ''
plugins:cleanurls:advancedRedirects:# Regular expressions redirects are possible too/^\/github\/?$/'$1'/^\/plugin\/$/'-$1'# Absolute URL redirects are even possible''''''''
To ensure they work, you must make sure that your 404 Page document calls
<!-- Standard Meta --><!-- Site Properties -->404 Page Not Found<!-- DocPad Meta --><%- @getBlock('meta').toHTML() %><!-- DocPad Styles --><%- @getBlock('styles').add('/vendor/404.css').toHTML() %><!-- 404 Page Content -->Not Found 😲Sorry, but the page you were trying to view does not exist.It looks like this was the result of either:a mistyped addressan out-of-date link<!-- DocPad Scripts --><%- @getBlock('scripts').toHTML() %>
Install this DocPad plugin by entering
docpad install cleanurls into your terminal.
These amazing people are maintaining this project:
No sponsors yet! Will you be the first?
These amazing people have contributed code to this project:
- Adam Hull — view contributions
- Benjamin Lupton — view contributions
- Daniel Smith — view contributions
- David Boyer — view contributions
- Laurence Elsdon — view contributions
- Marcus Stong
- Marcus Stong — view contributions
- Rob Loach — view contributions
- Zeno Rocha
- Zeno Rocha — view contributions
- iSpyCreativity — view contributions
- vsopvsop — view contributions
Unless stated otherwise all works are:
and licensed under: