Closed JohnONolan closed 5 years ago
Deploy preview for tryghost ready!
Built with commit 2edffa29ededea5218ed7d77dd39db6c3d0c26de
In general everything reads much better than before! 🎉 I didn't find anything except some proof-reading type things...
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"?
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?
you might prefer
author
andtopic
.
Should this be topic
and host
to match the example code?
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
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?
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 😬
Absolutely R E K T
Ignore me, Kevin did list that one
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?
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.
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:
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?
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."
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"
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:"
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
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
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 :)
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.
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
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.
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(...)"?
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
Notes