Skip to content

[5.x] Multi-site documentation overhaul #1307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 5, 2024
Merged

[5.x] Multi-site documentation overhaul #1307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e68e97a
Update multisite conversion doc.
jesseleite Apr 5, 2024
1ea441d
Overhaul of main `/multi-site` page.
jesseleite Apr 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 128 additions & 104 deletions content/collections/docs/multi-site.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,126 +17,156 @@ Each site can have different base URLs:
- subdomains: `example.com` and `fr.example.com`
- subdirectories: `example.com` and `example.com/fr/`

[More details on how to convert to a multi-site setup](/tips/converting-from-single-to-multi-site)
::: tip
Every Statamic install needs at least one site. Building zero sites is a bad way to build a website and clients will probably challenge any invoices.
:::

### Converting Existing Content to Multi-Site

The simplest way to convert existing content to multi-site friendly structure is to run the automated command:

``` shell
php please multisite
```

Read more on [converting to a multi-site setup](/tips/converting-from-single-to-multi-site).

## Configuration

Let's look at a full site configuration and then we'll explore all of its options.
### Enabling Multi-Site

First, enable `multisite` in your `config/statamic/system.php`:

``` php
# config/statamic/sites.php

return [
'sites' => [
'default' => [
'name' => config('app.name'),
'locale' => 'en_US',
'url' => '/',
'direction' => 'ltr',
'lang' => 'en',
]
]
];
'multisite' => true,
```

### Sites
Every Statamic install needs at least one site. Building zero sites is a bad way to build a website and clients will probably challenge any invoices.
### Adding New Sites

### Locale
Each site has a `locale` used to format region-specific data (like date strings, number formats, etc). This should correspond to the server's locale. By default Statamic will use English – United States (`en_US`).
Next, you can add new sites through the control panel:

:::tip
To see the list of installed locales on your system or server, run the command `locale -a`.
:::
<figure class="mt-0 mb-8">
<img src="/img/configure-sites.png" alt="Configure sites page in control panel">
</figure>

### Language
Statamic's control panel has been translated into more than a dozen languages. The language translations files live in `resources/lang`.
Or directly in your `content/sites.yaml` file:

You may specify which language translation to be used for each site with the `lang` setting. If you leave it off, it'll use the short version of the `locale`. e.g. If the locale is `en_US`, the lang will be `en`.
``` yaml
default:
name: First Site
url: /
locale: en_US
second:
name: Second Site
url: /second/
locale: en_US
```

## Available Options

```php
'sites' => [
'de' => [
'name' => 'Deutsche',
'locale' => 'de_DE',
// 'lang' => 'de', // Not needed as 'de' is implied.
],
'de_ch' => [
'name' => 'Deutsche (Switzerland)',
'locale' => 'de_CH',
'lang' => 'de_CH', // We want the de_CH language, not de.
]
]
Let's look at a full site configuration and then we'll explore all of its options.

``` yaml
# content/sites.yaml

en:
name: English
url: /
locale: en_US
lang: en
attributes:
theme: standard
```

Note that both Statamic and Laravel don't ship with frontend language translations out of the box. You have to provide your own string files for this. There is a great package called [Laravel Lang](https://github.com/Laravel-Lang/lang) containing over 75 languages that can help you out with this.
### Handle

Each site is keyed by its `handle`, which is important for directory structure, as well as referencing sites in collection configs, etc. throughout your site. Changing this is non-trivial, and you should be careful if you already have established content in this site. Read more about [renaming sites](#renaming-sites).

``` yaml
en: # <- This is your site handle
name: English

```
### Name

Each site has a `name`, which is a display-friendly representation of your site's name mostly seen within control panel UI. Changing this does not affect content relations.

``` yaml
en:
name: English
```

::: tip
You'll notice the default site dynamically references a [config variable](/variables/config), but feel free to change this!

``` yaml
default:
name: '{{ config:app:name }}'
```
:::

### URL
URL is required to define the root domain Statamic will serve and generate all URLs relative to. The default `url` is `/`, which is portable and works fine in most typical sites. Statamic uses a little magic to work out what a full URL is based on the domain the site is running on.

Each site requires a URL to define the root domain Statamic will serve and generate all URLs relative to. The default `url` is `/`, which is portable and works fine in most typical sites. Statamic uses a little magic to work out what a full URL is based on the domain the site is running on.

:::best-practice
It can be a good idea to change this to a **fully qualified, absolute URL**. This ensures that server/environment configurations or external quirks don't interfere with that "magic". Using an environment variable is an ideal solution here.

```php
'sites' => [
'en' => [
// ...
'url' => env('APP_URL')
],
'fr' => [
// ...
'url' => env('APP_URL').'fr/'
]
]
It can be a good idea to change this to a **fully qualified, absolute URL**. This ensures that server/environment configurations or external quirks don't interfere with that "magic".

