Editing with Bi-Directional Sync

This guide walks through creating and edit documentation when using ReadMe's bi-directional sync feature.

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 frontmatter metadata:

---
title: Your Page Title
summary: A brief description of the page
---

# Main Content

Your documentation content goes here...

Navigation Structure

Page order and navigation are controlled by sidebar.yml files:

- welcome-page
- getting-started
- advanced-topics
  - feature-one
  - feature-two

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.

Webhook Integration

ReadMe uses GitHub webhooks to:

Detect when changes are pushed to your repository
Trigger automatic syncs to update your documentation
Maintain consistency between platforms

Changes made in Git will be automatically reflected in your ReadMe project once they're pushed to your repository.

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

When you create a new branch in ReadMe, it won't be pushed to GitHub until you make your first edit.
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

To properly sync a branch created in GitHub, you need to make at least one change in ReadMe.
After the initial ReadMe change, all content from both GitHub and ReadMe will be synchronized (assuming there aren't any conflicts).