Allowing README creation in GitBook UI conflicts with default GitHub integration

[marmarmo]

Bug description

Creating a README file via the GitBook UI editor leads to serious issues in GitBook-integrated GitHub repositories, including:

• Repo-breaking behavior
• Duplicate README files
• Confusion around which file takes rendering precedence
• Loss of documentation with overwrites

Although this is referenced in GitBook documentation, the consequences are not clearly communicated, and the UI still allows users to create a README, which can have destructive effects.

This often results in broken builds, rendering conflicts, or overwritten content — especially for contributors working in hybrid GitHub + GitBook workflows.

Screenshot of an attempted removal of a duplicate README.md. To fully resolve the conflict, the GitBook space had to be hard reset to remove duplicated instances.

How to reproduce

1. Open a space in the GitBook UI (within the app, not within the repo)
2. Click “Add file”
3. Name it README, Readme, or readme

Expected: The UI prevents or warns users from creating a reserved file like README.md when Git sync is enabled.
Actual: The UI allows it without warning, resulting in potential duplication, rendering issues, or overwriting of an existing GitHub README.md.

Additional context

• This is a common pitfall in GitHub-synced projects
• Mentioned vaguely in GitBook Git Sync Configuration

This states:

• readme: Your documentation’s first page. Its default value is ./README.md

• The default behavior treats README.md as special. Allowing users to create an additional README from the UI risks unexpected overrides or UI instability.

Could be avoided by:

• Disabling README file creation in the UI
• Displaying a tooltip/warning: “Creating a README here may overwrite your GitHub README.md and break repo integration.”

[addisonschultz]

Hi @marmarmo - good suggestions. If you’re working with a hybrid-workflow as you’ve described, I would first make sure you have a bit more configuration set up - mainly the structure defined in the .gitbook.yaml file: https://gitbook.com/docs/getting-started/git-sync/content-configuration#structure

This allows you to define a root level readme and define the structure of other pages.

The steps you defined to replicate the bug shouldn’t happen if you have a readme defined in the structure - can you let me know if that isn’t working?

[marmarmo]

Thanks for the reply @addisonschultz!

Yes, I did see that doc and actually linked it in the original bug report. My main concern is less about configuring the .gitbook.yaml correctly and more about why the UI allows a README to be created at all, especially when doing so—without prior configuration—can lead to structural issues or duplication in GitHub-integrated projects.

If the UI simply included a tooltip, modal, or even a link to the Git Sync structure documentation when attempting to create a file named README, it could really help prevent these types of issues before they happen.

I totally get that this may straddle the line between a bug and a UX enhancement — happy to move it to a feature request if that’s more appropriate!