Coming soon. The Wiki is in active development, so features and these docs may still change. Early adopters: contact us for access.

Mirror spaces

Show the docs of a git repository, or of archives a pipeline uploads, as read-only pages of a space: sources, schedules, webhooks, suggested edits and converting back

1. Overview

A mirror space shows documentation that lives somewhere else as pages of a wiki space: the Markdown or HTML files of a git repository, or archives a person or a build pipeline uploads. The pages follow the source. Each sync creates the pages of new files, updates the pages of changed files and moves the pages of removed files to the trash. Nobody edits a mirror space's pages in the Wiki; they are changed at the source.

Everything around the pages works as in any space: search, comments, reactions, labels, watching, analytics and exports.

A space's Mirror tab: a git source with its last sync, and the sync history
A space's Mirror tab: a git source with its last sync, and the sync history

Mirror spaces need a Pro licence (Licensing) and can be turned off by an administrator. A mirror reads the files of a repository, not a published site: it never crawls GitHub Pages or GitLab Pages, it reads the repository those sites are built from.

2. Creating a mirror space

A space is a mirror space from the moment it is created. Choose New space, then Mirror space under Kind of space, and fill in the name, key and visibility as for any space. The choice is offered to people who may set mirrors up; a normal space can't become a mirror space later.

New space: choosing a mirror space instead of a normal one
New space: choosing a mirror space instead of a normal one

A mirror space has only what a mirror needs: Overview (its pages), Mirror (its sources), Members and Settings. It has no blog, trash, import or templates, since nothing is written in it. A normal space has no Mirror tab.

3. Setting a mirror up

A new mirror space opens on its Mirror tab. A space admin chooses Add a source and fills in where the pages come from.

