💋Kiss

Keep It Simply Static

Routes

Overview

A route is a page definition. Each file in route/ describes one route, its URL path, its Twig template, and the data it needs to render.

Fields

Field Required Description
path ✓ URL pattern, e.g. /about.html or /{slug}.html
template ✓ Twig template to render
data Metadata or archive context, merged into child pages
items Array of child items — one page per item when path has {param}
paginate Items per page for pagination

Supported formats

Format Extension Nested data $ref
YAML .yml / .yaml ✓ ✓
JSON .json ✓ ✓
PHP .php ✓ ✓

XML and INI are not supported for routes because they cannot represent nested arrays or the $ref syntax required by routes.

Single page

path: /index.html
template: page.twig
data:
  title: Home

{
  "path": "/index.html",
  "template": "page.twig",
  "data": {
    "title": "Home"
  }
}

<?php
return [
  'path' => '/index.html',
  'template' => 'page.twig',
  'data' => ['title' => 'Home'],
];

Pages with parameters

The items key allows you to generate one or multiple pages. Each item in this list generates a separate page. The data key contains metadata, merged into every child page.

path: /{slug}.html
template: post.twig
data:
  blog_title: "My Blog"
items:
  - slug: hello-world
    title: Hello World
  - slug: second-article
    title: Second article

{
  "path": "/{slug}.html",
  "template": "post.twig",
  "data": {
    "blog_title": "My Blog"
  },
  "items": [
    {
      "slug": "hello-world",
      "title": "Hello World"
    },
    {
      "slug": "second-article",
      "title": "Second article"
    }
  ]
}

<?php
return [
  'path' => '/{slug}.html',
  'template' => 'post.twig',
  'data' => ['blog_title' => 'My Blog'],
  'items' => [
    ['slug' => 'hello-world', 'title' => 'Hello World'],
    ['slug' => 'second-article', 'title' => 'Second article'],
  ],
];

External reference ($ref)

You can reference an external file using the $ref keyword. External references can be local files (e.g., data/articles.yml) or remote files (e.g., https://example.com/data/articles.yml).

path: /{slug}.html
template: post.twig
items:
  $ref: data/articles.yml

{
  "path": "/{slug}.html",
  "template": "post.twig",
  "items": {
    "$ref": "data/articles.yml"
  }
}

<?php
return [
  'path' => '/{slug}.html',
  'template' => 'post.twig',
  'items' => ['$ref' => 'data/articles.yml'],
];

Archive page with list

path: /blog
template: blog_list.twig
data:
  title: "Blog"
items:
  $ref: data/posts.yml

Template :

<h1>{{ title }}</h1>
{% for post in items %}
  <a href="{{ path('blog', {slug: post.slug}) }}">{{ post.title }}</a>
{% endfor %}

Pagination

path: /blog
template: blog_list.twig
paginate: 10
data:
  title: Archives
items:
  $ref: data/posts.yml

Generates blog/index.html (page 1) and blog/page/{n}/index.html.

{% for post in items %}
  ...
{% endfor %}
{% if prevPage %}
  <a href="{{ path('blog', {page: prevPage}) }}">← Previous</a>
{% endif %}
{% if nextPage %}
  <a href="{{ path('blog', {page: nextPage}) }}">Next →</a>
{% endif %}