Routes and URLs

Grow provides a flexible way to configure the URL serving paths for your site's routes. By leveraging the URL path configuration features, you can easily create clean, maintainable, and flexible URLs for all routes in your site.

Philosophy

Serving paths and filesystem paths do not need to match one-to-one. This is an explicit capability that exists to remove the need to name internal files a specific way. Because internal file paths do not need to match serving paths, you can change the URL of content at any time without renaming files or performing find and replace operations throughout your site.

Configuring URLs

There are three places URLs are specified. Your site's routing map is generated by analyzing and combining the rules set in all three locations.

1. podspec.yaml
2. blueprints
3. content documents

Content document path formatters

Use these formatters to configure serving paths for documents either in a content document or its blueprint.

Setting path in both a collection's blueprint and in a content document is optional. You should only define a path in a content document if you need to override a content document's path from the one specified in its blueprint.

Remember: don't repeat yourself. If you can specify a path format in a collection's blueprint that generates the right path for all of its documents, then there is no need to also specify $path for each document. Only specify $path in a document for paths you need to override.

Examples

# In a collection's _blueprint.yaml
$path: /pages/{slug}/
$path: /pages/{base}/
$path: /{root}/pages/{base}/
$localization:
  path: /{locale}/pages/{slug}/

# In document.yaml (only specify document-level paths if you need to override the format set in the blueprint)
$path: /pages/home/
$localization:
  path: /{locale}/pages/home/

Static file path formatters

Use these formatters to configure serving paths for static files in podspec.yaml.

Examples

# In podspec.yaml
static_dirs:
- static_dir: /source/images/
  serve_at: /static/images/
  localization:
    static_dir: /source/{locale}/images/
    serve_at: /{locale}/static/images/

Specifying a site root

You can specify the site root in podspec.yaml and then reference the root in path formats elsewhere. This provides flexibility should you need to change the site root later, and allows you to avoid repeating the site root throughout multiple configurations.

# In podspec.yaml
root: /my-site/

# In a collection's _blueprint.yaml
path: /{root}/pages/{base}/

Specifying the homepage

Most sites have homepages. You can specify your site's homepage in podspec.yaml, which improves automation by providing you with a clickable link to your homepage when the development server starts up. Notifications may also contain links to your homepage, so it's always a good idea to set this.

Note that the value of the homepage should point to a content document, not a URL path. Your homepage's URL will be derived from the content document's URL.

# In podspec.yaml
home: /content/pages/home.yaml

URLs in templates

Because you are provided with the freedom to change a serving path at any time, whenever you need to reference a URL in a template (such as in a <link> element for a stylesheet or <a href> for a link), you should always programmatically generate those URLs using a built-in template function.

In general, you should never refer to a linkable resource by its URL: you should refer to it by its internal pod path and leverage either g.doc or g.static to programmatically generate its URL. This technique provides you with flexibility to change URLs later without finding and replacing URLs in your site's code. Plus, it helps avoid broken links.

URL object

Documents and static files both have url properties that return their corresponding Url object.

# The serving path for a content document.
{{g.doc('/content/pages/home.yaml').url.path}}

# The serving path for a static file.
{{g.static('/source/images/image.png').url.path}}

{{doc.url}}            # The full URL to the document (based on the environment).
{{doc.url.path}}       # The serving path to the document.
{{doc.url.host}}
{{doc.url.scheme}}
{{doc.url.port}}

Relative URLs

All URLs generated from a Url object are absolute. However, if you'd like to generate relative URLs, you can use the relative template filter. The final URL generated is relative to the current document context.

{{g.doc('/content/pages/home.yaml').url|relative}}

Checking routes

Use the grow inspect routes command to quickly audit all of the routes that your site generates. You can use this command to avoid building the site and inspecting the generated fileset or saving and refreshing to check paths in the browser.

Grow validates your URL path configuration and raises errors upon misconfiguration. For example, Grow will raise an error if you generate the same serving path for two different resources – no two resources may share the same serving path.

Sitemap

Grow can autogenerate a sitemap.xml file for your site, upon build. You can enable sitemap generation in podspec.yaml and, optionally, customize which pages and locales are included in the sitemap.

# podspec.yaml

sitemap:
  enabled: yes
  path: "/{root}/sitemap.xml"   # Optional.
  collections:                  # Optional.
  - pages
  locales:                      # Optional.
  - en
  - fr