Website for 1.2.8: dependency upgrades and documentation drift

[MaEscalanteHe]

Hi! For 1.2.8 I'd like to take on the website. I compared the docs against the current code, and between outdated dependencies and documentation drift there's a fair amount to do, so I'm opening this thread to keep it in one place.

Mini-roadmap

1. Already done

On feature/web-refresh in my fork, branched from develop.

• Removed 10 dependencies that nothing imports (zod, date-fns, react-markdown, gray-matter, fs, path and a few more), pinned the "latest" ranges and applied the minor and patch updates. npm audit drops from 15 vulnerabilities to 6, none of them critical.
• About 460 generated pages showed < and > literally, for example disk-<device>. The fix is a single change in i18n/loadMessages.ts, which turns the entities into ICU quoting, so the catalogs and the translation checker stay as they are.
• storage-share/host-local-disk showed a raw message key instead of the text, in all eight languages.

Merged in #557.

2. Major upgrades (moved to 1.2.8.1-beta)

Each upgrade gets its own PR, with a full build and a check in the browser.

• Next 15 to 16, and the deploy workflow from Node 20, which is end of life, to Node 26 LTS. This also clears the remaining postcss advisory.
• Tailwind 3 to 4, together with @tailwindcss/typography and tailwind-merge 3.
• @types/react / @types/react-dom 18 to 19 so they match React 19.
• Mermaid 11 to 12, which clears the katex and mermaid advisories.
• lucide-react 1.x, recharts 3, react-resizable-panels 4, sonner 2 and html-react-parser 6.
• Replace setRequestLocale, deprecated since next-intl 4.14.
• TypeScript 5 to 7, last. Next.js supports it since 16.3 by running the project's tsc, but that path is still marked experimental. If it causes trouble, TypeScript 6 is the fallback.

3. Documentation drift

About 45 statements across 30 pages no longer match the code. I'd fix them section by section, one PR each, English first. Some examples:

