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:
- 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.
- Documents inherit
- Static files: Static file routes registered within
amagaki.js
are used. - 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 renderedpod
: The podroute
: 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.