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

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.
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.
Choose the Docs repository and the Deploy branch, the branch Mintlify deploys from. It is usually the default branch. Click Continue.
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.
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).
Optionally enter your Docs site URL, so each document links to its live page.
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

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.”
Optionally set the page’s Description and Sidebar title.
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.
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.