Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/docpad/docpad-plugin-cleanurls
Adds support for clean urls to DocPad
https://github.com/docpad/docpad-plugin-cleanurls
docpad-plugin
Last synced: 3 months ago
JSON representation
Adds support for clean urls to DocPad
- Host: GitHub
- URL: https://github.com/docpad/docpad-plugin-cleanurls
- Owner: docpad
- License: other
- Created: 2012-10-17T11:45:26.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2024-01-08T12:50:53.000Z (about 1 year ago)
- Last Synced: 2024-09-19T10:19:04.253Z (4 months ago)
- Topics: docpad-plugin
- Language: JavaScript
- Homepage:
- Size: 478 KB
- Stars: 21
- Watchers: 14
- Forks: 13
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
Clean URLs Plugin for DocPad
Adds support for clean URLs to DocPad
## Usage
### `static`
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.
For the `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/index.html`, with `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:
```coffee
plugins:
cleanurls:
static: true
```
If you would like to disable the static mode for the static environment, you can do so with:
```coffee
environments:
static:
plugins:
cleanurls:
static: false
```
If you would like to disable clean urls completely (not just the static mode) in the static environment, you can do so with:
```coffee
environments:
static:
plugins:
cleanurls:
enabled: false
```
### `trailingSlashes`
Enable this plugin configuration option to generate `document.url`s like `'/beep/'` instead of `/beep`. Defaults to `false`.
### `collectionName`
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:
```coffee
# Define a custom collection for cleanurls that ignores the documents we don't want
collections:
cleanurls: ->
@getCollection('html').findAllLive(cleanurls: $ne: false)
# Tell our clean urls plugin to use this collection
plugins:
cleanurls:
collectionName: 'cleanurls'
```
### `getRedirectTemplate`
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.
### `simpleRedirects`
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:
```coffee
plugins:
cleanurls:
simpleRedirects:
'/relative-url': '/somewhere-else'
'/other-relative-url': 'http://somehere.else'
```
### `advancedRedirects`
Advanced redirects work via routes in dynamic environments, and on static environments work via a client-side javascript injection into the Script Block on your 404 Page document. They can be defined like so:
```coffee
plugins:
cleanurls:
advancedRedirects: [
# Regular expressions redirects are possible too
[/^\/github\/?(.*)$/, 'https://github.com/docpad/$1']
[/^\/plugin\/(.+)$/, 'https://github.com/docpad/docpad-plugin-$1']
# Absolute URL redirects are even possible
['http://production.com/favourite-website', 'http://wikipedia.org']
['http://localhost:9778/favourite-website', 'http://facebook.com']
]
```
To ensure they work, you must make sure that your 404 Page document calls `@getBlock('scripts').toHTML()` to output the Script Block, which we inject the client-side javascript into. Here is an example of such a document using eco and location at `src/documents/404.html.eco`:
```html
404 Page Not Found
<%- @getBlock('meta').toHTML() %>
<%- @getBlock('styles').add('/vendor/404.css').toHTML() %>
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 address
- an out-of-date link
var GOOG_FIXURL_LANG = (navigator.language || '').slice(0, 2),
GOOG_FIXURL_SITE = location.host
<%- @getBlock('scripts').toHTML() %>
```
You can modify the client-side javascript by providing the option getRedirectScript` which is a function that accepts the advancedRedirects value as the first and only argument and returns a string which is the script to be injected.
Install
Install this DocPad plugin by entering docpad install cleanurls into your terminal.
History
Discover the release history by heading on over to the HISTORY.md file.
Contribute
Discover how you can contribute by heading on over to the CONTRIBUTING.md file.
Backers
Maintainers
These amazing people are maintaining this project:
Sponsors
No sponsors yet! Will you be the first?
Contributors
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
Discover how you can contribute by heading on over to the CONTRIBUTING.md file.
License
Unless stated otherwise all works are:
- Copyright © 2012+ Bevry Pty Ltd
- Copyright © 2011 Benjamin Lupton
and licensed under: