Open Sitez Documentation

Documentation main page


Open Sitez definition.osz

Routes Configuration

The definition.osz file in Open Sitez contains various sections to configure your website, including the "Routes" section. This section defines how URLs are mapped to specific content or functionality within your site. In this documentation, we'll provide a comprehensive overview of route configurations.

Introduction to Routes

Routes play a critical role in Open Sitez, allowing you to define how your website responds to different URLs. Each route is specified in the configuration with a unique name and a set of attributes that determine its behavior.

Route Types

Open Sitez supports several route types, each serving a specific purpose. With most plugins providing a type of route, I would recommend to checkout the plugins section for individual route types

Here are some common route types and their descriptions:

Page Route

Blog Route

Redirect Route

Feed Route

Form Route (Work in Progress)

Route Configuration Examples

Let's explore various examples of route configurations, including examples for a few route type:

Static Page Route

This example defines a static page route named "default" that displays an HTML file named "index.html."

  type: page
    type: include
    file: index.html

Dynamic Blog Route

This configuration sets up a dynamic blog route named "thoughts" with a limit of 20 posts and specifies the ID of the blog.

  type: blog
  limit: 20
  feature: 10

Redirect Route

This example creates a route named "old-page" that redirects visitors from "/old-page" to "/new-page/."

  type: redirect
  redirect: /new-page/

Form Route (Work in Progress)

This section is under development and will be expanded upon in future releases.

Page Route Layouts

Page routes of the "page" type can specify layouts that define the structure of the page. Layouts can be shared among multiple pages. If a layout is not explicitly specified, Open Sitez will look for the default layout. Below is an example of how to specify a layout for a page route:

  type: page
  layout: custom-layout
    type: include
    file: my-page-content.html

In this example, the "my-page" route specifies a custom layout named "custom-layout" for its page content. If "layout" is not provided, Open Sitez will use the default layout.

Additional Route Attributes

In addition to route type-specific attributes, you can use various attributes to customize the behavior of your routes. These attributes include:

These attributes allow you to create a wide range of customized routes tailored to your website's needs.

Authentication Options

Open Sitez provides flexible authentication options for protected routes. You can use either simple authentication or database-driven authentication, depending on your requirements.

Simple Authentication

This configuration defines a password-protected page route named "admin" using simple authentication. It includes two users, "aladdin" and "admin," with specific passwords and group assignments.

  type: page
    type: simple
        password: opensesame
        password: badpassword
        group: admin

Database-Driven Authentication

You can extend authentication to use a database as the source for user information. This example demonstrates database-driven authentication with the "query" type, allowing you to customize options such as the database table and fields.

            type: query
            table: users


The "Routes" section in the Open Sitez definition.osz configuration file is a powerful tool for defining how URLs are handled on your website. By understanding route types, attributes, and authentication options, you can create dynamic, secure, and user-friendly web experiences for your visitors.