kirby-routing-and-representations

Kirby Routing and Representations

Use Kirby 6 conventions for new work. Reserve template data names $slot/$slots and helper names push()/endpush()/stack() for Kirby's template system.

KB entry points

• kirby://kb/scenarios/13-custom-routes
• kirby://kb/scenarios/21-filtering-via-routes
• kirby://kb/scenarios/49-sitemap-xml-route
• kirby://kb/scenarios/78-trailing-slash-and-canonical-urls
• kirby://kb/scenarios/02-json-content-representation-ajax-load-more

Required inputs

• URL pattern and HTTP methods.
• Response type and content language behavior.
• Redirect or canonicalization rules.

Decision guide

• Use content representations for page-backed JSON/XML/RSS.
• Existing representations also support HTTP Accept negotiation. Test ordinary URLs, explicit extensions, Content-Type and cache separation; see kirby://glossary/content-representation.
• Use routes for non-page endpoints, redirects, or custom logic.
• Avoid greedy patterns that shadow representations.

Pattern hint

• Put specific routes before catch-alls; avoid top-level (:all) when using representations.

Canonical redirect example

[
  'pattern' => '(:any)/',
  'action' => function ($path) {
    return go('/' . trim($path, '/'), 301);
  }
]

Common pitfalls

• Route patterns that shadow .json or .rss representations.
• Expecting kirby:kirby_render_page to execute route logic.

Workflow

1. Clarify the URL pattern, HTTP methods, response type, and language behavior.
2. Call kirby:kirby_init and read kirby://roots to locate config and template roots.
3. Read kirby://config/routes to understand current route configuration.
4. If runtime is available, call kirby:kirby_routes_index to see registered patterns; otherwise run kirby:kirby_runtime_status and kirby:kirby_runtime_install first.
5. Inspect existing templates/controllers to avoid collisions:
   • kirby:kirby_templates_index
   • kirby:kirby_controllers_index
6. For content representations, add site/templates/<template>.<type>.php and optional site/controllers/<template>.<type>.php.
7. For routes, add or adjust routes in site/config/config.php or a plugin. Avoid greedy patterns that shadow .json/.rss representations.
8. Validate output:
   • use kirby:kirby_render_page(contentType: json|xml|rss) for representations
   • manually hit route URLs for router behavior (render does not execute the router)
9. Search the KB with kirby:kirby_search (examples: "custom routes", "json content representation", "filtering via routes", "sitemap.xml", "trailing slash").