Routes.yaml format


It would be very helpful to have the exact format required of the routes.yaml file.
Not sure why the routes.yaml file is not more free form for the spacing.
In addition, it would be more helpful for examples to be shown. For example, there are many references to using the Admin tool to load a routes.yaml file, but no mention of where in the Admin tool this is accomplished.


Hey :wave:

Here are the docs I’m referencing throughout my reply:

What exactly do you want to know about the format? I think everything you’re looking for is outlined in the docs :thinking:

The yaml parser should follow whatever spacing you use, but you need to be consistent n your spacing.

I couldn’t find a reference to that as well. You can upload custom routes in the labs page of the admin panel (the last section)


Hey Ron,

The dynamic routing page is intended to give a strong understanding of how everything works with examples of the exact format - but you can also find more detailed examples of dynamic routing in action for specific use cases in the tutorials section. If there are any specific use cases you are trying to achieve that aren’t documented in the tutorials I’d love to hear what they are :slight_smile:


Here’s the issue, the documents refer to to things without be clear where these things are located.

I’m 100% sure it’s clear to you, but to folks that are not the developers, it is a black hole.

For example, it’s stated one can upload a new/modified routes.yaml file via the Adam application. Cool, but where? Yes I finally found the where after quite a bit of poking around. Visible screen shot(s) would be extremely helpful.

One of the ghost docs says the space is critical to the routes.yaml file. Ok, but what is the spacing? I found the samples in the ghost docs show a space between tag: and the tag, but this causes an error. Removing the space solves the error yet, there
has to be a space between controller: and channel. Consistent form is a good coding practice.

If this still isn’t clear, either call me or otherwise let me know.


Ron Mitchell



Hi Ron,

Thanks for the feedback about where things are located in Ghost admin, I’ll make sure this gets noted. We keep a log of docs feedback and use community comments to drive decisions about what gets updated or added to the docs site.

As for the indentation being critical, I’ve updated the dynamic routing page to explain that 2 spaces is the suggested method. The strict indentation requirement is how YAML works as a structured data format. As @vikaspotluri123 mentioned, so long as you are consistent with your spacing (and do not use tab), then you shouldn’t get any formatting errors.

Related to having a space between tag: and the tags themselves, I’ve searched our docs and I can’t find an example of where this is shown incorrectly in the code examples - but let me know if you can remember the error that you stumbled upon and I’ll look into it.

If using tag: under taxonomies then there is a space. For example:

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

If using tag: after filter: then the tags are entered without a space. Example:

    controller: channel
    filter: tag:[iphone,ipad]

Hope this helps :slight_smile: