Running multiple sites#

Managing big documentation sites or multiple at a time can be a challenge. On this page we talk about the challenges and how to overcome them.

The basics of running multiple sites#

Before we go over recommended techniques, let's first introduce the main method on how to configure these sites.

Sites in Guider don't neccesarily have completely seperate entities. Anything that is customized beyond just the contents of the sidebar is a new site. Think of sites as just a new instance of a Guider site.

A good use case of when to use a different site is if you want to have different content in the navigation header.

Making new sites in Guider is thankfully very easy. Instead of just putting in one site configuration, you can enter an array:

import { site, defineTheme } from "@neato/guider/theme"
 
export default defineTheme([
  site('site-a', {...}), 
  site('site-b', {...}), 
])

Site templates#

When you have many different sites that are mostly similar, it can be very verbose to reconfigure every site with the same settings.

That is where site templates come in: you can make a template and any site can use a template as its base.

import { site, link, defineTheme, siteTemplate } from "@neato/guider/theme"
 
const base = siteTemplate({
  navigation: [
    link("Example link", "/example"),
  ]
})
 
export default defineTheme([
  site("site-a", {
    extends: [base],
    // ... other settings go here ...
  })
])

You can provide multiple sites to extend from, they are merged in order of how they are passed in.

Recommended folder structure#

Folder structure of your pages directory is completely flexible and up to the writer's choice. However, below we have some recommendations for bigger projects.

1. Reserve a space for non-documentation: It's likely that big documentation sites will expand slightly outside of purely documentation. Think showcases, contact page, brand information. So it's wise to put your documentation on /docs so you can put everything else outside of it.
2. Put your concepts all on one level: When you have multiple concepts like a list of libraries or a list of applications. You should put all of them in the same level. For example, for library shoejs, jacketjs and sockdotnet. You would have folders: /docs/shoejs, /docs/jacketjs and docs/sockdotnet. Do not group them as /docs/libs/xxx or /docs/apps/xxx, it will only make it harder to find in your project structure with less predictable URLs.
3. Have a _meta.json file at the root of every concept: you should have a _meta.json file containing common configuration per concept. Following the previous examples, put one at /docs/shoejs/_meta.json. with { "site": "shoejs" }.
4. Have a theme.config.tsx file at the root of every concept: to prevent your site configuration from being gigantic, you can split it up per concept. Create a theme config that just exports the single site(...) instance for that concept. At the top level theme.config.tsx, you can import them all and just add them to the defineTheme()

To combine everything, here is the example folder structure from all the examples:

theme.config.tsx
pages/
├── index.mdx
├── contact.mdx
└── docs/
    ├── shoejs/
    │   ├── _meta.json
    │   ├── theme.config.tsx
    │   ├── index.mdx
    │   ├── getting-started/
    │   │   ├── install.mdx
    │   │   ├── features.mdx
    │   │   └── examples.mdx
    │   └── usage/
    │       ├── basics.mdx
    │       ├── advanced.mdx
    │       └── contributing.mdx
    ├── jacketjs/
    │   ├── _meta.json
    │   ├── theme.config.tsx
    │   ├── index.mdx
    │   ├── getting-started/
    │   │   ├── install.mdx
    │   │   ├── features.mdx
    │   │   └── examples.mdx
    │   └── usage/
    │       ├── basics.mdx
    │       ├── advanced.mdx
    │       └── contributing.mdx
    └── sockdotnet/
        ├── _meta.json
        ├── theme.config.tsx
        ├── index.mdx
        ├── getting-started/
        │   ├── install.mdx
        │   ├── features.mdx
        │   └── examples.mdx
        └── usage/
            ├── basics.mdx
            ├── advanced.mdx
            └── contributing.mdx