• Pricing
Skip to content

Routing

On this page:

Loading...

Easy routing configuration to configure redirects, 404 pages, and customize URLs.

Routing file

Configure your CloudCannon’s hosting by configuring a single json file. Create a routing.json file in the .cloudcannon folder at the root of your file structure. When URLs are loaded through the file server, this file is loaded to extend the default behaviour. Add custom headers and configure redirects all in one place.

Producing invalid JSON in this file will break the build and prevent hosting being impacted. Error messages will be available in the build output.

Redirects

When you change your website’s structure, you should redirect the old URLs to the new pages. This ensures external links pointing to the old content and search engines can be redirected. Configure your routing.json to include an array under the routes key with the following keys:

from

Regex (Implemented using re2)

A regular expression or plain string defining the url to match. The urls will always start with a / character. Implicit ^ and $ on each value.

to

String

The new URL to replace the current path including regex parameters.

status

Number

One of 301, 302, 307 or 308. Used to define the HTTP status code to use on the route.

.cloudcannon/routing.json
{
  "routes": [
    {
      "from": "/documentation/(.*)",
      "to": "/docs/$1",
      "status": 308
    },
    {
      "from": "/cloudcannon/(.*)",
      "status": 302,
      "to": "https://cloudcannon.com/$1"
    }
  ]
}

Redirects will only occur if the from url doesn’t resolve to a file. Rules are read in order and the earliest matching rule is used.

Note

You can redirect to, but not from a URL fragment (e.g. #example-heading). The fragment is not passed to the server so, it cannot be processed by the redirect.

Custom Headers

Configure extra headers on any route. Meet security needs or change some behaviour. Configure your routing.json to include an array under the headers key with the following keys:

match

Regex (Implemented using re2)

A regular expression or plain string defining the url to match. The urls will always start with a / character. Implicit ^ and $ on each value.

headers

Array

A list of header names and values to add to the matching request

headers.name

String

The name of the header to configure. Allowed values are

  • ‘strict-transport-security’

  • ‘x-robots-tag’

  • ‘x-content-type-options’

  • ‘x-frame-options’

  • ‘x-xss-protection’

  • ‘access-control-allow-origin’

  • ‘access-control-allow-headers’

  • ‘access-control-allow-methods’

  • ‘content-security-policy’

  • ‘content-security-policy-report-only’

  • ‘expect-ct’

  • ‘sourcemap’

  • ‘large-allocation’

  • ‘content-type’

headers.value

String

The value to return in the header

.cloudcannon/routing.json
{
  "headers": [
    {
      "match": "/about/",
      "headers": [
        {
          "name": "Access-Control-Allow-Origin",
          "value": "example.com"
        }
      ]
    }
  ]
}

Headers are processed at the beginning of all calls. Rules are read in order and combined on all matching rules similar to how CSS works.

404 Page

CloudCannon serves a 404 page when it can’t find a file on your site. Create your own 404 page to blend in with the rest of your site.

To create a custom 404 page:

  1. Create a file called 404.html at the root of your site
  2. Add the content you want CloudCannon to serve
Note

Set the permalink of your page to /404.html if you are using Jekyll and non-default permalinks.

Extensionless URLs

Extensionless URLs do not end with a trailing slash or a file extension. They map to the file in the same path with an html, htm or xml extension. For example, these URLs would serve the same file:

https://example.com/about
https://example.com/about.html

To serve files on extensionless URLs:

  1. Go to Site Settings / Routing
  2. Enable Serve Extensionless URLs and optionally Force Extensionless URLs
  3. Click Update Hosting Details
Note

Serve Extensionless URLs is on by default for new sites for compatibility with the latest Jekyll versions.

Enabling Force Extensionless URLs redirects URLs with html, htm or xml extensions to extensionless versions. This ensures a single URL rather than serving the same file on two different URLs.

On this page:

Loading...

Don’t miss the latest
CloudCannon news freshly delivered to your inbox
Illustration of woman holding an envilope