Better Monorepo support (multiple spaces in a single repo & branch)

[jalaziz]

What's your feature/idea?

GitBook should support a configurable path to the .gitbook.yaml file, allowing it to exist in subdirectories of the repo.

One of our biggest issues with GitBook is the single space per repo/branch limitation. We use a monorepo and one of the main reasons for doing so is being able to update related components in a single commit. In fact, we regularly run into issue where people forget to update docs in the same commit they make changes in, resulting in inconsistencies for our customers.

What's your desired outcome?

If the path to the .gitbook.yaml was configurable, then it would theoretically be possible to have multiple spaces reside in the same repo and on the same branch.

This has several benefits:

1. Documentation changes can be in the same commit as component changes.
2. Avoids branch or repo mania when dealing with many spaces.
3. Documentation can live close to the components in a monorepo containing multiple components.
4. Documentation can be versioned alongside other related changes!
5. Documentation updates can follow the same branching conventions and release workflows that we (and likely others) have.

What's the impact of this for you?

• Critical
• High
• Medium
• Low

Anything else?

Using separate branches or submodules don't help here because you still end up with the single commit problem. It also becomes much trickier to version cohesively, especially when changes move between environments.

[SamyPesse]

Thank you for the feedback!

We just released a solution that should fit your needs 🎉 You can now configure a "Project directory" when configuring the GitSync. Learn more about it in our documentation.

This option can be used to synchronize one repository with multiple spaces.

Keep in mind that this feature is brand new, so let us know if you have any feedback or if you observe any issues.

(If you don't see the option when configuring the GitSync, hard-refresh your page to clear your browser's cache).

[jalaziz]

Holy cow that was quick! Thank you so much!!! ❤️

Will test it shortly (after meetings 😂)

[cafferata]

There is a .gitbook.yaml reference missing in the code example.

/
  package.json
  packages/
     styleguide/
        .gitbook.yaml
        README.md
        SUMMARY.md
     app/
+       .gitbook.yaml
        README.md
        SUMMARY.md
     api/
        .gitbook.yaml
        README.md
        SUMMARY.md

[SamyPesse]

@cafferata It's done on purpose. The .gitbook.yaml file is optional; if you don't have one, GitBook will use the README.md and SUMMARY.md or lookup all markdown files under this directory.

[jalaziz]

Did some basic testing and it works great so far! Changes were picked up from and synced to the correct directory <3.

Through the testing, I did run into a separate issue which prompted this feature request: #69