Configure custom routing

Custom routing allows you to control which content is delivered to your visitors when they enter a URL in their internet browser. You can create custom routing by creating a routing.json file in your .cloudcannon folder. When a visitor requests your webpage, CloudCannon will also load the routing.json file to extend the default routing behavior.

Your custom routing file can specify redirects and headers using JSON data.

• Custom redirect — an instruction to redirect a visitor from one URL to another.
• Custom header — additional information passed between the web server and the client (e.g., visitor's browser).

To create a blank custom routing file:

1. Navigate to the .cloudcannon folder using the File browser, or create one in the root of your Site.
2. Click the + Add button at the top right of the browser and select the + Create new file option from the dropdown. CloudCannon will open a blank .txt file in the Source Editor.
3. Click the Save button in the top right of the editing interface. CloudCannon will open the Review changes modal.
4. Edit the file path to "/.cloudcannon/routing.json" and click the Save selected button in the bottom right of the modal.

CloudCannon will save a blank routing.json file in your .cloudcannon folder.

If you would prefer, you can also create a routing.json file using your local development environment.

For a complete list of options available in the routing.json file, please read our routing reference documentation.

Custom Routes#

When CloudCannon loads the routing.json file each time a visitor requests a URL, the first matching routing rule can control what content is delivered to the visitor by redirecting them to a different URL or serving a different content without changing the URL (i.e., a proxy). You can specify the type of custom route using an HTTP status code.

CloudCannon supports the following redirect codes:

• 301 — Indicates the requested URL has been changed permanently.
• 302 — Indicates the requested URL has been changed temporarily, and the visitor's browser should continue to use the original URL in future requests.
• 307 — Indicates the requested URL has been changed temporarily and the visitor's browser should continue to use the original URL in future requests. This is similar to a 302 code however it does not allow the HTTP method to change.
• 308 — Indicates the requested URL has been changed permanently. This is similar to a 301 code however it does not allow the HTTP method to change.

CloudCannon supports the following proxy codes:

• 200 — Indicates the request was successful.
• 404 — Indicates the requested URL could not be found.
• 410 — Indicates the requested URL has been permanently deleted, and search engines should de-index this page.

When configuring custom routing, most users will only need the 307, 308, and 404 status codes.

We recommend redirecting your old page URLs with 307 or 308 redirects whenever you change the URL of a page or the architecture of your Site in a way that affects the URL structure. Redirecting old URLs will:

• Preserve your SEO scores if you want to rank highly in search engine results.
• Maintain external links to your website.
• Prevent visitors from seeing incorrect or missing content when they attempt to load any of your old URLs.

We also recommend configuring a 404 page and routing all unrecognized subpaths to that page.

You must configure three keys for a custom redirect: the from URL, the to URL, and the status code.

• From — Specifies which URL should trigger this redirect rule.
• To — Specifies which URL the visitor should be redirected or proxied to.
• Status — Tells the visitor's browser the reason for the route using an HTTP status code.

To add custom routes to your routing.json file:

1. Navigate to the .cloudcannon folder in your File browser and click on the routing.json file. CloudCannon will open routing.json in the Source Editor.
2.  Create a JSON array under the routes key. Each entry in the array could include the keys from, to, and status.
3. When you are happy with your routing file, save your changes.

After a successful build, CloudCannon will route visitors according to the rules in your routing.json file.

Here are a few examples:

{
  "routes": [
    {
      "from": "/cloudcannon/(.*)",
      "to": "https://cloudcannon.com/$1",
      "status": 302
    },
    {
      "from": "/documentation/articles/choosing-your-ssg/",
      "to": "/documentation/articles/select-your-ssg/",
      "status": 301
    },
    {
      "from": "/app/(.*)",
      "to": "/app/",
      "status": 200
    }
  ]
}

For more a complete list of configuration keys available for custom routing, please read our routing reference documentation.

Generating redirects#

If your Site requires it, you can generate your routing file at build time.

For example, if you only want to redirect URLs on your production Site, you could add the following Liquid templating:

{
  routes: [
    {% if environment == 'production' %}
      {from: '/example-1',
      to: '/example-2'}
    {% endif %}
  ]
}

You can create a build process to generate your routing file with the correct content, depending on the environment. In this case, the build process should generate the file to _cloudcannon/routing.json in your site output directory. CloudCannon will use this file instead of .cloudcannon/routing.json from your source.

For more information, please contact our friendly support team.

Custom Headers#

Custom HTTP headers allow you to pass more information between your web server and the visitor's browser every time someone loads a web page. Custom headers are often used to change some website behavior, meet security requirements, or allow other origins to load resources.

In CloudCannon, you can configure headers using the routing.json file. Whenever a visitor loads a web page from your Site, all relevant header rules from your routing file are applied in order.

To add custom headers to your routing.json file:

1. Navigate to the .cloudcannon folder in your File browser and click on the routing.json file. CloudCannon will open routing.json in the Source Editor.
2. Create a JSON array under the headers key.
3. Within the headers key, add an object labeled match and a second headers array. The value of the match object should be a REGEX string of all URLs to which you want to add a header.
4. Within the second headers array, add an entry for each custom header. Each entry in the array should include the keys name and value.
5. When you are happy with your routing file, save your changes.

After a successful build, CloudCannon will load your custom headers whenever a page loads.

{
  "headers": [
    {
      "match": "*",
      "headers": [
        {
          "name": "Access-Control-Allow-Origin",
          "value": "https://example.com"
        },
        {
          "name": "X-Content-Type-Options",
          "value": "nosniff"
        },
        {
          "name": "X-Robots-Tag",
          "value": "noindex, nofollow"
        }
      ]
    }
  ]
}

For more a complete list of configuration keys available for custom routing, please read our routing reference documentation.