Automated PR preview hosting for docs contributions

[alexeyzakh]

Today, reviewing a docs PR means doing it locally: switch to the PR branch (for example, in GitHub Desktop), fetch it, run archbee dev, and view the result in a browser.

This is relatively quick, but it means every reviewer runs untrusted contributor content on their own machine. Markdown/MDX can embed HTML/JS that executes in the browser at localhost during preview.

We would like to remove this risk and make it easier for non-maintainers to review content. Ideally, a bot would post a clickable preview link on each PR, updated on every push. Similar to what's happening in the MCU Firmware sub-project:

We hope to find a solution with the help of the community. Ideas and prototypes are all welcome!

[astynax]

Any clickable previews you described suppose that somewhere should be a VM that will serve every version of docs.

Another option is to use a single GitHub Pages site and build every version of the doc as a subfolder under the URL like flipperone-docs.flipperdevices.io/PR-##/. It would require some cleaning up procedure for closed PRs, but it sounds doable.

[galleon8]

Seems like there is a Tugboat tool (https://www.tugboatqa.com/), or any similar, that can build working previews for branches, commits, tags, and pull requests in a git repository. It integrates with GitHub and can automatically create a preview for each PR.

This looks like a good fit for the current Archbee + GitHub workflow. Instead of reviewers fetching contributor branches locally and running archbee dev, Tugboat could run the same preview process in an isolated, disposable environment and post a clickable preview link to the PR.

The production flow would stay unchanged, Tugboat would only add a pre-merge preview layer:

PR into public-release
        ↓
Tugboat checks out the PR
        ↓
Tugboat runs Archbee preview
        ↓
Tugboat posts preview URL to the PR

A maintainer would need to connect the GitHub repository to Tugboat, add a .tugboat/config.yml file to the repository, and enable automatic PR previews, preview comments, PR status checks, and forked PR previews if needed.

The main thing to verify with a proof of concept is whether archbee dev --port 3000 is reachable through Tugboat’s preview URL.

[hypery11]

I tried this locally and have a few concrete findings that might narrow the options.

archbee dev is a Next.js live server and the docs are client-rendered, so there's no static HTML to grab by just fetching a URL. It loads the markdown locally (no Archbee SaaS call needed to render content), but a plain wget/curl mirror only gets an empty shell. Rendering a page with a headless browser does produce faithful HTML (custom blocks like ::VerticalSplit come out as real layout), so a static export is possible but needs a browser in the loop, not just a crawler.

@galleon8 on the PoC question: archbee dev --port 3000 is reachable and renders fine in a clean container, so Tugboat or any disposable-env runner serving the live dev server would work. @astynax the GitHub Pages subfolder approach also works, but it needs that headless-render step first to turn the SPA into static files.

One caveat for either approach: images load from api.archbee.com, so previews aren't fully self-contained unless assets are rewritten.

Worth checking before building anything custom: archbee.json has publishSpace set, so does Archbee's own GitHub integration already offer a per-branch preview space? If so, most of this goes away.

I can put up a working PoC (already have the headless render + a sample static dump working) if that's useful.

[TriplEight]

I subscribed to an Archbee trial, deployed and integrated it with my fork. Also played a bit with CLI.

Some findings:

1. Github integration is in beta (space settings -> General -> Edit mode: Branches & Reviews). Their current documentation claims that edits are possible both ways (edit in Archbee UI and push to GitHub and edit on a branch and see as a preview space in Archbee). However neither of ways work yet for the context of this issue - it's only possible to setup Archbee with one branch and one repo - and you currently have it as a prod version of docs. It's also possible to switch your current integration method to this one and then space settings - (wait a bit) > Github integration -> Sync with repo. Clearly this option will be the best way for you when the integration is out of beta.

Details

2. It is possible to set up a preview (see my deployment https://shared.archbee.space/public/PREVIEW-mfEW1UzrSN99dQNgEdKRN/PREVIEW-tabWQlBWMsAJXFTbjkEp1). Although currently only in Drafts & Reviews edit mode, which doesn't communicate with GitHub.
3. It might be possible to temporarily workaround this limitation with API, but I can't test it since API is not included in a trial version.

What's feasible as an interim makeshift:

1. pull_request GitHub Actions workflow triggers on docs/** changes (safe - no secrets, standard fork permissions, also runs in a throwaway azure conainer)
2. Checks out the PR head (the untrusted markdown)
3. Installs @archbee/cli and runs archbee dev in the background - this starts a local HTTP server serving the rendered docs
4. playwright navigates to the local server, screenshots each page corresponding to a changed .md file, saves as PNGs. Might be possible to get PDFs or htmls from a CLI
5. CLI can also check for the broken links, so screenshot will be sufficient
6. Uploads screenshots as workflow artifacts, then a job with GITHUB_TOKEN posts them inline in the PR comment
   What the PR comment looks like:

▎ 📸 Docs preview — 2 changed pages
▎ docs/general/Tech-Specs.md → screenshot (artifact-url)
▎ docs/Welcome.md → screenshot (artifact-url)

But the first thing I'd do if I were you - is asking Archbee support when are they going to finish the GitHub flow. Quite honestly, the whole Archbee product seems very raw.

[NetVar1337]

Ready-to-post comment for #340 (≤250 words):

I built a working version of @astynax's Pages-subfolder idea, with @hypery11's headless-render step — no third-party services, no secrets exposed to fork PRs: https://github.com/VoidChecksum/flipperone-docs/tree/pr-preview

Design. A pull_request workflow renders archbee dev in headless Chrome (the CLI has no static export) and saves a static snapshot: scripts and inline handlers stripped, absolute URLs rewritten relative, same-origin assets mirrored. A second workflow_run workflow publishes it to gh-pages/pr/<n>/ and keeps a sticky comment with the link; a third deletes it when the PR closes. Locally: 55/55 pages render in ~30 s, and the snapshot navigates correctly when served from a subpath.

Security model. The build half runs untrusted markdown with a read-only token and no secrets; the deploy half runs only base-branch code and cross-checks the artifact's PR number against the API before publishing. Previews are plain HTML with zero contributor JS — relevant because github.io project sites share an origin org-wide. Reviewers stop running PR content on their own machines, which was the point of this issue.

To turn on: merge the branch and enable Pages once (Settings → Pages → deploy from branch → gh-pages/root). Only official actions/* are used.

Honest caveat: snapshotting a client-rendered SaaS app is a workaround. If Archbee ships a static export or finishes the GitHub integration @TriplEight tested, this machinery shrinks to a few lines — worth asking their support in parallel.

[gmike8046-netizen]

How easy is this to use?

What do I need to know to use the flipper One?

Questions to sell something that people need, not necessarily what they want.