Sync documentation from a Forge repository

Docs as code keeps documentation in an Orbit Forge repository, next to the code it describes. Orbit Folio shows that folder as pages in a space, so people read it with the rest of the knowledge base. This page is for people who write in a space.

Edits to synced pages go through a merge request, so documentation is reviewed and versioned like code. The space must belong to a project that has the repository.

Connect a folder

Open the space tools of a space and choose Forge sync. You need to be able to write in the space.
Choose the repository of the space’s project, the branch and the folder. The branch is the main branch by default. The folder is docs by default, and an empty folder field means the whole repository.
Choose where in the page tree the pages should go.
Connect. Folio runs the first sync.

A space can have up to 20 syncs. Each sync is unique by repository, branch and folder.

Folio reads Forge with the session of the person who runs the sync, so Forge decides what can be read. A repository of another project is refused. The pages are therefore visible to the same people who can see the repository.

How files become pages

The layout is the same as for a Markdown import.

Folders become pages. README.md or index.md comes first and gives the folder its text and its title from the first heading.
Front matter gives titles and labels.
Links between files become permanent links between pages.
Images are read from the repository on the branch. Other files of the repository become links to the Forge view.
Hidden names are skipped.

Limit	Value
Syncs per space	20
Files per sync	300
Folders per sync	200
Folder depth	10
File size	Up to 1 MB. Larger files and binary files are skipped and listed.

A sync with more files, folders or levels than this is refused as too large. An empty folder is refused as empty.

Pages managed by Forge

A synced page is marked as managed by Forge. The page tree shows a From Forge icon. The page carries a note, Managed by Forge, with the file path, the branch and the commit.

In Folio	Possible?
Publish, save a draft, restore a version, move, delete	No, these are refused
Comment, react, label and watch	Yes
Propose a change	Yes, see below

Propose a change

Open the synced page and choose Propose a change.
Edit the text. Folio reads the file on the branch with your session, creates a branch named folio/<slug>-<suffix> from the file’s commit, and commits your edit to it.
Folio opens a merge request into the main branch, with a link to the page.
Review and merge it in Forge. See Merge requests and approvals.

The page changes at the next sync after the merge.

When a sync runs

A sync runs when you connect the folder, when you choose Sync now, and when a person who can write opens the space page. For the last case Folio syncs at most once a minute. It first compares the commit of the folder and reads no files if it has not changed.

A push to the branch is therefore picked up at the next sync, not at the moment of the push.

One sync runs at a time. A second request while it runs is refused.

Each sync does everything in one step:

New files become new pages.
A page gets a new version only if its title or text changed. The version note is Synced from <repository>/<folder> on <branch> at <commit>.
Pages follow the order and nesting of the folder.
A file removed from the folder sends its page to the trash. Pages in it that Folio does not manage move to the nearest page that remains.
The activity log gets an entry, synced pages from Forge, with counts.

If Forge returns an error, Folio keeps it and shows it in the dialog.

Disconnect

Disconnect removes the link between the folder and the space. The pages stay in the space as ordinary pages that anyone with edit rights can change.