Upload routes.yaml

Wire the /courses/, /training/, and /docs/ URL structures by uploading routes.yaml in Ghost Admin.

1 min read Swarnil Singhai Updated 3 Feb 2026

Upload routes.yaml

Ghost's URL structure — which template renders which path, and how collections and permalinks are shaped — is defined in a file called routes.yaml. This theme relies on specific routes to make courses, training, and docs nest correctly, and the file lives in Ghost Admin, not in the theme repository, so you upload it separately.

Navigate to Settings → Labs (or Settings → Advanced, depending on Ghost version) and use Routes to download the current file and upload a replacement. A routes file has three sections: routes (map a path to a template), collections (group posts under a base path with a permalink pattern and a filter), and taxonomies (tag and author archive patterns).

collections:
  /courses/:
    permalink: /courses/{primary_tag}/{slug}/
    template: courses
    filter: 'tag:hash-course,tag:hash-lesson'
  /training/:
    permalink: /training/{primary_tag}/{slug}/
    template: training
    filter: 'tag:hash-training,tag:hash-training-content'
  /docs/:
    permalink: /docs/{primary_tag}/{slug}/
    template: documentation
    filter: 'tag:documentation'

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

The key idea is the {primary_tag} permalink token: because a lesson's primary tag is its course or track tag, this pattern produces the nested URLs /courses/{course}/{lesson}/ and /training/{track}/{lesson}/ that the theme and this documentation assume throughout. The filter on each collection selects which posts belong to it using the internal tags — courses and lessons into /courses/, training posts into /training/, and documentation into /docs/.

After editing, upload the file. Ghost rebuilds its URL map and may take a moment; then verify a few URLs resolve to the right templates. A malformed routes file can 500 the site, so keep a known-good backup before uploading, and change one collection at a time when experimenting.

With routing in place, the site's sections resolve correctly. The next docs cover the navigation menus and navbar behaviour that sit on top of this routing.