```yaml
en:
# ...
url: '{{ config:app:url }}'
fr:
# ...
url: '{{ config:app:url }}/fr/'
```

By default, this is linked to your `APP_URL` environment variable, which allows you to control the exact URL by environment:
```env
# production
APP_URL=https://mysite.com/

# development
APP_URL=http://mysite.test/
```
:::

### Locale

Each site has a `locale` used to format region-specific data (like date strings, number formats, etc). This should correspond to the server's locale. By default Statamic will use English – United States (`en_US`).

:::tip
To see the list of installed locales on your system or server, run the command `locale -a`.
:::

### Text Direction
### Language

All sites are Left-To-right (`ltr`) by default, and you may omit the setting entirely. But if any of your sites is in a `rtl` text direction (like Arabic or Hebrew), you may define the direction in the config and use it on your front-end wherever necessary.
Statamic's control panel has been translated into more than a dozen languages. The language translations files live in `resources/lang`.

```php
'sites' => [
'en' => [
'name' => 'English',
],
'he' => [
'name' => 'Hebrew',
'direction' => 'rtl',
]
]
```
You may specify which language translation to be used for each site with the `lang` setting. If you leave it off, it'll use the short version of the `locale`. e.g. If the locale is `en_US`, the lang will be `en`.

```
<html dir="{{ site:direction }}">
``` yaml
de:
name: Deutsche
locale: de_DE
# Lang not needed, as `de` is implied
de_CH:
name: 'Deutsche (Switzerland)'
locale: de_CH
lang: de_CH # We want the `de_CH` language, not `de`
```

:::tip
Statamic's `direction` is `ltr` by default. You only need to set `direction` when your site is `rtl`.
:::
Note that both Statamic and Laravel don't ship with frontend language translations out of the box. You have to provide your own string files for this. There is a great package called [Laravel Lang](https://github.com/Laravel-Lang/lang) containing over 75 languages that can help you out with this.

### Additional Attributes

You may also add an array of arbitrary attributes to your site's config, which can later be accessed with the [site variable](/variables/site) .

```php
'sites' => [
'en' => [
'name' => 'English',
'attributes' => [
'theme' => 'standard',
]
],
]
You may also include additional arbitrary `attributes` in your site's config, which can later be accessed with the [site variable](/variables/site).

``` yaml
en:
# ...
attributes:
theme: standard
```

```
Expand All @@ -147,27 +177,21 @@ You may also add an array of arbitrary attributes to your site's config, which c
Nothing fancy happens here, the values are passed along "as is" to your templates. If you need them to be editable, or store more complex data, you could use [Globals](/globals).
:::

## Text Direction

Text direction is automatically inferred by Statamic, based on the [language](#language) of your configured site.

## Adding a Site
For example, most sites will be `ltr`, but Statamic will automatically use `rtl` for languages like Arabic or Hebrew.

To add another site to an existing multi-site installation, add another array to the `$sites` configuration array along with the desired settings.
If you need to reference text direction in your front end, you make use the [site variable](/variables/site):

```php
'sites' => [
'en' => [
'name' => 'English',
//
],
'de' => [
'name' => 'German',
//
],
];
```
<html dir="{{ site:direction }}">
```

## Renaming a Site
## Renaming Sites

If you rename a site handle, you'll need to update a few folders and config settings along with it. Replace `{old_handle}` with the new handle in these locations:
If you rename a site's [handle](#handle), you'll need to update a few folders and config settings along with it. Replace `{old_handle}` with the new handle in these locations:

**Content Folders**

Expand Down Expand Up @@ -206,15 +230,15 @@ permissions:

[Views](/views) can be organized into site directories.

If a requested view exists in a subdirectory with the same name as your site, it will load it instead. This allows you have site-specific views without any extra configuration.
If a requested view exists in a subdirectory with the same name as your site [handle](#handle), it will load it instead. This allows you have site-specific views without any extra configuration.

``` php
# config/statamic/sites.php
``` yaml
# content/sites.yaml

'sites' => [
'site_one' => [ /* ... */ ],
'site_two' => [ /* ... */ ],
]
site_one:
# ...
site_two:
# ...
```

``` files theme:serendipity-light
Expand Down
Loading