Routes

Routes define how your content is exposed to your visitors. This affects the structure of your baked output, which affects the URLs of your pages.

Routes are defined as a list of entries under site/routes:

site:
    routes:
        - url: /foo/%slug%
          source: something
        - url: /bar/%year%/%month%/%slug%
          source: otherthing

Each route must define the following settings:

• url: That’s the pattern to use to figure out where the baked page will go. You obviously need to use placeholders here (things of the form %blah%) otherwise all your pages would be overwriting each other — although PieCrust would warn you about that. The available placeholders depend on the source tied to this route. See the list of available sources to see what kind of routing information they expose.

• source: This defines the source that this route is defined for. Only pages coming from that source will have their bake output generated from this route.

Optional settings include:

• taxonomy: If this route is meant to match a taxonomy index page, you have to define which taxonomy that is.

• page_suffix: Pages that create sub-pages (e.g. when using pagination) will append this suffix to the route. By default, this is /%num%. You must use the %num% placeholder somewhere in this setting.

Route ordering

The order of the routes is important, because the first matching route for a given page will be the one that’s used. This is especially important when running chef serve, or running PieCrust as a dynamic CMS.

This is because the incoming URL requested by a visitor’s browser will be matched against each route starting from the first one in the list. For each route that matches, an actual page will be looked for, and the first one to be found will be returned for that URL.