Editing with Bi-Directional Sync
Learn how to manage content, handle conflicts, and maintain consistency across platforms.
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
Ready to start editing with bi-directional sync? Whether you're making quick updates in ReadMe's intuitive editor or pushing changes through Git, bi-directional sync keeps everything in perfect harmony. Your edits in ReadMe automatically flow to your GitHub repository, and any changes you commit to GitHub appear right in your ReadMe hub. Don't worry about version conflicts or maintaining multiple copies – bi-directional sync handles the heavy lifting, so you can focus on creating great documentation wherever you prefer to work.
Setting Up Bi-Directional Sync
Prerequisites
- Your project must be enabled for the new editing UI.
- You must have a GitHub account and an empty private repository.
Important Note
External repositories connected to your project must be empty on initial sync.
Initial Configuration
- Go to Settings > Git Connection in your ReadMe project settings.
- Create a new empty private repository in your GitHub account.
- Click Sync with GitHub in ReadMe.
- Authenticate with GitHub when prompted.
- Select the repositories you want ReadMe to access (including your new repo).
- Choose your project and click Sync Repository.
Documentation Structure
Project structure
Each ReadMe project will be equivalent to a GitHub repository. See the diagram below:
File Organization
The bi-directional sync feature offers a format that closely mirrors the well-organized ReadMe project structure. With folders neatly organizing your documentation and markdown files serving as individual pages, it creates a user-friendly experience that will feel instantly familiar to ReadMe users.
Your documentation follows this standardized structure:
📂 project
├── 📁 guides
│ ├── 📂 category-folder
│ │ ├── 📄 page.md
│ │ └── 📃 sidebar.yml
│ └── 📃 sidebar.yml
├── 📁 recipes
├── 📁 custompages
└── 📁 references
Each component serves a specific purpose:
guides
: Contains your main documentation content, organized in categories.recipes
: Holds step-by-step tutorials and how-to guides.custompages
: Stores any custom pages you've created.references
: Contains API reference documentation.sidebar.yml
: Manages the navigation structure for each section.
This organization mirrors your ReadMe project structure, making it easy to maintain consistency between your Git repository and ReadMe documentation.
File Format
Documentation pages use Markdown with front matter metadata:
---
title: List all owls
api:
file: hoot.json
operationId: get_owls
hidden: false
metadata:
title: My SEO Title
description: A brief description for SEO
keywords:
- keyword1
- keyword2
---
# Main Content
Your documentation content goes here...
Guides Structure
Page order and navigation are controlled by _order.yml
files:
- welcome-page
- getting-started
- advanced-topics
- feature-one
- feature-two
API Reference Navigation Structure
Code Example
- reference:
- Owl Sanctuary API:
- owls:
- postowls
- index
- getsightings
- getowlsid
- getowls
- habitats:
- index
- gethabitats
Image Example
This is after uploading a sample OAS file, hoot.json. The above matches the following sidebar:
Editing in ReadMe
Making Changes
- Navigate to the page you want to edit in ReadMe.
- Make your changes using the ReadMe editor.
- Save your changes.
- Changes will automatically sync to your Git repository.
Handling Conflicts
When conflicts occur during saving:
- ReadMe will display a conflict notification.
- You can choose to:
- Overwrite the changes in Git.
- Cancel the save and incorporate Git changes first.
- Review the changes carefully before deciding.
Editing in Git
When editing documentation in Git, you can use your preferred code editor or Git tools. The bi-directional sync feature will detect changes made to your Git repository and automatically update your ReadMe documentation.
Content Structure
-
Markdown Files:
- Files must include required frontmatter (title, summary)
- Content follows standard Markdown format.
- File names should match the intended URL slug.
-
Navigation:
- Page order is controlled by
sidebar.yml
files. - Each category folder can have its own
sidebar.yml
- Navigation structure mirrors your ReadMe project.
- Page order is controlled by
Managing Versions
Version Control with Git
- Each documentation version corresponds to a Git branch.
- The default branch represents your main version
- Create new branches for major versions:
git checkout -b v2.0
Version Settings
Version-specific settings like public/deprecated status are managed in ReadMe's interface, not in Git.
Conflict Resolution
Handling Conflicts in ReadMe
When a conflict is detected while saving in ReadMe, the system will:
- Display a conflict notification indicating changes were made in another session
- Present you with two options:
- Overwrite the changes in Git
- Cancel the save and continue editing
This gives you the chance to check for changes made in Git and incorporate those changes manually in the ReadMe editor before saving again.
Handling Conflicts Outside ReadMe
Users who run into conflicts will be able to resolve those conflicts using their preferred tool:
- Manually in a code editor
- Tools offered by their Git service
- Other preferred conflict resolution methods
Branch Synchronization
When working with branches across ReadMe and GitHub, there are some important synchronization behaviors to understand:
Creating Branches in ReadMe
- The initial commit in ReadMe is required to establish the branch synchronization with GitHub.
Creating Branches in GitHub
- If you create a branch in GitHub, you must create a corresponding version in ReadMe with the same name.
- While the branch exists in GitHub, ReadMe won't recognize it until you create the matching version in the ReadMe interface.
Synchronizing Branch Content
- After the initial ReadMe change, all content from both GitHub and ReadMe will be synchronized (assuming there aren't any conflicts).
Working with GitHub Branch Protection
If your GitHub repository uses branch protection rules, you'll need to configure them to allow the ReadMe Sync app to push changes. Here's how to set it up based on your GitHub configuration:
For GitHub Rulesets (New Version)
- Navigate to your repository's branch protection settings.
- Look for the Bypass list section.
- Click + Add bypass.
- Search for "ReadMe Sync" (App • readmeio).
- Set the permission to Always allow.
For Legacy Branch Protection
- Go to your repository's branch protection rules.
- Find the Allow specified actors to bypass required pull requests section.
- Click the search box.
- Add "readme-sync" (ReadMe Sync) to the allowed actors list.
This configuration ensures that changes made in ReadMe's editor can be synchronized to protected branches in your GitHub repository.
Updated 6 days ago