Connection Configuration

Once your Git Connection is set up, all changes made in the ReadMe editor automatically sync to your Git repository, and vice versa. When editing documentation in Git, you can use your preferred code editor or Git tools. This guide covers the components required to enable a seamless connection between ReadMe and your Git tooling.

Documentation Structure

To ensure successful syncing from Git to ReadMe, follow these structure guidelines:

Markdown Files

• Files must include required frontmatter: title and summary
• Content should be written in standard Markdown format
• File names must match the intended URL slug for proper routing

Navigation

• Page order is defined using _order.yaml files
• Each category folder can have its’ own order.yaml
• Navigation structure in Git, mirrors your ReadMe project hierarchy

Branches

• The initial commit from ReadMe is to establish branch synchronization with Git
• Branch names must exactly match the version names defined in ReadMe
• Any mismatched version and names will exist in Git and will not sync with ReadMe.

ReadMe: v2.0_new-branch
GitHub: v2-new-branch
		

ReadMe: v2.0_new-branch
GitHub: v2.0_new-branch
		

Handle Conflicts

When a conflict is detected while saving in ReadMe, the system will immediately prompt you to Overwrite Git changes or Cancel the save and continue editing. Changes saved in ReadMe, will always match what goes live.

When merging from GitHub, the user can resolve conflicts via the GitHub editor or the merge tool of their choice locally before pushing.

Sync Multiple Versions

When you first connect your repository, only the main version of your code syncs. Once bi-directional sync is established, any changes to other versions will trigger them to sync as well. For example, if version 2 is your main version, only version 2 syncs initially — version 1 will only sync once you make changes to it after the connection is established.