Mastering routes.yaml in Ghost CMS

Mastering routes.yaml in Ghost CMS

Ghost CMS is a powerful, open-source platform designed for modern publishing. One of the many features it offers is the ability to customize your site’s URL structure using a file called routes.yaml. This guide will walk you through the process of using the routes.yaml file in Ghost CMS.

What is routes.yaml?

The routes.yaml file is a configuration file in Ghost CMS that allows you to customize the URL structure of your site. It maps URL patterns to data and templates within Ghost. By default, Ghost comes pre-configured with a traditional publication structure, but you can customize it extensively to build powerful custom site structures.

How to Use routes.yaml

Step 1: Access routes.yaml

You can access the routes.yaml file from within your Ghost admin panel under Settings → Labs. If you edit the file manually, you’ll need to restart Ghost to see the changes, but if you upload the file in admin then your routes will automatically be updated right away.

Step 2: Understand the Structure of routes.yaml

The routes.yaml file contains three main sections: routes, collections, and taxonomies.

  • routes: This section is used for individual, static pages or channels.
  • collections: This section is used for groups of posts. You can create multiple collections and each collection can have its own URL structure.
  • taxonomies: This section is used for tags and authors.

Here’s an example of what a routes.yaml file might look like:

## routes.yaml

routes:

collections:
   /:
     permalink: /{slug}/
     template: index

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

In this example, the collections section defines the structure for blog posts, with each post’s URL being its slug. The taxonomies section defines the URL structure for tags and authors.

Step 3: Customize Your URL Structure

You can customize your URL structure by editing the routes.yaml file. For example, you can change the URL of your archives from /tag/news/ to /archive/news/.

Step 4: Upload Your routes.yaml File

Once you’ve made your changes, you can upload your routes.yaml file back to Ghost through the admin panel. Your new routes will automatically be updated.

Conclusion

The routes.yaml file in Ghost CMS is a powerful tool that allows you to customize the URL structure of your site. Whether you’re looking to create a unique site structure or simply want to change the URL of your archives, the routes.yaml file gives you the flexibility to do so.