Routes

Routing behavior determines how Amagaki generates URLs for content, and what the
lifecycle of a request to a page on the development server looks like.

Route providers

Amagaki has three basic route providers, all which generate routes. In a
nutshell, here's how routing works:

1. Documents: All collections and documents are searched to find $path settings (for both
   the root document and localized variations).
   • Documents inherit $path settings from their collection's
     _collection.yaml.
   • If a document has $path: null or a collection does not have a
     _collection.yaml, the document will not generate a route.
2. Static files: Static file routes registered within amagaki.js are used.
3. Plugins: Any plugins registered within amagaki.js that configure custom route
   providers can add additional routes beyond document routes and static file
   routes.

Pods collect the routes from the steps outlined above to determine a full
routing tree outlining all routes that the pod generates.

Inspecting routes

Use npx amagaki build to build your site, and inspect the generated files
within the build directory to see which routes are created.

Referring to URLs

Because Amagaki routing is declarative (within content) and progammatic (within
plugins that provide route providers), you should never hardcode URLs anywhere
within either content files or templates. Always use an appropriate pod function
to retrieve the URL for something.

The Url object is used for all URLs for documents, static files, and custom
route providers within Amagaki. While it's usually appropriate to refer to a URL
using its path property only, you may also want an object's absolute URL
including its domain name. Build environments can specify the hostname that your
site is deployed to, allowing you to centrally configure hostnames.

home: !pod.doc /content/pages/index.yaml

{{doc.home.url.path}}

Route provider deep-dive

Collection routes

A collection's _collection.yaml file specifies the default URL path for all
documents within a collection. Here's what a typical _collection.yaml may look
like:

$path: /pages/${doc.basename}/

All documents within this collection will be generated to paths generated from
the above path formatter. Path formatters are interpolated, with the following
context variables:

• doc: The document being rendered
• pod: The pod
• route: The route being rendered

For example, a collection with the following structure...

.
└── content
    ├── pages
        ├── _collection.yaml
        ├── about.yaml
        ├── contact.yaml
        └── index.yaml

... will generate the following routes and URL paths:

• /pages/about/
• /pages/contact/
• /pages/

Note that paths that terminate in /index/ are automatically cleaned.

Document routes

Documents can override a collection's $path by specifying their own.

$path: /pages/get-in-touch/

In the above example, the page will be generated to /pages/get-in-touch/
instead of inheriting its path from _collection.yaml.

Documents can disable routing (and therefore won't be built) by setting their
path to null:

$path: null

Remember, path formatters are interpolated, so you can even refer to a
document's content:

$path: /posts/${doc.fields.date}/${doc.fields.slug}/
date: 2019-01-06
slug: hello-world

In the above example, the page will be generated to
/posts/2019-01-06/hello-world/.

Static routes

Amagaki collects files from directories and copies them to the build folder.

module.exports = function (pod) {
  pod.configure({
    staticRoutes: [
      {
        path: '/static/',
        staticDir: '/dist/',
      },
      {
        path: '/static/images/',
        staticDir: '/src/static/images/',
      },
    ],
  });
};

It's a best practice to refer to static files using their pod paths, in case you
want to change the serving path in the future. See the following example for a
common usage pattern.

<link rel="stylesheet" href="{{pod.staticFile('/dist/css/main.css').url.path}}">
<script src="{{pod.staticFile('/dist/js/main.js').url.path}}"></script>
<img src="{{pod.staticFile('/src/static/images/cat.jpg').url.path}}">

Pod functions also enable usage recording, so it's possible to determine where
assets are used, and how frequently.