maxsuite Diagrams

Doc sync

Doc sync

Doc sync binds a project's documentation to a GitHub repository. It pulls the repository's Markdown files into the project's page tree, and writes the project's navigation file back. Teams that keep their docs beside their code in Git use it so Pages shows what the repository holds.

In the sidebar under Files → Doc sync. Needs: Pages, Projects.

Doc sync screen

  • Git Synchronization: the projects bound to a repository, with a picker when there are several. For the chosen project you see its repository, branch and docs path. The buttons are ↓ Pull from Git, ↑ Publish navigation, Edit binding, Set up webhook (or Rotate webhook), Connect another and Unbind.
  • No binding yet: "No project is bound to a repository", with Connect a repository.
  • GitHub App: whether a GitHub App is configured for the workspace, with its name and client id, or a note that it is not.
  • Sync History: every pull and push, with its direction (Pull or Push), its status, the commit, a message and when it happened. The table has a search box and filters.

Bind a project to a repository

  1. Open Files → Doc sync and click Connect a repository.
  2. Choose the Project.
  3. Enter the Repository as owner/name, the Branch (main if left blank) and the Docs path, the folder inside the repository that holds the documentation. Blank means the repository root. A path with .. in it is refused.
  4. Paste an Access token if the repository is reached with a token rather than through the GitHub App. It is encrypted and never shown again.
  5. Save. Edit binding changes these later. Unbind removes the binding and its stored token; pages already pulled stay.

Pull the docs in

Click ↓ Pull from Git. MaxSuite reads every Markdown file under the docs path at the tip of the branch and works out the page tree:

  • README.md or index.md is a folder's landing page (README.md wins when there are both), and the pages in that folder sit under it;
  • a page's title comes from its frontmatter, then the navigation file, then its first heading, then its file name;
  • order comes from frontmatter, then the navigation file, then the title;
  • a repository moved from GitBook keeps its order and nesting, read from SUMMARY.md and .gitbook.yaml.

A pull changes pages in MaxSuite, never the repository. It overwrites the published text of pages that came from files. Pages whose files are gone from the repository are deleted. Pages written in MaxSuite with no file behind them are left alone.

Pull automatically when the repository changes

  1. Click Set up webhook. A notice shows a webhook address and a signing secret. The secret is shown once.
  2. In the repository's settings at GitHub, add a push webhook with that address, content type application/json, and that secret.

From then on, a push to the bound branch that touches the docs path starts a pull. Pushes to other branches, or that change nothing under the docs path, are ignored. A delivery without a valid signature is refused. Rotate webhook makes a new address and secret, and the old ones stop working.

Write the navigation back

Click ↑ Publish navigation. MaxSuite generates maxdoc.config.yaml from the project's page tree and commits it at the docs root. This is a commit in a repository other people read. Pages themselves are committed one at a time as each is published.

GitHub App

A workspace can reach repositories through a GitHub App instead of per-project tokens. The screen shows whether it is configured. The private key and secrets are never shown.

Who can do what

PermissionLabelLets you
docgit:readView doc syncSee bindings, sync history, the GitHub App status and installations, and the generated navigation file.
docgit:writeManage doc syncBind and unbind repositories, pull, publish the navigation, set up or rotate the webhook, and configure the GitHub App.

See People, roles and permissions.

What happens on its own

Nothing in this module runs on a schedule. Pulls happen when somebody asks, or when the repository's webhook says the docs changed.

What agents can do

An agent can see how a project's docs are bound, read the sync history, preview the navigation file, run a pull or a navigation push, and unbind a repository. Reads run straight away. A pull or a push reaches GitHub, and unbinding cannot be undone, so they wait for a person's approval by default (Agents and approvals).

Read only: docgit.status, docgit.repo, docgit.event, docgit.installations, docgit.generate_nav_config

Reaches GitHub: docgit.pull, docgit.pushNav, docgit.sync

Remove: docgit.unlinkRepo forgets the binding and its stored token. Pages already pulled are kept.

docgit.sync does a pull by default, the same as docgit.pull, or a navigation push the same as docgit.pushNav. docgit.repo and docgit.installations never return the token or the private key. Over MCP the same tools are named docgit__status, docgit__pull and so on. See API keys and MCP access.