Dynamic Routing

Refs: https://github.com/TryGhost/Ghost/issues/9528 (YAML Settings), https://github.com/TryGhost/Ghost/issues/9192 (Routing re-write), https://github.com/TryGhost/Ghost/pull/9550 (Url Service).

The what and why of dynamic routing

Ghost’s Routing has always been almost entirely static and hard-coded. The only config we’ve offered is the option to add dates to permalinks, but that setting is probably my least favourite part of Ghost 😂

People close to the project will have heard a lot about a mysterious feature called “channels”, which was an attempt to expose more configuration around lists of posts. This has been working behind the scenes, but we haven’t been clear on how to expose the functionality: Apps? Config? UI?

Early this year we sat down and rethought routing from the ground up with a view to answering the following questions: How can we make it possible to solve all the common routing use cases? How do we expose functionality to our users? How does this fit in with Apps? And where the fuck do Channels fit into all of this?

Top 3 common use cases we want to solve:

1. custom home pages
2. rendering a taxonomy at a non-standard URL, e.g. /tag/recipes/ -> /category/recipes/
3. customising post collections e.g. removing posts with a certain tag, or using a different URL

There are 3 main problems we have with trying to reach these use cases:

• How to make routes enumerable and configurable
• Ability to generate sitemaps and other features that need to know about URLs rather than routes
• Resource <-> URL 2 way binding - get resource from URL, get URL for resource

We think we have the answers, however the theory is never quite the same as the practice. This issue represents our current thinking at the time of writing and is very subject to change!

What’s coming?

In https://github.com/TryGhost/Ghost/issues/9528 we added the ability to customise Ghost through YAML files that live in content/settings. The first file that will live here will be routes.yaml, and this will be the gateway to all things dynamic routing. This solve the configuration problem.

The solution to everything else is the introduction of a URL service and a huge rewrite of all the code that generates content for Ghost blogs 😅

Beta Goals

In the first beta version, by editing content/settings/routes.yml it will be possible to:

• Define a custom route that renders a specific template
• Define a custom home page
• Change the location of the standard collection of posts, e.g. so they all live at /blog/*.
• Change the URL for taxonomies e.g /tag/:slug/ -> /category/:slug/
• Customise the main post collection (v1 has severe known limitations)
• Define new collections (v1 has severe known limitations)

Once the first beta goes out we will be looking for people to test their routing use-cases. At that point, we’ll publish some documentation on how the default routes.yml file is structured and how to define custom routes and collections within the limitations.

Tracked tasks

• YAML Settings #9528
• Url Service rewrite #9550
• Dynamic sitemap 100% working (https://github.com/TryGhost/Ghost/pull/9580)
• Rework url utility https://github.com/TryGhost/Ghost/pull/9593
• Routing re-write https://github.com/TryGhost/Ghost/pull/9596
• render 503 if url service is processing (https://github.com/TryGhost/Ghost/pull/9588)
• Resources have full 2-way binding https://github.com/TryGhost/Ghost/pull/9596

Overall Goals

This issue will be closed when we achieve the following:

• Ship first beta version of dynamic routing
• First version of channels (https://github.com/TryGhost/Ghost/pull/9686)
  • Resource path aliases with automatic redirects (Need a separate issue explaining this feature!)
• Data key, order, limit, redirect
• Disable rss (https://github.com/TryGhost/Ghost/pull/9693)
• Extracted: disable sitemaps, disable pagination (https://github.com/TryGhost/Ghost/issues/10313)
• Extracted: All hard-coded public routes (e.g. page) are configurable inc homepage (https://github.com/TryGhost/Ghost/issues/10312)
• Add UI to upload+reload routes.yaml file (https://github.com/TryGhost/Ghost/issues/9744)

Note: There are some extensions to the dynamic routing behaviour that are known but not covered by this issue, which include custom controllers and custom taxonomies

💡 Please direct all questions & discussion to the forum. This issue will be used for collecting bugs & use cases once the beta goes out.

[kirrg001]

FYI: We will officially announce Dynamic Routing Beta in Ghost 2.0.

[kirrg001]

Dynamic Routing Beta was shipped in Ghost 1.24.0. I am closing this issue for now. I extracted two sub features, which we aren’t able to achieve yet.

Any further improvement or bug should be tracked separately 👻