Skip to content
Jotly

Git Sync

Git Sync connects a docs site to a folder in a GitHub repository. Each published page is a Markdown file, so your docs get pull requests, history and review like the rest of your code, and writers can still use the editor.

It needs the Pro plan, and only owners and admins can set it up.

Connect a repository

  1. Open Docs, then the Git Sync tab, and press Connect GitHub.
  2. Install the Jotly GitHub app on your account or organization. Jotly confirms that you really have access to that installation before it links it.
  3. Pick the repository, the branch and the folder (docs by default; leave it empty for the repository root).
  4. Press Start sync. If the folder already has .md files Jotly imports them. If it is empty, Jotly exports your published pages.

Disconnect stops the sync and leaves your pages and your files exactly where they are.

Repository layout

Every published page is one file, and the folder tree follows the page slug. Only .md files and jotly.json are read; anything else in the folder is ignored.

docs/  jotly.json  introduction.md  guides/    webhooks.md    api-keys.md

The page guides/webhooks lives in docs/guides/webhooks.md. Drafts are not exported.

Frontmatter

The keys Jotly reads are title, description, icon and sidebarTitle (the shorter name shown in the menu). Any other key, such as noindex, is kept and written back untouched.

docs/guides/webhooks.md
---title: Webhooksdescription: Receive events in your own server.icon: webhooksidebarTitle: Webhooks---Jotly signs every event with an HMAC header...

Components such as callouts, tabs, steps and cards are written as MDX in the .md file, in the Mintlify-style subset. Conditional blocks are written as <Conditional rule='...'>.

Navigation

The menu lives in jotly.json. navigation is an ordered list, and every item is exactly one of these:

  • { "page": "guides/webhooks" }: a page by its slug. Add "hidden": true to take it out of the menu while it is still served.
  • { "group": "Guides", "items": [ ... ] }: a group, which can nest and take icon, expanded and hidden.
  • { "link": "Status", "href": "https://status.acme.com" }: an external link.
  • { "tab": "API", "slug": "api", "items": [ ... ] }: a top-level section. If there is one tab, every top-level item must be a tab.
docs/jotly.json
{  "version": 1,  "navigation": [    { "page": "introduction" },    {      "group": "Guides",      "items": [        { "page": "guides/webhooks" },        { "page": "guides/api-keys" }      ]    },    { "link": "Status", "href": "https://status.acme.com" }  ]}

How the sync works

From Jotly to the repository

Every publish, unpublish, delete or move makes one atomic commit on your branch. The commit is authored by the Jotly Docs Sync app and co-authored with the name and email of the person who made the change.

From the repository to Jotly

A push to the branch sends a signed webhook. Jotly imports the changed .md files, creates or updates the page, publishes it and keeps the previous version in the page history. Deleting a file unpublishes the page; it never deletes it. A change to jotly.json rewrites the navigation.

Sync now and conflicts

Sync now works in both directions: it pulls what changed in the repository since the last sync, then pushes what changed in Jotly. After a force-push it reconciles the whole folder. An hourly job does the same for every connection in case a webhook was missed.

If a page changed on both sides, the newer change wins and the other version stays in the page history. The Git Sync tab shows a summary of the last sync and any conflicts.

Limits

  • Up to 2,000 .md files per folder. Past that, the sync stops with a clear error.
  • Files over 1 MB are skipped.
  • If GitHub rate-limits the sync, the tab shows the error and the next run tries again.

The page menu can show Edit on GitHub, which opens the page's file in your repository.

See also Docs portal