Locales

Locale support is achived configuring the sidebar in your configuration file.

When locale support is enabled, a language switcher will automatically appear in your documentation site.

Example

If you wish to provide both English and French versions of your documentation, convert your sidebar to an object, where the key is the 2-character ISO language code, and the value the usual sidebar configuration.

{
  "sidebar": {
    "en": [
      {
        "group": "Getting Started",
        "pages": [
          ["Get Started", "/"],
          ["Installation", "/installation"]
        ]
      }
    ],
    "fr": [
      {
        "group": "Commencer",
        "pages": [
          ["Commencer", "/"],
          ["Installation", "/installation"]
        ]
      }
    ]
  }
}

You should now change your documentation directory structure in the repository to match these paths.

/docs
  /en
    /index.mdx
    /installation.mdx
  /fr
    /index.mdx
    /installation.mdx

Now when accessing your documentation, specify the locale key in the URL, e.g.:

https://docs.page/:owner/:repository/en
https://docs.page/:owner/:repository/fr

Or when using Custom Domains:

https://sdk.acme.com/en
https://sdk.acme.com/fr

The sidebar will automatically switch to the correct locale based on the locale in the page. All links on the page are relative to the current locale, for example if the URL /installation is provided whilst viewing the French version of the documentation, the link will be /fr/installation.

Root Page

The root page of the documentation which does not have a locale can either be used to display content, or redirect to a default locale.

Redirecting

To redirect the root page to a default locale (e.g. en), add a redirect property to the root page frontmatter:

---
redirect: /en
---

Displaying Content

If you wish instead to display content on the root page, simply write markdown as usual. If you also wish to display a sidebar for the root page, you can specify a default sidebar in your configuration:

{
  "sidebar": {
    "default": [
      {
        "group": "Getting Started",
        "pages": [
          ["Get Started", "/"],
          ["Installation", "/installation"]
        ]
      }
    ],
    "en": [],
    "fr": []
  }
}