📘

Beta Feature

We're excited to announce that bi-directional sync is currently in beta and will be gradually available to our ReadMe customers! If you’d like to be among the first to try it out, feel free to join our waitlist in the app. We can’t wait to have you on board!

Overview

Our bi-directional sync feature allows you to effortlessly connect your documentation in ReadMe with your Git repositories, empowering your team to work where they thrive. Whether you prefer the intuitive ReadMe editor or your favorite Git workflow, this powerful integration ensures that your documentation is always up-to-date and easily accessible.

What is Bi-Directional Sync?

Bi-directional sync creates a two-way connection between your ReadMe project and a Git repository. When you make changes in either location:

• Changes made in ReadMe are automatically synced to your Git repository.
• Changes pushed to your Git repository are automatically reflected in ReadMe.
• Content stays consistent across both platforms without manual copying or updating.

Key Benefits

• Write Where You Want: Give your team the flexibility to work in their preferred environment - whether that's ReadMe's editor UI or their local development setup.
• Version Control: Leverage Git's powerful version control capabilities for your documentation.
• Automated Syncing: Changes sync automatically between platforms, eliminating manual updates.
• Collaboration: Enable developers, engineers, and technical writers to collaborate seamlessly using familiar tools
• Single Source of Truth: Maintain consistency by having documentation synced across platforms.

How It Works

1. Connection Setup: Install the ReadMe Sync GitHub App in your repository to establish the connection.
2. File Structure: Documentation is organized in a standardized folder structure:

   📂 project
   ├── 📁 guides
   ├── 📁 recipes 
   ├── 📁 custompages
   ├── 📁 references
   └── 📃 sidebar.yml
   

3. Content Format:
   • Documentation pages are stored as Markdown files with frontmatter metadata.
   • Navigation and page order are managed through sidebar.yml files.
   • Content supports both standard Markdown and ReadMe's enhanced features.

Git Integration Details

ReadMe integrates through GitHub Apps to provide:

• Easy installation process
• Transparent permission management
• Granular repository access controls
• Ability to modify or revoke access at any time

Required Permissions

Repository-level access:

• Metadata (Read-only): Required for basic GitHub functionality
• Contents (Read & write): Used to sync documentation content

The integration uses webhooks to:

• Detect changes in either platform
• Trigger sync operations
• Maintain content consistency
• Handle conflict resolution

Versioning Support

Documentation versions are handled through Git branches:

• Default branch represents your main documentation version
• Additional branches can be created for other versions
• Version metadata (public/deprecated status) is managed in ReadMe

Getting Started

To begin using bi-directional sync:

1. Create or select a Git repository for your documentation.
2. Install the ReadMe Sync GitHub App.
3. Connect your ReadMe project to the repository.
4. Start writing documentation in either platform.

For more detailed information about working with bi-directional sync, see our "Editing with Bi-Directional Sync" guide.