Syncing docs with GitHub

Keep your documentation in sync with a GitHub repository. Write docs in markdown, push to GitHub, and Mantle automatically updates your published documentation. Changes you make in Mantle's editor can sync back to GitHub too.

This is useful when your team already writes in markdown, wants version control for documentation, or prefers to manage docs alongside code in a familiar Git workflow.

How it works

GitHub sync connects a repository to your Mantle docs. Once connected:

• Push to GitHub — Mantle detects the change via webhook and updates your docs automatically
• Edit in Mantle — Changes are pushed back to GitHub as commits (in two-way mode)
• Initial sync — When you first connect, Mantle imports all markdown files from your repository

You choose the sync direction: two-way sync keeps both sides in sync, or backup only pushes Mantle changes to GitHub without pulling from it.

Setting up GitHub sync

You'll find GitHub sync in your docs repository settings. Go to Helpdesk > Docs, open your repository, and click the gear icon to access settings.

Step 1: Install the GitHub App

Click Connect on the GitHub Sync card. If you haven't installed the Mantle Docs GitHub App yet, you'll be prompted to install it on your GitHub account or organization.

The GitHub App only requests permission to read and write repository contents — it never accesses your code outside the repositories you explicitly grant access to.

Step 2: Configure the connection

Once the GitHub App is installed, you'll see the setup form:

We recommend creating a dedicated GitHub repository for your documentation rather than putting it inside your application repo. This makes it easier to manage permissions and keeps documentation changes separate from code changes.

Step 3: Connect and sync

Click Connect Repository to save the configuration. Mantle immediately runs an initial sync, importing all markdown files from your repository into your docs.

If your repository is empty, Mantle pushes your existing Mantle docs to GitHub instead — so you can start from either direction.

Repository structure

Mantle uses your repository's folder structure to organize docs into collections, groups, and pages. Your files need three levels of folders before the page file:

{locale}/
  {collection}/
    {group}/
      {page}.md

• Locale (first level) — Must be a locale code matching one of your repository's supported locales (e.g. en, es, fr). Files outside a recognized locale folder are skipped.
• Collection (second level) — A top-level section in your docs (e.g. "Getting started", "FAQ").
• Group (third level) — A sub-section within a collection. Every page must be inside a group folder.

A typical repository might look like this:

en/
  docs/
    getting-started/
      installation.md
      quick-start.md
    faq/
      billing.md
      troubleshooting.md

This creates one collection (docs) with two groups (getting-started and faq), each containing pages. Collection and group names are derived from the folder names.

You can also have multiple collections, each with their own groups:

en/
  guides/
    getting-started/
      installation.md
      quick-start.md
    advanced/
      custom-themes.md
  reference/
    api/
      authentication.md
      endpoints.md

You can check which locales your repository supports in Helpdesk > Docs > your repository > Settings.

Page frontmatter

Each markdown file can include a YAML frontmatter block to control how the page appears in your docs:

---
title: Getting started
description: Learn how to install and configure the app.
slug: getting-started
order: 1
status: published
---

Your page content here...

Collection and group metadata

To set a title, description, or icon for a collection or group folder, add a _index.md file inside it:

---
type: collection
title: Getting started
description: Everything you need to get up and running.
icon: rocket
order: 1
---

Use type: collection for top-level section folders and type: group for sub-group folders. Without a _index.md, the folder name is used as the title.

Sync directions

You can change the sync direction at any time from the management view.

Two-way sync

The default mode. Changes flow in both directions:

• GitHub → Mantle — When you push commits to the connected branch, a webhook triggers an automatic sync. New and updated markdown files are imported into your docs.
• Mantle → GitHub — When you edit a page in Mantle's editor, the change is queued and pushed to GitHub as a commit.

Mantle handles conflicts by comparing timestamps. If a page was edited in Mantle after the last GitHub sync, the local version is preserved during the next pull.

Backup only (push to GitHub)

In this mode, Mantle pushes changes to GitHub but never pulls from it. This is useful when:

• You want a version-controlled backup of your docs
• Your team edits exclusively in Mantle's editor
• You want a Git history of changes without bidirectional sync

Managing your sync

Once connected, click Manage on the GitHub Sync card to see your sync status, recent sync history, and settings.

The management view shows:

• Connection status — Which repository, branch, and whether sync is active
• Last sync — When the most recent sync ran and the latest commit SHA
• Recent syncs — A history of sync runs showing status, trigger type (auto, manual, or initial), and file counts

Click Sync now to manually trigger a sync at any time. This pulls the latest changes from GitHub and pushes any pending Mantle changes.

Disconnecting

To disconnect GitHub sync, click Manage on the GitHub Sync card, then click Disconnect sync. This stops syncing but preserves your existing documentation in both Mantle and GitHub — nothing is deleted.

If you want to fully remove the GitHub App integration, click Uninstall GitHub App in the setup view, and also uninstall the app from your GitHub account settings.

Go further

• Documentation & knowledge base — Overview of Mantle's docs platform
• Using the docs editor — Write and format docs directly in Mantle
• Docs landing page — Configure your docs site homepage