Import from GitHub and keep in sync

Point Markdrop Guides at a GitHub repository and it copies the docs in it into a guide: every page, the sidebar, images and files, and old addresses. Turn on Keep in sync and every push to the branch updates the guide. Markdrop only reads your repository: it never commits or changes anything there.

Markdrop Guides works out the format from the folder's files. You can also choose it yourself under Format.

For a format with a config file, choose the folder that holds the config (like website for a Docusaurus site in website/). Markdrop finds the pages from there.

Each format's own blocks become the guide's blocks:

Anything without a match keeps its text, and the import report lists it under Blocks converted approximately.

Public repositories import without connecting anything. To import a private repository, or to keep a guide in sync, install the Markdrop Guides GitHub app on the repositories you choose.

The app asks for two read-only permissions:

• Contents: read-only, to download the docs at each push.
• Metadata: read-only, which every GitHub app has, to list the repositories you chose.

It gets no write access, so it can't commit, open pull requests or change settings. GitHub tells the app when you push, which is how a sync starts.

1. 1

   Choose Connect GitHub

   #Copy sectionAsk about this

   On New guide (or a guide's Settings › GitHub), choose Connect GitHub. You need to be a Guides admin of the workspace.

2. 2

   Install the app on GitHub

   #Copy sectionAsk about this

   Pick the account or organisation and the repositories the app can read. Only an owner of an organisation can install apps on it; GitHub can send them a request.

3. 3

   Come back to Markdrop

   #Copy sectionAsk about this

   GitHub sends you back to Markdrop Guides, which checks with GitHub that your account can open that installation and connects it to the workspace. Guides admins of the workspace can then import from its repositories.

The app is already installed on the account? Choose Already installed? Link it instead. To stop Markdrop reading an account, remove the app on GitHub (Settings › Applications), or change which repositories it can read there.

1. 1

   Start a new guide

   #Copy sectionAsk about this

   Choose New guide, pick where it lives, and under How do you want to start? choose Import from GitHub.

2. 2

   Pick the repository

   #Copy sectionAsk about this

   Under Your repositories, choose a repository the app can read. For a public repository without the app, choose Public repository and paste its address, like https://github.com/acme/docs. A link to a folder (…/tree/main/docs) opens that folder.

3. 3

   Choose the branch and folder

   #Copy sectionAsk about this

   The Branch starts at the default branch. Folder suggests the folders that hold docs; choose Other folder… to type another. The detected Format shows beside it.

4. 4

   Check what comes across

   #Copy sectionAsk about this

   The preview shows how many pages the folder has and the sidebar groups the guide will get, with anything worth knowing, like an OpenAPI file it found.

5. 5

   Choose what pushes do

   #Copy sectionAsk about this

   Turn on Keep in sync and choose Update drafts (each push updates the drafts; you publish when ready) or Publish automatically (each push is published after it syncs). Then name the guide and choose Import.

The import screen shows four steps: downloading the repository, converting pages, copying images and files, and saving as drafts. You can close it: the import keeps running. When it's done, check what Needs a look before you publish, as for a GitBook import. Nothing is public until you publish.

If the repository has an OpenAPI file (a Mintlify site's openapi setting, or a file named openapi.yaml), the import screen and Settings › GitHub offer Use as API reference. See API reference.

With Keep in sync on, every push to the branch that changes something in the folder updates the guide, usually within a minute or two:

• Changed files update their pages. Each sync is a new version in the page's history, so nothing is lost.
• New files become new pages, in the place the sidebar config gives them.
• Removed files remove their pages.
• A renamed or moved file keeps its page and history when its text stays mostly the same (as Git judges a rename), and the old address redirects to the new one once it was published. The same goes for a page whose address changes because of its front matter (a new slug, say).
• The same file is always the same page, so a sync never makes duplicates, and a page whose file didn't change isn't touched.
• Update drafts: the changes wait as drafts, like an edit in the editor. Publish automatically: the guide is published after the sync, as the person who connected the repository. Publishing counts toward the daily publish limit.

Pushes to other branches, and pushes that change nothing in the folder, are ignored. A guide syncs at most 50 times a day.

GitHub is the source of truth for the pages it brought:

• A page from GitHub shows This page comes from GitHub with its repository and file, and Edit on GitHub. You can still edit it here, but the next push that syncs replaces your edit (the page's history keeps it).

• Pages you add in the editor stay yours: a sync never changes or removes them, and keeps them in the sidebar where you put them. A file whose address belongs to one of your pages is left out of the sync, and the sync history says so.
• Design, settings, the changelog and the guide's domains are yours too: a sync only changes pages and the sidebar.

A connected guide's Settings › GitHub shows the repository, branch and folder, the last commit it synced and when, and:

• Sync now, to sync the latest commit without waiting for a push. Editors and admins can use it.
• Keep in sync and what pushes do (Update drafts or Publish automatically), the branch and the format. Admins can change them.
• Sync history: each sync with what started it (the first import, a push and who pushed, or Sync now), the commit, how many pages were added, updated and removed, and any problem.
• Disconnect: syncing stops, and the pages stay in the guide as ordinary pages you edit here.

To connect a guide you made another way, open Settings › GitHub, choose the repository and folder, and choose Connect. The first sync takes over pages at the same addresses, so a guide's home page becomes the repository's.

A public repository can be imported once without installing anything. It can't stay in sync, because GitHub only tells Markdrop about pushes to repositories the app is installed on. Sync now in Settings › GitHub still brings in the latest commit whenever you choose. GitHub limits how often a repository can be read without the app; if you see GitHub asked us to slow down, wait a few minutes or connect GitHub.