Ghost Release: 1.24.6

TL;DR

Ghost 1.24.6: Dynamic Routing Beta Enhancements

This release significantly expands the Dynamic Routing beta with powerful new features including Channels, RSS customization, and improved collection filtering. The update introduces more flexible template support, better resource configuration, and enhanced routing controls. It also fixes several bugs including dated URLs when timezone changes and updates documentation links throughout the codebase. This release lays important groundwork for the upcoming public announcement of Dynamic Routing.

Highlight of the Release

• Dynamic Routing Beta now supports Channels - a way to create different views of posts without changing URLs
• Added ability to disable or override RSS feeds for collections and channels
• Improved template support with multiple definition formats
• Fixed dated URLs when timezone changes
• Replaced jsonpath with more powerful NQL for collection filtering

Migration Guide

for Dynamic Routing Beta

If you're using the Dynamic Routing beta, this release includes several enhancements and changes:

1. Routes.yaml Migration:

   • Ghost will automatically migrate existing routes.yaml files if they match the old format
   • The home.hbs behavior for the index collection (/) is now hardcoded in Ghost
   • The default routes.yaml file reflects how Ghost worked before dynamic routing

2. Template Changes:

   • Static routes now render default.hbs as fallback instead of index.hbs
   • Collection names are now used for template lookup (e.g., a collection named "podcast" will look for podcast.hbs)
   • Explicitly defined templates take precedence over the collection name

3. Router Changes:

   • Static routes are now stronger than taxonomy in the router hierarchy
   • Site and App Routers have been renamed for consistency
   • res._route and res.locals.routerOptions have been consolidated

4. Collection Filtering:

   • jsonpath has been replaced with NQL for collection filtering
   • The featured:true filter is still supported for collections

If you're using custom routes.yaml configurations in the beta, you may need to review your setup to ensure compatibility with these changes.

Upgrade Recommendations

This is a minor release with significant enhancements to the Dynamic Routing beta and several bug fixes. We recommend all users upgrade to this version, especially if you:

1. Are participating in the Dynamic Routing beta
2. Use dated permalinks and have changed your site's timezone
3. Have experienced issues with model defaults

The upgrade process should be straightforward with no breaking changes for standard Ghost installations. If you've been experimenting with the Dynamic Routing beta, please review the migration guide for potential adjustments to your routes.yaml configuration.

To upgrade:

1. Back up your Ghost installation
2. Follow the standard upgrade process for your installation method
3. If using the Dynamic Routing beta, review your routes.yaml file for compatibility with the enhanced features

Bug Fixes

• Fixed dated URLs when timezone changes: Collection router now subscribes to timezone events and regenerates URLs when timezone changes for dated permalinks

• Fixed missing defaults in model layer: Addressed an issue where model events were emitted without correct defaults

  • Added missing defaults for user & post models
  • Sanitized boolean values (converting 0/1 to false/true)
  • Ensures components listening on model events receive complete and properly formatted data

• StaticRoutesRouter now respects route name: Fixed an issue where the routeName was not parsed correctly for static routes

• Updated documentation links:

  • Fixed incorrect links to themes.ghost.org
  • Updated links to use HTTPS
  • Replaced dev.ghost.org references with blog.ghost.org
  • Updated theme fixture post to direct users to the Ghost forum instead of Slack

New Features

Dynamic Routing Beta Enhancements

• Channels Support: Added the ability to define channels in routes.yaml, allowing different views of posts without changing URLs

  routes:
    /worldcup-2018-russia/:
      controller: channel
      filter: tag:football18
      data: tag.football18
  

• RSS Customization: Added ability to disable RSS feeds with rss:false or define custom RSS URLs with target templates

• Enhanced Collection Features: Added support for data, limit, and order parameters for collections

  • Limit definition in routes.yaml takes precedence over theme package.json configuration

• Flexible Template Definition: Multiple ways to define templates for routes and collections

  # Simple format
  routes:
    /about/: about
    
  # Expanded format
  routes:
    /about/:
      template: about
      
  # Multiple templates
  routes:
    /about/:
      template:
        - about
        - me
  

• Redirect Support: Added ability to define redirects in routes.yaml and pre-check for redirects before rendering static pages

• Collection Name Behavior: The collection name is now remembered as routerName and used for context values and template lookup

Other Improvements

• Updated password reset email text to offer peace of mind for users who didn't initiate the request
• Added debug logging to Base model's emitChange method (accessible via DEBUG=ghost:models:base node index.js)

Security Updates

No specific security fixes were included in this release.

Performance Improvements

• Refactored Router Architecture: Restructured routing to support channels and improve overall routing efficiency

• Reordered Router Hierarchy: Static routes now take precedence over taxonomy, improving routing performance and predictability

• Dependency Updates:

  • [email protected]
  • [email protected]
  • [email protected]
  • [email protected]
  • [email protected]
  • [email protected]

Impact Summary

Ghost 1.24.6 significantly enhances the Dynamic Routing beta with powerful new features like Channels, RSS customization, and improved collection filtering with NQL. This release provides theme developers with more flexibility in defining templates and routing behavior, while fixing important bugs like dated URL issues when timezone changes.

The update to password reset emails improves security messaging, and documentation links throughout the codebase have been updated to reflect current resources. For developers working with the Ghost API, the model layer now properly handles defaults, ensuring consistent behavior when creating or updating content.

This release represents an important step toward the public announcement of Dynamic Routing, providing a more robust and flexible foundation for Ghost's routing system. The changes are primarily focused on enhancing developer capabilities rather than end-user features, laying groundwork for more visible improvements in future releases.

Full Release Notes