Dynamic routing docs

[JohnONolan]

This PR moves dynamic routing docs out of core concepts and into the handlebars theme documentation, with expanded descriptions and examples.

Preview

https://deploy-preview-83--tryghost.netlify.com/api/handlebars-themes/routing/

Questions

• Does this make sense?
• Is anything unexpected?
• Is anything missing?
• Does it seem weird to have redirects all by themselves in core concepts now? Cause they also only apply when using Ghost handlebars front end, just like dynamic routing. I feel like maybe they should move over too -- and that would potentially make it possible to break the massive core config page up into multiple pages which are easier to digest, and can have more detail.

Notes

• The data property is purposely under-documented here in its most simple form. It's actually much more powerful, but I don't feel like we have a good way of explaining (yet) how and when to use it.
• The currently live dynamic routing docs can be found here: https://docs.ghost.org/concepts/routing/

[netlify[bot]]

Deploy preview for tryghost ready!

Built with commit 2edffa29ededea5218ed7d77dd39db6c3d0c26de

https://deploy-preview-83--tryghost.netlify.com

[kevinansfield]

In general everything reads much better than before! 🎉 I didn't find anything except some proof-reading type things...

Overview

defined in content/settings/routes.yaml - which you can edit directly, but you can also upload/download this file

On first read this seemed to suggest that editing directly is the preferred option, however that comes with the caveat that Ghost needs to be restarted manually each time it's changed which isn't mentioned anywhere.

because aren't enough unfunny

Missing "there"?

when you accidentally uses the wrong

uses -> use

Maybe you want your homepage to simple landing page

Missing "be"?

Routes

Custom routes are handy for creating static pages of Ghost Admin

I'm not really sure what this means?

Let's say you've got a big Features landing page called with all sorts of animations

What is the "called" referring to here?

Taxonomies

you might prefer author and topic.

Should this be topic and host to match the example code?

Channels

stream of content paginated content matching a specific filter

Too many "content"s?

It's a filtered view of a slice of content from across your site

Seems like it should say "a filtered view" or "a slice of content", or maybe "a filtered slice of content"? Having both felt redundant and tripped me up when reading.

filter to determine what posts to return

Maybe just a stylistic thing but I expected "what" to be "which" here

Properties

Determines what Handlebars template file will be used for this route.

Same as the what/which thing above. I have no idea what the "officially correct" word is here though 😬 (or indeed if one even exists)

{primary_tag} - the first tag listed in the post settings, eg. news {primary_author} - first author in post settings, eg. cameron

Should this specify that it's the slug of the tag/author that will be put in the URL?

Further reading

router1

The hash link wasn't working for me, clicking it I just got a page flash like the whole page was re-loading. Maybe a Safari bug?

You probably noticed that all the examples here use trailing slashes on routes

Most of the examples on the Routes page don't have trailing slashes 😬

[JohnONolan]

Absolutely R E K T

[ErisDS]

Ignore me, Kevin did list that one

[ErisDS]

content taxonomies

Taxonomies are groupings of post based on a common relation

post -> posts

---

• The data property is purposely under-documented here in its most simple form. It's actually much more powerful, but I don't feel like we have a good way of explaining (yet) how and when to use it.

To be clear, this has gone above and beyond removing the browse option that was the subject of discussion that I understood this morning, to also remove the full long form, the concept of multiple data entries, renaming the data, and the ability to disable redirects. This is all on purpose?

[aileen]

Custom Routes

The downside of using an /about/team route to point at a stattic team.hbs template is that it's... well: static.

stattic -> static

---

Didn't find anything else content-wise, but I was wondering if it makes sense to either not show the TOC here, or to make some headings in the text to fill the TOC?

Note: you could switch off the TOC from within MD by adding toc: false to the frontmatter data of the specific post.

[kymellis]

Overall makes a lot more sense and feels more aimed toward theme developers and beginners. Has a lot more personality too. I think this style would really suit the rest of the Handlebars docs to help reduce the barrier to entry for getting started with Ghost 🎉

---

Some additional copy suggestions I spotted below:

Routes

Custom routes are handy for creating static pages of Ghost Admin, because you don't want them to be editable, they use lots of custom code, you want them to be versioned in Git, or you need to create a specific custom URL which isn't possible using Ghost content and slugs.

Should this be static pages outside of Ghost Admin? Or without using Ghost Admin? This sentence is a bit long and needs revising for clarity.

Suggestion: "Custom routes are handy for creating static pages that are not editable inside Ghost Admin. These pages use custom code, which can be versioned in Git and used to create a specific custom URL which isn't possible using Ghost content and slugs."

Rather than trying to cram all the code into the Ghost editor and hope for the best, you could store the code in a custom template called features.hbs

Suggestion to change "you could store" to, "dynamic routing allows you to store the code in a custom template". Maybe just me - but saying "you could do this" doesn't sound very convincing.

