Prev & Next 2.0: refactor & primary tag support

[ErisDS]

## Part 1: Refactor next/prev

Many, many moons ago, we added special helpers {{prev_post}} and {{next_post}} to the theme API.

You can read a little bit about how we struggled to implement this, back in the day before we had a proper API, or a plan, or well anything here and here.

At the time, we ending up implementing this as a set of ?include parameters that could be fetched from the posts.read endpoint, i.e. you could fetch one post WITH its next and/or previous post at the same time. This was inefficient, and results in lots of extra queries.

Now in Ghost, we have a feature-rich filter parameter on the posts API, which makes implementing something like next and previous posts much easier. Even though our documentation for the get helper officially lists date filtering as being one of the remaining limitations (because I'd never tested it) it does actually work 🎉 apparently, across sqlite3 and mysql without issue, and really quite well.

Previous post query: /posts/?filter=slug:-[current-post-slug]+published_at:<='current-post-published-at'&order=published_at desc&limit=1
Next post query: /posts/?filter="slug:-[current-post-slug]+published_at:>='current-post-published-at'&order=published_at asc&limit=1

Seeing as the old implementation is inefficient, ugly and results in a lot of extra code, and implementing this with filters is efficient and very light on code, we want to get rid of the old implementation.

This would be a breaking API change, however the ability to include next/prev was never documented, and I do not see any usages of it on Ghost(Pro) in the last 7 days, and therefore I believe it is only ever used via the {{next_post}} and {{prev_post}} helpers, and is safe to remove.

Part 2: Add support for primary tags

Using the new, filter based implementation, we'd like to make it possible to output the next or previous post, which have the same primary tag as the current post.

This will be implemented with an extra parameter for the {{next_post}} and {{prev_post}} and helpers, e.g:

{{#next_post in="primary_tag"}}
      {{> "post-card"}}
{{/next_post}}

{{#prev_post in="primary_tag"}}
       {{> "post-card"}}
{{/prev_post}}

This will change which next and previous post is output, so that it is the next post inside the list of posts which share the same primary tag, instead of the next post across the whole blog.

If you don't provide the in="" clause, the {{#next_post}}{{/next_post}} & {{#prev_post}}{{/prev_post}} helpers will continue to work exactly as they do now.

Short term, the only value the in="" clause will support is "primary_tag". Longer term, we'll roll out support for channels when #5091 is closer to being usable, etc.

---

Summary

This issue proposes a breaking change to the JSON API, removing the undocumented ability to fetch next/prev post directly using includes. Instead, anyone who did use this feature would need to use the filter param instead.

Meanwhile, the widely used {{#next_post}}{{/next_post}} & {{#prev_post}}{{/prev_post}} helpers will work exactly as they did before, with no changes. The underlying implementation will be more efficient (hopefully improving page load times and reducing load on the database).

Finally, we're adding an extra parameter to the {{#next_post}}{{/next_post}} & {{#prev_post}}{{/prev_post}} to support fetching the next/prev post inside of a primary tag.

• Remove old next/prev includes from post API
• Swap the {{#next_post}}{{/next_post}} & {{#prev_post}}{{/prev_post}} helpers to use the filter parameter instead
• Tests for the API & date based filtering
• Update get helper documentation to include date-based filtering
• Update api documentation to include data-based filtering