Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    docpad-plugin-cleanurls

    2.12.1¬†‚Äʬ†Public¬†‚Äʬ†Published

    Clean URLs Plugin for DocPad

    Travis CI Build Status NPM version NPM downloads Dependency Status Dev Dependency Status
    GitHub Sponsors donate button Patreon donate button Flattr donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button Wishlist browse button

    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:

    plugins:
        cleanurls:
            static: true

    If you would like to disable the static mode for the static environment, you can do so with:

    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:

    environments:
        static:
            plugins:
                cleanurls:
                    enabled: false

    trailingSlashes

    Enable this plugin configuration option to generate document.urls 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:

    # 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:

    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:

    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:

    <!DOCTYPE html>
    <html>
        <head>
            <!-- Standard Meta -->
            <meta charset="utf-8" />
            <meta http-equiv="X-UA-Compatible" content="IE=edge" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
     
            <!-- Site Properties -->
            <title>404 Page Not Found</title>
     
            <!-- DocPad Meta -->
            <%- @getBlock('meta').toHTML() %>
     
            <!-- DocPad Styles -->
            <%- @getBlock('styles').add('/vendor/404.css').toHTML() %>
        </head>
        <body>
            <!-- 404 Page Content -->
            <div class="container">
    ¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†<h1>Not¬†Found¬†ūüė≤</h1>
                <p>Sorry, but the page you were trying to view does not exist.</p>
                <p>It looks like this was the result of either:</p>
                <ul>
                    <li>a mistyped address</li>
                    <li>an out-of-date link</li>
                </ul>
                <script>
                    var GOOG_FIXURL_LANG = (navigator.language || '').slice(0, 2),
                        GOOG_FIXURL_SITE = location.host
                </script> 
                <script src="http://linkhelp.clients.google.com/tbproxy/lh/wm/fixurl.js"></script> 
            </div>
     
            <!-- DocPad Scripts -->
            <%- @getBlock('scripts').toHTML() %>
        </body>
    </html>

    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?

    GitHub Sponsors donate button Patreon donate button Flattr donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button Wishlist browse button

    Contributors

    These amazing people have contributed code to this project:

    Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

    License

    Unless stated otherwise all works are:

    and licensed under:

    Install

    npm i docpad-plugin-cleanurls

    DownloadsWeekly Downloads

    29

    Version

    2.12.1

    License

    MIT

    Unpacked Size

    56 kB

    Total Files

    11

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar