Below is a copy‑pasteable Markdown guide you can hand to anyone running a white‑label fork of VDO.Ninja on GitHub Pages (eg. modified main.css, index.html, translation JSON files). It shows the safest, least‑surprising way to get from v22.x to the latest stable release without being a Git pro.

TL;DR

Back up your current fork.

Update your fork to the latest stable release tag (currently v28.0, released Aug 26, 2025). (GitHub)

Re‑apply branding via non‑conflicting overrides (&css, &base64css, &js) and translation files instead of editing core files. (VDO.Ninja)

If you only want “alpha/preview” features, you can sync your fork to the upstream develop branch—but that’s intentionally less stable. (GitHub)

Upgrade VDO.Ninja (white‑label fork) on GitHub Pages

What you’re upgrading to

The latest stable release is VDO.Ninja v28.0 (tag v28.0). (GitHub)
The upstream repo keeps an alpha/preview on the develop branch; releases are tagged (and sometimes branched) separately for stability. For most white‑label sites, track the release tag, not develop. (GitHub)

Prerequisites

You have a fork of steveseguin/vdo.ninja hosted on GitHub Pages.
You can sign into GitHub and open your repo’s Settings → Pages (to pick which branch is published). (GitHub Docs)

Step 0 — Back up what you have (do this once)

In your fork, create a branch named archive-v22 from your current published branch (main, master, or whatever you’re using). GitHub Web UI path: Branches → New branch (source = your current branch). (GitHub Docs)
(Optional) In Settings → Pages, switch the published branch temporarily to archive-v22 so you can roll back instantly if needed. (GitHub Docs)

Option A (Recommended) — Move to the latest stable release tag

This avoids pulling alpha changes and usually reduces merge pain.

A1) Make a clean branch from the latest release

No command line? Use the GitHub Web approach:

Go to the upstream repo’s Tags page and confirm the latest stable tag (e.g. v28.0). Download the Source code (zip) if you prefer to upload files. (GitHub)
In your fork, create a new branch named upgrade/v28. (GitHub Docs)
Replace the contents of upgrade/v28 with the files from the v28.0 zip (drag‑drop in Add file → Upload files), then Commit.

Comfortable with a terminal? Run:

git clone https://github.com/<you>/<your-fork>.git
cd <your-fork>
git remote add upstream https://github.com/steveseguin/vdo.ninja.git
git fetch upstream --tags
git switch -c upgrade/v28 v28.0   # create a branch starting at the release tag

Heads up on translations: The v28.0 tag’s notes include a commit that removes translations/default.json, so translation files changed structure since v22.x. Expect to re-check or re-map keys. (GitHub)

A2) Publish the new branch for testing

Open your fork Settings → Pages → Source: Deploy from a branch, pick upgrade/v28 and root /. Save. (GitHub Docs)
Visit your Pages URL and confirm it loads. The landing page shows a Version label—verify it reads the new version (e.g., “Version: 28.0”). (VDO.Ninja)

A3) Re‑apply your branding without touching core files

To avoid future merge conflicts:

CSS: Put your styles in a separate file (e.g., /brand.css in your fork) and add &css= to your links:
```
https://<your-pages-domain>/?css=https%3A%2F%2F<your-pages-domain>%2Fbrand.css
```
You can also inline CSS with &base64css=. (VDO.Ninja)
JS tweaks (optional): If you truly need JS for minor DOM changes, host /brand.js and pass it with &js=:
```
https://<your-pages-domain>/?js=https%3A%2F%2F<your-pages-domain>%2Fbrand.js
```
(Keep it minimal.) (VDO.Ninja)
Translations / wording: Use the &language= parameter to select a language file (e.g., &language=fr). The app loads translations by language code. Inference: in your own fork, placing a file like translations/mybrand.json and visiting ?language=mybrand should use that file; if not, replace the existing translations/en.json in your fork and use &language=en. (VDO.Ninja)