Now you've created a new static page in Ghost, programmatically, without the admin!

"Without the admin" might not be automatically clear to some people? "Without using Ghost Admin" would be clearer.

Unlike the Features landing page, the team page here is just a list of team members which needs to be fairly regularly updated; so it would be inconvenient to have to do that in code each time.

This sentence tripped me up for some reason. Suggestion:

"Unlike the Features landing page, the team page needs to be updated fairly regularly with a list of team members; so it would be inconvenient to have to do that in code each time."

In the examples used so far, routes have been configured to generate a single page some data and a template, but that's not all routes can do.

Missing comma after single page?

Content Taxonomies

Taxonomies are groupings of post based on a common relation.

Post should be posts.

and each of these places also come with their own automatically generated RSS feeds which can always be accessed by adding /rss/ to the end of the URL.

Suggestion: "Each of these come with their own automatically generated RSS feeds which are accessed by adding /rss/ to the end of the URL."

Channels

If you're still not sure which would be the best fit

Suggestion for tense: "If you're still not sure which is the best fit for you"

Further Reading

While the docs here cover simple examples and broad use-cases, you'll find more detailed and specific use-cases of how to build different types of website and publication using dynamic routing.

Introduces tutorials without mentioning them, suggestion:

"While these docs cover simple examples and broad use-cases, you'll find more detailed and specific use-cases of how to build different types of publication in these tutorials:"

[JohnONolan]

To be clear, this has gone above and beyond removing the browse option that was the subject of discussion that I understood this morning, to also remove the full long form, the concept of multiple data entries, renaming the data, and the ability to disable redirects. This is all on purpose?

Yes it's absolutely intentional. As far as I can tell there is not a single person inside or outside of Ghost who is able to explain the longform data property, including most of the people who actually worked on it. There could not physically be more red flags.

It's absolutely not ready to be promoted and there is no way to document the redirect switch thanks to the mandatory variable and type properties which can neither be left out nor explained without documenting the entire thing.

Whole thing needs a lot more discussion, none of which should block the rest of the docs.

--

Have implemented every single other fix/suggestion mentioned by everyone ☝️ above

[JohnONolan]

Nobody has replied to my question about redirects locations - so if there are no objections then I intend to move them into the same place and out of core concepts - I think that makes more sense

[kymellis]

Oh yeah I think moving redirects too makes total sense @JohnONolan since it's only applicable when using the Ghost front-end. However, it does then make all of the handlebars stuff quite hidden within the site, though I suppose people can just search.

Would it be worth having a link to the handlebars section on the homepage somewhere for theme developers who land on docs.ghost.org? Edit: NVM I see the Frontend SDKs link covers that.

I am sure you have done already but just incase, remember to add some redirects from the old locations -> new ones in handlebars before it goes up :)

[kirrg001]

https://deploy-preview-83--tryghost.netlify.com/api/handlebars-themes/routing/collections/#creating-multi-lang-sites

collections:
  /:
    permalink: /{slug}/
    template: index
    filter: tag:-de
  /de/:
    permalink: /de/{slug}/
    template: index-de
    filter: tag:de

FYI: "tag:-de" will show all posts which are not tagged at all and posts with any tags.

---

https://deploy-preview-83--tryghost.netlify.com/api/handlebars-themes/routing/channels/

filter: tag:column+author:cameron

I'd suggest not using "author:", because it's deprecated. Either authors: or primary_author.

---

Most of the examples on the Routes page don't have trailing slashes 😬

Yeah very important :)

---

• Does it seem weird to have redirects all by themselves in core concepts now? Cause they also only apply when using Ghost handlebars front end, just like dynamic routing. I feel like maybe they should move over too -- and that would potentially make it possible to break the massive core config page up into multiple pages which are easier to digest, and can have more detail.

Yeah somehow makes sense. The middleware is only attached to the "site/frontend" anyway.

[JohnONolan]

Would it be worth having a link to the handlebars section on the homepage somewhere for theme developers who land on docs.ghost.org?

yeah, I also think we needed clearer labelling of "ghost themes" not just "handlebars" - it's in a bit of an awkward place atm. Am stewing on it

FYI: "tag:-de" will show all posts which are not tagged at all and posts with any tags.

Yep that's fine I think

I'd suggest not using "author:", because it's deprecated.

Good point

[ErisDS]

I completely agree about moving redirects, and having one place for all the frontend "stuff".

Also in general this is much clearer, and having it all grouped together makes way more sense 👍

---

One thing that's definitely additional to the changes here, but related to the conversation about the ghost theme / frontend vs handlebars.

I find it tricky not having a full list of helpers anywhere in the docs, as even though the categorisation made sense when I reviewed it, in reverse I find myself guessing which section a helper might be under when I'm trying to find the docs for it.

[peterzimon]

Everything is clear 🎉

On the Channels page: shouldn't "If you want something more flexible than tags(...)" be "If you want something more flexible than taxonomies(...)"?