Document multi-repository preview deploy workflow
Antora makes it possible to host content in multiple branches of multiple repositories. This provides writers with a lot of organizational power, but with great power comes with an equally strong need to understand how it all works.
The documentation should suggest (though not mandate) ways of working with content across branches and repositories, specifically coordinating updates and previewing work in progress. Eventually, we anticipate Antora (or tooling around it) to be able to assist with these workflows. But before we can even understand what tooling might do, we need to be able to reason about the workflow. That is the purpose of this documentation. It should help writers today and also inspire tools to be created tomorrow.
By building and hosting the site on Netlify, it's possible to preview content in a staging site before it goes live. The feature is called "preview deploys" (aka branch builds). It's tied directly to the pull request mechanism on GitHub. Each pull request gets assigned a dedicated preview URL automatically.
It's not necessary for each individual writer to create an account or add any additional configuration. When using Netlify (which integrates directly with GitHub), everyone has access to this feature right out of the gate.
Here's how it works, step by step.
The writer creates one or more branches in one of the content repositories (e.g., docs-server) and commits content changes to those branches.
The writer then pushes the branches to their fork of that content repository (e.g., username/couchbase-docs-server).
- Writers can push their branches to the upstream repository, though we feel strongly that using forks prevents the upstream repository from being cluttered
The writer then creates a branch in the docs-site repository and updates the playbook file to point to their content branch(es)
- This requires adding an content source entry that points to their content repository fork and removing the corresponding branch(es) from the content entry for the upstream
- The writer can reuse the same docs-site branch over and over; it's kind of their personal preview site
The writer pushes that branch to their fork of the docs-site repository and sends a pull request from that branch to the upstream docs-site repository
- If the branch is already enlisted in an open pull request, all the writer has to do is push the branch
Visit the pull request on GitHub to find the preview deploy URL (click "Show all checks > Details")
- The preview site looks exactly like the real site, except it includes the writer's content changes
Step 3 is the trickiest part because it requires updating the playbook file to point Antora at the writer's fork of the content repository. (There's a level of indirection here). But if the writer forgets to remove the corresponding branch from the entry for the upstream repository, Antora will fail because it finds two entries for the same version. It's important for the writer to understand that s/he is replacing the official branch (and hence version) with the work in progress one.
Once writers become familiar with this workflow, I don't think they will have any trouble understanding and using it. It just might take some trial and error to gain that understanding.
As we get feedback, we'll certainly discover ways to simplify this process.