• The docs say the Monitor is optional at install time, but the installer always installs it.
• "Change Language" is hidden in the sidebar "until the translation flow is reactivated", although config_menu.sh already offers it.
• Some API paths are wrong (/api/auth/ssl/* is /api/ssl/*, and the exclusions live under /api/health/*), and tokens and SSL are placed under Settings instead of Admin → Security.
• lxc-samba-server documents GID 999 while the code uses 101000, and persistent-names suggests rm 10-*.link, which would also delete files the user created.
• Several Disk Manager pages (format-disk, add-controller-nvme-vm, import-disk-lxc) describe behaviour the scripts no longer have.

Sections: Settings & Introduction, Monitor, Backup & Restore, OCI manager, Storage & Share, Disk Manager, Hardware, Create VM, Network, Security and Utils.

• Settings, Introduction and Installation (docs(web): fix Settings, Introduction and Installation drift #574)
• Monitor (docs(web): fix Monitor drift #575)
• Backup & Restore (docs(web): fix Backup & Restore drift #586)
• Utils (docs(web): fix Utils drift #587)
• Storage & Share (docs(web): fix Storage & Share drift #637)
• Disk Manager (docs(web): fix Disk Manager drift #638)
• Network (docs(web): fix Network drift #639)
• Post-install (docs(web): fix Post-install drift #640)
• Hardware, Create VM, Security and Help & Info (docs(web): fix Hardware, Create VM, Security and Help & Info drift #641)
• OCI manager: no drift found, no PR needed

4. Missing pages (moved to 1.2.8.1-beta)

• The Monitor's Backup tab: host backup, VM/CT backup jobs and restore.
• PBS host support, both the CLI menu and the Monitor's PBS mode.
• Notification events. The docs list about 70 and the code has 106.
• OCI manager: custom multi-service Compose (including workers and migration jobs), the Zigbee serial adapter, owner-aware tmpfs mounts and stack frontend URLs. The Swedish custom-image page also still says multi-service Compose files are blocked.

5. Smaller items

Merged in #652.

• Four pages show <code> tags as plain text: changelog, AI assistant, access & auth and cross-kernel.
• The strict translation check fails on 4 Spanish files and on the Slovak sidebar.
• guides/*.md in the repo have drifted from the website guides; we should decide whether to keep them. Removed, the website has the same guides.

How I'd work

1. A first PR to develop with block 1, which is ready.
2. Then one PR per item in blocks 2 to 4, so each one is easy to review and to revert.

Questions

1. You mentioned 1.2.8 would be a short corrective release. Does this scope fit, or would you rather move blocks 2 and 4 to the beta after it?
2. Was hiding "Change Language" intentional for some other reason?

[MacRimi]

Hi @MaEscalanteHe,

Thank you so much for this. Honestly, it's a huge help. Keeping ProxMenux moving on my own means the documentation is often the first thing to fall behind, and I know there are times when it doesn't match the code. Seeing someone take the time to compare the docs against the current code, find around 45 outdated statements, and turn it all into a clear roadmap is a real gift to the project.

The plan looks excellent, and working in small PRs, one per item so each is easy to review and revert, is exactly the right approach. Please go ahead and open the first PR to develop with block 1.

On your questions:

•	Scope for 1.2.8: [Blocks 1, 3 and 5 fit well in the corrective release. Let's move blocks 2 and 4 to the beta after it. / The full scope is fine for 1.2.8.]
•	"Change Language": No, there was no other reason. I simply forgot to restore it in the sidebar after the translation flow was reactivated. Please go ahead and uncomment the entry in DocSidebar.tsx so the page shows again.

If you'd like to take care of the documentation on an ongoing basis, I'd be really happy to have you on board. It would be a magnificent contribution. Feel free to ping me with any questions about how a feature is supposed to behave.

Thanks again, truly appreciated!

[MaEscalanteHe]

Thanks @MacRimi, really glad it helps!

I've opened the PR for block 1: #557. It also includes the Change Language entry in the sidebar, with its label translated into all eight languages.

On scope, I'll go with blocks 1, 3 and 5 for 1.2.8 and leave the major upgrades and the missing pages for the next beta (1.2.8.1-beta, if I've got the numbering right). Your reply still had both options in brackets, so let me know if you meant the full scope instead.

And yes, I'd be happy to keep looking after the docs. I'll ping you when I'm not sure how something is supposed to behave.

[MacRimi]

Sorry about the brackets, I left both options in by mistake! Blocks 1, 3 and 5 for 1.2.8, and the major upgrades and missing pages for the next beta, is exactly what I meant. And yes, the numbering is right: 1.2.8.1-beta.

I've left a comment on #557. It's only a small detail on two pages, and everything else is ready.

Having you look after the docs is a real relief. Whenever you're unsure how something is meant to behave, just ask me here.

[MaEscalanteHe]

Block 3 is done! Thanks @MacRimi for the reviews and the extra fixes, and thanks @Vaso73, @f3rs3n and @Umnov91 for going over the Slovak, Italian and Russian.

These are the merged PRs:

• docs(web): fix Settings, Introduction and Installation drift #574 Settings, Introduction and Installation
• docs(web): fix Monitor drift #575 Monitor
• docs(web): fix Backup & Restore drift #586 Backup & Restore
• docs(web): fix Utils drift #587 Utils
• docs(web): fix Storage & Share drift #637 Storage & Share
• docs(web): fix Disk Manager drift #638 Disk Manager
• docs(web): fix Network drift #639 Network
• docs(web): fix Post-install drift #640 Post-install
• docs(web): fix Hardware, Create VM, Security and Help & Info drift #641 Hardware, Create VM, Security and Help & Info

OCI manager didn't need a PR, since the audit found nothing wrong there. Post-install and Help & Info weren't on the original list, but they had drift too, so I included them. Now that Russian is in, I'll include it in my PRs and tag Umnov91 on those changes (more on that in #599).

The only thing left for 1.2.8 is block 5. I'll open one PR for the <code> tags that show up as plain text and for the strict translation check. About guides/*.md: they no longer match the website guides. Should I delete them and point to the website, or keep them in sync?

Once that's in, I'll start on blocks 2 and 4 for 1.2.8.1-beta.

[MacRimi]

Great work on block 3, thank you! The docs match the code again, and adding Post-install and Help & Info was a good call.

A note on timing: 1.2.8 is already out, so block 5 will ship with 1.2.8.1-beta, together with blocks 2 and 4.

About guides/*.md, I'd delete them. The website already has the same four guides (NVIDIA, Samba in an LXC, cloud backup and Kodi), translated, with its own copies of the images in web/public/guides. Nothing in the repository links to those files, and the README already points to proxmenux.com/guides. Please remove the .md files and their image folders together.

While you're on block 5: two glossary entries link to routes that don't exist. /guides/nvidia should be /guides/nvidia-manual, and /guides/backup_cloud should be /guides/backup-cloud. They could go in the same PR.

[MaEscalanteHe]

Block 5 is up in #652: the guides/ folder is gone, the glossary links point to the real guide routes, and the tags that showed up as text render properly now.

The strict translation check is still open: I left a question for you in the PR, since fixing it means touching the docs translation script. Once that's settled, I'll start on blocks 2 and 4.

[MacRimi]

Thanks a lot for block 5, it's merged now! The glossary links, the tags that showed up as text and the cleanup of guides/ all look great.

I think the strict translation check ended up in a good place too: the exceptions for headers, captions, breadcrumbs and the Slovak FAQ label, with VM and NVIDIA still protected and the tests covering both, are exactly what I would have hoped for. Thanks also to @f3rs3n and @Vaso73 for checking it so carefully. The strings still pending in de, fr, pt and sv for contribute-app.json can be left to the translation workflow.

Whenever you're ready, please go ahead with blocks 2 and 4 for 1.2.8.1-beta. As always, if you're unsure how something is meant to behave, just ask me here.

[MaEscalanteHe]

Thanks @MacRimi! Something you might have missed, since it went in at the end: while testing every page in all nine languages with next dev, I found a few rendering bugs the build doesn't catch. Some pages showed raw message keys (ssl-letsencrypt, lxc-samba-server and access-auth), and in French and Italian a straight apostrophe before a tag printed the tag as text. They're all fixed in #652.

I'm starting on blocks 2 and 4 now, beginning with Next 16 and Node 26.

[MaEscalanteHe]

Block 2 is ready, @MacRimi. It ended up as six PRs instead of one per upgrade, because every upgrade touches package-lock.json and separate PRs would have conflicted with each other. Each one builds on the previous, so I will open them one at a time: when one is merged, I open the next. That way every PR shows only its own commits.

1. chore(web): upgrade to Next 16, TypeScript 7 and Node 26 #667 Next 16, TypeScript 7 and Node 26 for the deploy workflow. The build type-checks again.
2. Mermaid 12 (preview).
3. Unused components removed, plus lucide-react 1, html-react-parser 6 and smaller updates (preview).
4. Tailwind 4, with the config moved into CSS (preview).
5. setRequestLocale replaced with next/root-params, and a styled 404 page (preview).
6. Sitemap and search index fixes, plus the broken internal links (preview).

The six branches are already pushed and tested, so the previews show exactly what each PR will contain. One request: please keep merging them with a merge commit, as you did with the previous ones. With a squash the next branch would show these commits again and I would have to rebase it.

Three things changed from the plan in the first post:

• recharts, react-resizable-panels and sonner are not upgraded but removed. 48 of the 64 files in components/ui were never imported, and those packages only existed for them. The site goes from 58 direct packages to 26.
• Replacing setRequestLocale meant moving the root layout into app/[locale]. In exchange the server now renders the right <html lang>, so LocaleHtmlSync and localize-export.mjs are gone.
• The live sitemap has [locale] written literally in 145 of its 146 URLs. PR 6 fixes it, along with eight internal links that had no locale and ended in a 404, and the "Hardware" breadcrumb, which linked to a page that does not exist.

What you will notice on the site:

• The OCI manager diagrams use the Mermaid 12 layout, with right-angle edges. It is a separate commit, easy to revert if you prefer the old look.
• Colours are slightly more saturated, from the Tailwind 4 palette. Sizes and spacing are unchanged: I measured every element of the 145 English pages on desktop and mobile.
• Some icons are redrawn by lucide 1.x.
• The 404 page has the site theme and a link back to the home page.
• The export grows from about 411 MB to about 655 MB, because Next 16 writes prefetch files next to every page. Pages allows 1 GB.

Things I found and left alone, in case you want them fixed:

• The numbered steps only have a gap after the first step. The code asks for 40 px between all of them, but space-y-0 was overriding it. I kept what the site shows today.
• The cylinder nodes in the diagrams are drawn with a notch.
• https://proxmenux.com/share/main-menu.png in the changelog does not load.
• npm audit still reports two moderate advisories: @tailwindcss/typography pins postcss-selector-parser 6.0.10. It only runs at build time on our own CSS.

I could not test the real deploy, since deploy.yml only runs on main. Everything was tested on the static export with a local server.

Next is block 4, the missing pages.