Monorepos

Use Git Sync with monorepos and map spaces to separate directories

Use site-wide Git Sync to sync multiple spaces from one repository and branch. Map each space to its own directory in gitbook-docs.yaml.

How site-wide Git Sync works

The site’s Project directory sets the Git Sync installation directory. gitbook-docs.yaml lives there. If you leave it empty, GitBook uses the repository root.

In gitbook-docs.yaml, each space has a content.directory. That directory contains the space’s .gitbook.yaml, README.md, SUMMARY.md, and content files.

For an overview of these files, see Content configuration.

Map spaces to directories

Use Content mapping in the Git Sync panel to map each space. GitBook saves the mapping in gitbook-docs.yaml.

Directory paths work as follows:

Path	Meaning
./docs	A directory inside the site’s Project directory.
/docs	A directory from the repository root.
docs	The same as ./docs.

For example, this repository maps three spaces:

/
  gitbook-docs.yaml
  documentation/
    .gitbook.yaml
    README.md
    SUMMARY.md
    .gitbook/
      assets/
        logo.png
  developers/
    .gitbook.yaml
    README.md
    SUMMARY.md
  changelog/
    .gitbook.yaml
    README.md
    SUMMARY.md

This gitbook-docs.yaml maps each space to its directory:

gitbook-docs.yaml

$schema: https://api.gitbook.com/gitbook-docs.yaml
site:
  structure:
    - type: space
      key: documentation
      title: Documentation
      path: documentation
      content:
        directory: ./documentation
    - type: space
      key: developers
      title: Developers
      path: developers
      content:
        directory: ./developers
    - type: space
      key: changelog
      title: Changelog
      path: changelog
      content:
        directory: ./changelog

Keep space content self-contained

Each space only syncs the directory assigned to it. GitBook doesn’t automatically share content or assets between mapped directories.

Keep every referenced asset inside its space’s mapped directory. If several spaces need an asset, add a copy to each directory or reorganize the repository.

The .gitbook.yaml root setting controls where GitBook reads content within that space’s mapped directory. It doesn’t make sibling directories available.

Move a mapped directory

Move a space’s content by updating its files and mapping together:

1. In the repository, move the space’s content files and assets.
2. In gitbook-docs.yaml, update that space’s content.directory. Leave its key unchanged.
3. Commit both changes in the same commit.

If GitBook imports before both changes exist, the mapped space can appear empty.

Don’t rename the key to match the new directory. Keys and directory names are independent. Changing a space’s key replaces the space with a new one that has a new space ID, and restoring the original key doesn’t bring the old ID back. See Keys identify your spaces.

Keys generated by GitBook — space-1, space-2 — don’t reflect directory names, and there’s no benefit to keeping the two aligned.

Use individual space Git Sync

Use individual space Git Sync when a space needs another repository or branch. For example, use it when a private space must sync separately.

Remove the space from the site’s content mapping first. Then configure Git Sync from that space.

To configure the space, follow Enabling GitHub Sync or Enabling GitLab Sync. In the scope step, select Space Git Sync.