Why this approach? Using &css/&js/&language keeps your changes out of index.html, main.css, and core scripts, so future upgrades are mostly just “switch to the next release tag” with zero or few conflicts. (VDO.Ninja)

A4) Flip your production Pages branch

When your upgrade/v28 branch looks good, either:

Change Settings → Pages to publish from upgrade/v28, or
Merge upgrade/v28 into your normal published branch (main) and publish that. (Use a Pull Request so you can review the diff.)

(GitHub Docs)

Option B — One‑click Sync Fork (fastest, but may be “alpha”)

If you don’t mind tracking the upstream develop branch (preview/nightly), you can click Sync fork on your fork’s homepage and “Update branch.” GitHub will merge upstream’s default branch into your fork’s default branch. Conflicts must be resolved if you changed core files. (GitHub Docs, GitHub)

Note: Upstream’s default branch is currently develop and is intentionally not as stable as tagged releases. For production/clients, prefer Option A. (GitHub)

CLI equivalent (optional):

# with GitHub CLI installed
gh repo sync <you>/<your-fork> -b <your-default-branch>

(GitHub Docs)

Handling merge conflicts (if you edited core files)

If you previously changed index.html, main.css, or core JS, expect conflicts jumping from v22 to v28.
Easiest fix: Stop editing core files and move your customizations to /brand.css (+ &css=) and /brand.js (+ &js=). Then delete your old core edits. (VDO.Ninja)
For translations, compare your old JSON to the new release’s language file to re‑map any changed keys (a JSON diff tool helps). Note that translation files evolved since v22. (GitHub)

Verifying the upgrade

Open your published site and check the Version string on the landing page or other UI places. For the upstream site, it shows “Version: 28.0” today; your fork should reflect the version shipped by the files you deployed. (VDO.Ninja)
Exercise your usual links (?push, ?room, ?view, scenes, etc.) with your &css/&language overrides.

Rolling back

Switch Settings → Pages back to your archive-v22 branch, or revert the merge that updated your published branch. (GitHub Docs)

FAQ

Q: Isn’t this just “pull from upstream and merge”? A: Yes in spirit—but if you’ve modified core files, that’s how people get stuck in merge hell. Using release tags plus &css/&js/&language keeps your brand changes decoupled from upstream, so future upgrades are a quick branch switch or tag bump. (GitHub, VDO.Ninja)

Q: Where do I find stable vs alpha? A: Stable is on release tags (eg. v28.0). Alpha/preview is the develop branch. The upstream README describes this split. (GitHub)

Q: How do I change which branch GitHub Pages publishes? A: Settings → Pages → “Deploy from a branch” and pick the branch/folder. (GitHub Docs)

Q: How do I change the interface language via URL? A: Add &language=<code> to your links (eg. &language=fr). (VDO.Ninja)

Appendix — Commands (power users)

# Add upstream once
git remote add upstream https://github.com/steveseguin/vdo.ninja.git

# See what’s available
git fetch upstream --tags

# Create a new branch from the latest stable release tag
git switch -c upgrade/v28 v28.0

# (Optional) bring over just your old brand assets from your old branch
git checkout archive-v22 -- brand.css brand.js translations/en.json

# Commit and push
git add .
git commit -m "Upgrade to v28.0 + reapply brand overrides"
git push -u origin upgrade/v28

# Make a PR to main, or set Pages to publish from upgrade/v28

References

Latest release tag (v28.0) and prior tags. (GitHub)
“Develop vs Release” explanation in upstream README. (GitHub)
Syncing a fork (web UI, gh repo sync, Git). (GitHub Docs)
GitHub Pages: publish from a branch. (GitHub Docs)
Design/branding via URL: &css, &base64css, &js. (VDO.Ninja)
Set UI language via URL: &language=. (VDO.Ninja)

If you like, I can tailor this to your exact repo layout (which branch you publish from, which files you changed) and produce the precise diff/apply steps—but as written, this should be “dummy‑resistant” and safe for most forks.

steveseguin/upgrade.md

Select an option

No results found