# How to connect Mintlify and publish to it

Mintlify publishes whatever is in the GitHub repository it deploys from. Workover works with that same repository: it imports your pages from it, and publishing a page from Workover is a commit to it, either through a pull request or straight to the branch Mintlify deploys. This page covers connecting a project to your Mintlify docs, editing pages and publishing them back.

**Before you start:**

- Your docs must be in a GitHub repository you own. If they are still in a repository Mintlify hosts for you, clone them to your own GitHub first; Mintlify’s settings have a Git section for this. GitHub is the only code host supported for Mintlify.
- The Workover GitHub app must be installed on the account that owns the repository, with access to it. Publishing writes to the repository, so approve the app’s write permission when GitHub asks.
- Publishing needs an active plan or trial on your workspace.

## Connect a project to Mintlify

1. Create a project: choose **Website**, enter your docs site’s address in **Website link**, pick **Mintlify** as the CMS and click **Connect to Mintlify**. For an existing project that isn’t connected to a site, open **Project settings** and click **Connect to Mintlify** in the **Mintlify** card.
2. If your workspace hasn’t connected GitHub yet, click **Connect GitHub** and install the Workover GitHub app. When GitHub sends you back to Workover, open the project’s **Project settings** and click **Connect to Mintlify** in the **Mintlify** card again. Setup continues from choosing the repository.
3. Choose the **Docs repository** and the **Deploy branch**, the branch Mintlify deploys from. It is usually the default branch. Click **Continue**.
4. Workover looks for your `docs.json` (or an older `mint.json`), including in a subfolder of a larger repository. If it finds more than one docs site, choose one under **Docs site**.
5. Under **When someone publishes**, choose **Open a pull request** (the change goes live when the pull request is merged) or **Publish straight to *branch*** (Mintlify deploys it immediately).
6. Optionally enter your **Docs site URL**, so each document links to its live page.
7. Click **Import pages**.

Workover imports every page listed in your site’s navigation and tells you what it skipped: navigation entries with no page file of their own (usually API reference pages generated from an OpenAPI file) and any page it could not read. Files that are not in the navigation, such as snippets and hidden pages, are not imported. An import stops at 1,000 pages.

To change the repository, branch or publishing mode later, open **Project settings** and click **Change repository or settings** in the **Mintlify** card.

## Edit a page

Write as you would anywhere in Workover. Mintlify components appear in the editor as components, each with an **Edit** button for its settings, and components that hold a list, such as steps or tabs, have a button to add another item.

To insert a component, type **/** and pick it from the menu: callouts, a card, a card grid, steps, tabs, accordions, a code group, an update, API parameter and response fields, an expandable, a file tree, a panel or a prompt.

Anything Workover does not model, such as your own custom components, imports, raw HTML and `{expressions}`, is kept exactly as it is and shown as a locked block, so publishing never changes it.

## Publish a page

1. Open the document and click the **Mintlify** tab in the editor’s side panel. It shows the repository and what publishing does: “Publishing opens a pull request, and merging it goes live.” or “Publishing commits to *branch*, and Mintlify deploys it straight away.”
2. Optionally set the page’s **Description** and **Sidebar title**.
3. For a document that is not a Mintlify page yet, enter its **Page path**, such as `guides/getting-started`, and choose its **Sidebar group**. Workover adds the page to your `docs.json` in the same commit.
4. Click the publish button. It reads **Open pull request** (or **Update pull request** when one is already open) in pull request mode, and **Publish to Mintlify** in direct mode.

> **Warning:** In direct mode, publishing commits straight to your deploy branch and Mintlify deploys it at once, with no review step. Use pull request mode if changes need a review first.

When it finishes, the tab says **Pull request ready.** with a **Review it on GitHub** link, or **Published. Mintlify is deploying it now.** While a pull request is open, the tab shows **Pull request open, waiting to be merged**. Images you added in Workover are committed to your repository, under `images/workover/` in your docs folder, in the same change. Images that came from your repository keep their original paths.

The publish button stays unavailable while the document has pending suggestions, and the tab asks you to review them first.

## If the page changed in Mintlify

If someone changed the page in Mintlify or in the repository since your last sync, publishing stops and asks first:

- **Pull Mintlify’s version first** asks **Pull the latest version from Mintlify?**. Clicking **Pull latest** replaces the document here with the page on your deploy branch, discarding changes you have not published.
- **Publish anyway, overwriting** publishes your version over theirs.
- **Cancel** publishes nothing.

> **Warning:** **Publish anyway, overwriting** replaces the changes made in Mintlify. In pull request mode you can still review the pull request before merging it; in direct mode the change goes live immediately.

If the page was moved or deleted on the deploy branch, the tab says so, and publishing would create it again at its old path.

To bring a published page’s latest version into Workover at any time, click **Pull from Mintlify** in the tab.

## Bring in later changes

Click **Sync from Mintlify** in the project’s toolbar to import new pages and refresh the others. A page that someone has already opened in Workover keeps its body, so your edits are never overwritten; only its title is refreshed. Pages nobody has opened are refreshed in full.

## Limits and errors

- **GitHub only.** GitLab and Bitbucket are not supported for Mintlify.
- **Split navigation.** If your navigation is split across files with `$ref`, a new page can only go in a group defined in `docs.json` itself. For other groups, Workover asks you to add the page to that file by hand.
- **Renaming, moving and deleting pages** happens in your repository or in Mintlify, not in Workover.
- **Protected branches.** Direct mode cannot commit to a protected branch. If GitHub refuses the update, switch the project to pull requests in **Change repository or settings**.
- **“Workover’s GitHub app needs permission to write to your docs repository.”** Approve the app’s updated permissions in GitHub, then publish again.
- **“GitHub refused access to the docs repository.”** Check that the Workover app is installed on the account that owns the repository and has access to it.

## Related

- [GitHub](/docs/github-integration/)
- [Integrations overview](/docs/integrations-overview/)
- [How to connect Webflow and publish to it](/docs/publishing-to-webflow/)