Set up a mirror: the host, repository, branch, folder, schedule and access token
Set up a mirror: the host, repository, branch, folder, schedule and access token
FieldWhat it means
NameWhat the source is called in the space, such as "Product docs"
Where the pages come fromGit repository (read through its host) or Uploaded archives (a ZIP a person or a pipeline uploads)
HostGitHub, GitLab, Gitea or Forgejo, or Bitbucket Cloud. Host address is for a host of your own (GitHub Enterprise, self-managed GitLab, Gitea, Forgejo)
Repository, Branch, Folderowner/name, the branch to follow, and the folder whose files become pages (empty for the whole repository)
FilesAutomatic reads the kind of file the folder mostly holds: Markdown, or HTML pages when it holds more HTML files than Markdown files (a generated site's repository usually keeps a README or two beside its pages); or choose one. For HTML pages, Content selector names the element that holds a page's content (article.doc, .content); empty tries main and article
Access tokenNeeded for a private repository and for suggested edits. Stored encrypted and never shown again. Give it read access to the repository; for suggested edits, also the right to push branches and open pull or merge requests
ScheduleHow often the branch is checked for new commits: every hour, every 6 hours, every day, or only when asked
Published siteOptional: where the docs are published, for a View on the site link on each page
Let readers suggest editsSee Suggesting an edit. Markdown files on GitHub and GitLab
Put its pages under a page of their ownThe source's pages go under one top-level page named after it. Useful when a space follows several sources

A space can follow up to 20 sources: choose Add a source for the next one.

4. What becomes a page

  • Each folder becomes a page holding its files' pages; a folder's index.md, README.md or _index.md is the folder page's text. Titles come from front matter (title), else the first heading, else the file's name. tags become labels, and images in the source become attachments.
  • The order and titles of a MkDocs nav (mkdocs.yml) and of Docusaurus _category_.json files are followed when pages are first made.
  • Notes and warnings written as !!! note (MkDocs), :::tip (Docusaurus) or > [!NOTE] (GitHub) become panels.
  • HTML pages: the content element is converted to Wiki blocks; scripts, styles and the site's own navigation are left out.
  • Links between files become links between pages.

5. Syncs

A git mirror syncs on its schedule, when someone chooses Sync now, and within seconds of a push when a webhook is set up. A sync only does work when the branch has a new commit. The Mirror tab shows the sync under way and the history: when, what started it, the commit, and how many pages were created, updated and removed. Pause stops a source's syncs until Resume.

6. Webhooks

When a mirror is set up, the Wiki shows a Payload URL and a Secret once. Add a webhook for push events on the git host with both (content type JSON). The Wiki checks every call's signature with the secret, and a push to another branch does nothing. If the secret is lost, New webhook secret makes another; the old one stops working at once.

The webhook's payload URL and secret, shown once after setting a mirror up
The webhook's payload URL and secret, shown once after setting a mirror up

7. Uploading archives

A source set to Uploaded archives takes a ZIP of the docs. Each upload makes the source's pages match the archive. Upload in the Mirror tab (large files are sent in parts and resume after a dropped connection), or from a pipeline with an API token of a space admin:

curl -X PUT \
  -H "Authorization: Bearer $WIKI_TOKEN" \
  -H "Content-Type: application/zip" \
  --data-binary @site.zip \
  "https://wiki.example.com/api/spaces/docs/mirrors/<mirror id>/archive?label=build-42"

label is shown in the sync history. One request takes archives up to 32 MiB; larger ones go through the upload in parts, as the browser does. The mirror's id is in the API's list of the space's mirrors (GET /api/spaces/{key}/mirrors).

8. When a sync would remove many pages

A sync that would remove more than 5 pages and more than a fifth of the source's pages stops and waits: usually a folder was renamed, or the wrong branch or archive was sent. The Mirror tab lists the pages, and a space admin chooses Remove … pages and go on or Cancel sync. Removed pages go to the space's trash and can be restored from there until the trash is emptied. A pipeline that means it can add allowRemovals=true to its upload.

A sync waiting for a yes before it removes pages, with the list of pages
A sync waiting for a yes before it removes pages, with the list of pages

9. Reading a mirrored page

A strip above each mirrored page says which source it comes from, when it was last synced and which file it is, with links to Edit at source on the git host and, when the mirror has a published site, View on the site.

A mirrored page: the strip with its source file, Edit at source and Suggest an edit
A mirrored page: the strip with its source file, Edit at source and Suggest an edit

10. Suggesting an edit

Where a mirror lets readers suggest edits, people who may comment in the space see Suggest an edit on the strip. It opens the page's source text; change it, say what you changed, and the Wiki opens a pull request (GitHub) or merge request (GitLab) on the source that names you. The page changes in the Wiki once the request is merged and the mirror syncs.

Suggest an edit: the page's Markdown source and a line saying what changed
Suggest an edit: the page's Markdown source and a line saying what changed
  • The request is opened with the mirror's access token, so people don't need an account on the git host.
  • If the file changed on the source while you were editing, the Wiki says so; start again from the new text.
  • Each person can open 20 suggestions a day.

11. Converting to a normal space

Convert on the Mirror tab stops mirroring: the space's mirrors are removed, nothing syncs any more, and its pages, with their history, comments and attachments, can be edited in the Wiki like any others. A converted space can't become a mirror space again.

Removing a single source leaves its pages as they are; the space stays a mirror space until it is converted.

12. For administrators

Settings → Security → Mirrors (settings:write):

Settings → Security → Mirrors: allow mirror spaces, who sets them up, the largest archive and internal git hosts
Settings → Security → Mirrors: allow mirror spaces, who sets them up, the largest archive and internal git hosts
SettingDefaultEffect
Allow mirror spacesOnTurned off, mirror spaces stay as they are and nothing syncs. Sources can still be removed and spaces converted
Who sets mirrors upSpace adminsOr site administrators only: setting a mirror up decides where the Wiki reads from and which token it holds. It also decides who may create a mirror space. Space admins then see their mirror space's sources without changing them
Largest archive (MiB)512Between 1 and 10,240: the largest repository archive or upload a sync reads
Internal git hostsNoneHosts on private addresses that mirrors may reach, one per line (at most 50). Any other private address is refused
  • Syncs run in the background on any server, one step at a time; a sync that fails 5 steps in a row stops with its reason in the history.
  • A mirror's syncs write pages as the person who set it up. If that person can no longer sign in, syncs stop until a space admin chooses Take over on the mirror.
  • Setting up, changing and removing mirrors, syncs, suggestions and converting are in the audit log and raise events: mirror.create, mirror.update, mirror.delete, mirror.convert (a policy can refuse them, for example to allow only some hosts or repositories), mirror.synced, mirror.failed, mirror.suggestion.create and mirror_settings.update.
  • Without a Pro licence nothing syncs; existing mirror spaces stay readable, and can be converted.

13. What isn't there yet

  • Git hosts other than GitHub, GitLab, Gitea, Forgejo and Bitbucket Cloud: upload archives from a pipeline instead.
  • A file renamed in the source becomes a new page; the old page, with its comments, goes to the trash.
  • Pages that already exist aren't moved or re-ordered by later syncs.
  • View on the site guesses a Markdown file's address; sites with unusual permalinks may not match.
  • Suggested edits change the source text of one Markdown file; there is no rich editor for them.