# Sync

> How changes move between Typemark and GitHub, what happens when edits collide, and what gets synced.

Once your project is connected to GitHub, changes flow both ways. Save in Typemark and the commit lands on GitHub. Push to GitHub and your site rebuilds.

## How sync works

<Tabs>
  <Tab title="Typemark to GitHub">
    When you save a page in the editor:

    1. Typemark commits the change with you as the author.
    2. Typemark pushes the commit to your deployment branch on GitHub, or to the branch you're on if you're working on a [branch in the editor](https://docs.typemark.dev/editor/branches). If GitHub has commits Typemark doesn't have yet, Typemark pulls them in and pushes again.
    3. In auto-deploy mode, the page goes live as soon as it compiles. It doesn't wait for the round trip through GitHub.
  </Tab>
  <Tab title="GitHub to Typemark">
    When you push to your deployment branch from your editor, the terminal, or CI:

    1. GitHub notifies Typemark.
    2. Typemark pulls the latest commits.
    3. Typemark rebuilds the site, recompiling only the files that changed.
    4. Your site and search index update when the build finishes.
  </Tab>
</Tabs>

Image uploads and settings changes made in Typemark are committed and pushed to GitHub too.

## Deployment branch

Only pushes to the deployment branch rebuild your live site. Pushes to other branches never change it, so you can draft on a feature branch and merge when it's ready. On Pro and Enterprise, two kinds of branches get a site of their own:

- A pull request into the deployment branch gets a [preview](https://docs.typemark.dev/github/previews), rebuilt on every push to it.
- A [branch you create in the editor](https://docs.typemark.dev/editor/branches) is pushed to GitHub under the same name. Commits pushed to it on GitHub are picked up when its preview next builds.

When the owner changes the deployment branch, sync follows the new branch. See [Branches](https://docs.typemark.dev/github/branches).

## When edits collide

Typemark checks every save against the version of the page you opened. If the page changed in the meantime, because someone pushed to GitHub or a teammate saved it, your save is stopped and you see **Page was modified**:

- **Reload page** loads the latest version. Your unsaved changes are lost, so copy anything you want to keep first.
- **Keep editing** closes the dialog and leaves your changes in the editor.

There's no automatic merge.

If Typemark can't pull your GitHub changes, for example because of a merge conflict, the deployment fails and your live site keeps serving the last build. The error shows on your project's overview page.

## Manual deploy and GitHub

[Manual deploy](https://docs.typemark.dev/configuration/publishing#manual-deploy) holds back edits saved in the Typemark editor. Pushes to GitHub rebuild the site and publish the pages they change right away.

## What syncs

| Content | Synced with GitHub |
|---------|--------------------|
| Pages (`.mdx` and `.md`) | Yes |
| `typemark.json` | Yes |
| Images and other files in the repo | Yes |
| Commit history | Yes |
| Site status, deploy mode, and custom domain | No, these are project settings in Typemark |
| Team members and roles | No |

## Files Typemark doesn't use

Your repository can hold more than docs: application code next to a `docs` folder, a README, a license, CI workflows. Typemark only uses the files a docs site needs:

- `typemark.json` at the repository root
- pages: `.mdx` and `.md`
- `.json`, `.yaml` and `.yml` files, such as OpenAPI specs
- images, video, audio, fonts and PDFs: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.svg`, `.ico`, `.bmp`, `.mp4`, `.webm`, `.mp3`, `.wav`, `.woff`, `.woff2`, `.ttf`, `.otf` and `.pdf`, in upper or lower case

With a [`docs_root`](https://docs.typemark.dev/configuration/typemark-json#docs_root), only those files inside that folder count, plus the `images` folder at the root, where editor uploads go, and files `typemark.json` points to, such as your logo or an OpenAPI spec. Files in folders whose names start with a dot, such as `.github`, and files like `.gitignore` are never used.

Typemark ignores everything else. Ignored files stay in your repository and its history, and saves in Typemark never change or delete them, but they aren't part of your site. Each publish on your project's overview lists the files it ignored, and so does the import summary when you import a site. It's a warning, not an error: your site still builds.
