gerritvanaaken/multidomain-router

A Kirby plugin for routing and managing multiple domains in a single Kirby installation.

1.0.2 2025-11-10 15:02 UTC

Requires

• php: >=8.1
• getkirby/composer-installer: ^1.1

Requires (Dev)

• getkirby/cms: ^3

MIT

• Gerrit van Aaken

• routing
• multidomain
• kirby
• kirby-plugin

README

A Kirby plugin for routing and managing multiple domains within a single Kirby installation.

How It Works

The plugin automatically handles routing for multiple domains and replaces URLs in the rendered HTML output:

1. Routing: Intercepts all requests and maps them to the correct content folder based on the domain
2. URL Replacement: In the rendered output, all URLs are intelligently trimmed:
   • links within current domain (same folder): Converted to relative paths
   • links to sibling domain (different folder): Converted to the full absolute URLs

Installation (1/3)

via composer

To install the Multidomain Router plugin via composer, run:

composer require gerritvanaaken/multidomain-router

Make sure you are in the root directory of your Kirby project when running this command.

After installation, the plugin will be available at site/plugins/multidomain-router/. You can then continue with the configuration as described below.

manually

Download and copy the full plugin folder into site/plugins/.

Domain Configuration (2/3)

There are two methods to configure your domains:

Method A: Config File (Recommended)

Add the domain configuration directly in your site/config/config.php:

<?php

return [
    'praegnanz.multidomain-router.sites' => [
        [
            'domain' => 'https://example-domain-one.com',
            'folder' => 'example-domain-one',
            'error' => 'example-domain-one/error' //optional
        ],
        [
            'domain' => 'https://example-domain-two.com',
            'folder' => 'example-domain-two',
            'error' => 'example-domain-two/error' //optional
        ]
    ]
];

Configuration Options:

• domain (required): Full URL including protocol, no trailing slash
• folder (required): Content folder name, without any slashes
• error (optional): Path to custom error page (e.g. 'folder-name/error')

Method B: Panel Configuration (Fallback)

If you prefer to configure domains through the Panel:

1. Add the Multidomain config to your site/blueprints/site.yml, using extend:

title: Site

tabs:
  content:
    label: Seiten
    icon: page
    sections:
      pages:
        type: pages
  
  multidomains:
    extends: multidomain-router

1. Refresh the Panel and configure your domains:
   • Open the Panel and go to Site Settings
   • Locate the "Multidomain" section
   • Click "+ Add" to configure a new site
   • Enter the folder name (e.g. example-domain-one)
   • Enter the domain (e.g. https://example-domain-one.com)
   • Optionally select an error page
   • Don't forget to save! ✓

Note: If domains are configured in the config file (Method A), the Panel configuration will be ignored.

Folder creation (3)

To create the required content folders for each domain, follow these steps:

1. Navigate to your site's content directory (usually site/content in your Kirby installation).

2. Create a new folder for each domain.

   • The folder name must exactly match the folder value you set in your multidomain configuration.
   • For example:

     site/content/example-domain-one/
     site/content/example-domain-two/
     

3. Add content to each folder as usual.

   • Each folder will represent the homepage and pages for that particular domain.
   • The typical structure inside a folder:

     site/content/example-domain-one/home.txt
     site/content/example-domain-one/1_rooms/rooms.txt
     site/content/example-domain-two/1_rooms/1_penthouse/room.txt
     

   • Add your regular Kirby pages (folders ending in .txt/subfolders) inside the domain folder as you would for a single-site setup.

Tips:

• If a domain has a custom error page, make sure to create the corresponding error page in the respective folder, e.g.:

  site/content/example-domain-one/error/default.txt
  site/content/example-domain-two/error/default.txt
  

• Folder names and structure should remain consistent with your configuration to ensure correct routing.

That's it! Each domain will serve content from its respective folder.

Examples for URL replacements

On https://hotel-kirby.de

• /hotel-kirby/room → /room
• /restaurant-kirby/lunch → https://restaurant-kirby.de/lunch
• https://hotel-kirby.de/hotel-kirby/room → /room

On https://restaurant-kirby.de

• /restaurant-kirby/lunch → /lunch
• /hotel-kirby/room → https://hotel-kirby.de/room
• https://restaurant-kirby.de/restaurant-kirby/lunch → /lunch

License

MIT

Author

Gerrit van Aaken ([e-mail])