feat: build documentation and host it on github pages by skjnldsv · Pull Request #14177 · nextcloud/documentation

skjnldsv · 2026-03-29T07:48:17Z

Summary

Move documentation hosting to GitHub Pages, removing the need to maintain our own hosting infrastructure and the documentation build step from the release process.

See https://docs.skjnldsv.com

What this changes

No more doc builds at release time. Docs are built and published automatically on every push to master and stable branches, so they're always up to date without any extra step during releases.
No more self-hosted doc infrastructure. GitHub Pages handles hosting entirely.
PDF downloads included. User and admin manuals now ship with a generated PDF alongside the HTML version.
Docs index stays in sync. The landing page is generated dynamically from active stable branches, so it never needs manual updates when a new version is released.

How it works

Here's a clear breakdown:Here's how the full system works:

Every branch pushes its own docs. When any branch (master or stableXX) is pushed, sphinxbuild.yml builds all three manuals (user, admin, developer) plus their PDFs, and the deploy job maps the branch name to a folder on gh-pages:

master → server/latest/
the highest numbered stable → server/stable/
stableXX → server/XX/

So stable29 would deploy to server/29/, completely independently of every other branch.

The index page is separate. generate-top-index.yml only runs on master pushes. It scans all stableXX branches dynamically, generates a fresh index.html via a PHP script, and commits it to the root of gh-pages. No manual updates needed when a new stable is cut — it picks it up automatically.A few things worth noting about the deploy logic:

The branch-to-folder mapping is smart: master always goes to server/latest/, and whichever is the highest-numbered stable at the time of the push additionally gets written to server/stable/. This means server/stable/ always points to the most recent release without any manual redirect management.

TODO after

Run the dispatch workflow to update the sphinxbuild.yml actions
Run the dispatch workflow to update the build/verify-index.php file

Notes

The sphinxbuild workflow needs to be backported down to stable19, which is the oldest branch we can support with the current Sphinx build process.

When backporting, use Python 3.12 for stable32 and above (aligning with nextcloud/documentation), and Python 3.10 for stable31 and below.

How to test

Merge this PR into master and backport sphinxbuild.yml to stable19 and above
Wait for the GitHub Actions workflows to complete
Visit the GitHub Pages URL and confirm all manuals (user, admin, developer) are accessible
Check that PDF download links work for the user and admin manuals
Verify the index page lists the correct stable versions

Copilot

Pull request overview

This PR migrates documentation publishing to GitHub Pages by building manuals on CI, deploying per-branch outputs to gh-pages, and generating a dynamic top-level index.html from active stable branches.

Changes:

Replace the static root index.html with a generated landing page (PHP script + HTML template + bundled static assets).
Update Sphinx configs and CI workflow to build HTML for user/admin/developer manuals and generate PDFs for user/admin manuals.
Replace the legacy go.php server-side redirect with a GitHub Pages–compatible client-side redirect (go.php/index.html).

Reviewed changes

Copilot reviewed 13 out of 63 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
user_manual/index.html	Add redirect from `user_manual/` to `user_manual/en`.
user_manual/conf.py	Add LaTeX/PDF-related configuration for user manual outputs.
index.html	Remove legacy static landing page (now generated via workflow).
go.php/index.html	Add JS-based redirect replacement for `go.php`.
go.php	Remove legacy PHP redirect implementation (not supported on Pages).
build/static/js/require.min.js	Add RequireJS runtime for generated landing page.
build/static/js/require.config.js	Add RequireJS configuration for landing page assets.
build/static/js/navigation.js	Add navigation JS for generated landing page.
build/static/js/modules/youtubePlayer.js	Add YouTube player module used by landing page.
build/static/js/modules/submenu.js	Add submenu behavior for landing page.
build/static/js/modules/slideshow.js	Add slideshow behavior for landing page.
build/static/js/modules/header.js	Add header behavior for landing page.
build/static/js/modules/cookieconsent.js	Add cookie consent behavior for landing page.
build/static/js/modules/codeHighlights.js	Add code highlighting behavior for landing page.
build/static/js/main.js	Add main landing page behavior/animations.
build/static/img/warning.svg	Add landing page static asset.
build/static/img/social/youtube.svg	Add landing page social icon asset.
build/static/img/social/twitterround.png	Add landing page social icon asset.
build/static/img/social/twitter.svg	Add landing page social icon asset.
build/static/img/social/twitter.png	Add landing page social icon asset.
build/static/img/social/rss.svg	Add landing page social icon asset.
build/static/img/social/rss.png	Add landing page social icon asset.
build/static/img/social/mail.svg	Add landing page social icon asset.
build/static/img/social/googleplus.svg	Add landing page social icon asset.
build/static/img/social/googleplus.png	Add landing page social icon asset.
build/static/img/social/facebook.svg	Add landing page social icon asset.
build/static/img/social/facebook.png	Add landing page social icon asset.
build/static/img/social/diasporaround.png	Add landing page social icon asset.
build/static/img/social/diaspora.svg	Add landing page social icon asset.
build/static/img/social/diaspora.png	Add landing page social icon asset.
build/static/img/note_pencil.svg	Add landing page static asset.
build/static/img/Nextcloud-Talk.svg	Add landing page static asset.
build/static/img/Nextcloud-Home.svg	Add landing page static asset.
build/static/img/Nextcloud-Groupware.svg	Add landing page static asset.
build/static/img/Nextcloud-Files.svg	Add landing page static asset.
build/static/img/logo.svg	Add landing page static asset.
build/static/img/logo_white_sprite.png	Add landing page static asset.
build/server-block.php	Add PHP helper to render per-version “server” blocks in generated index.
build/index-template.html	Add HTML template for generated landing page.
build/build-index.php	Add generator that fills template with stable/latest blocks and writes `build/index.html`.
admin_manual/conf.py	Add LaTeX/PDF-related configuration for admin manual outputs.
.gitignore	Ignore generated `build/index.html` and root `index.html`.
.github/workflows/update-workflow.yml	Add workflow to backport a file from `master` into stable branches.
.github/workflows/sphinxbuild.yml	Rework docs build into matrix + deploy-to-`gh-pages` job.
.github/workflows/generate-top-index.yml	Add workflow to generate and publish the top-level Pages `index.html` + static assets.
.github/dependabot.yml	Remove pip Dependabot updates configuration.

Comments suppressed due to low confidence (1)

user_manual/index.html:6

The comment has a grammar issue: "This act as" should be "This acts as".

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

skjnldsv · 2026-04-01T14:25:49Z

That means after branch-off, stable is pointing to the next version while not being released. I'm unsure if that's a good idea. Maybe a check if a tag "vXY.0.0" exists?

Good idea!

I'll have a look at the pdf generation 👍

skjnldsv · 2026-04-01T19:33:07Z

Done @kesselb, I now properly generate the full versions based on their release and support EOL date.

https://github.com/skjnldsv/documentation/actions/runs/23866606290/job/69587299106#step:6:10

I also fixed a few things. The pdf theming as well for example.

kesselb · 2026-04-01T20:32:50Z

Nice, Thank you 🙏

kesselb · 2026-04-01T20:33:48Z

On https://docs.skjnldsv.com/ the docs for Nextcloud 31 does point to stable instead of 31.

kesselb · 2026-04-01T20:35:40Z

Did you drop the links (on the index page) to 30, 29, etc intentionally?

skjnldsv · 2026-04-02T06:46:40Z

Did you drop the links (on the index page) to 30, 29, etc intentionally?

Nope, forgot to push a fix 👍

Add update-workflow.yml to automatically dispatch documentation builds when triggered externally, enabling continuous deployment.

Move user_manual_index.html to user_manual/index.html to align the English language redirect with the per-language URL structure.

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>

Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>

https://github.com/skjnldsv/documentation/commit/4f59e8ba2dafd9fbcdb156fe8dca42a8346d9a0e Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com> Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

Bumps [requests](https://github.com/psf/requests) from 2.33.0 to 2.33.1. - [Release notes](https://github.com/psf/requests/releases) - [Changelog](https://github.com/psf/requests/blob/main/HISTORY.md) - [Commits](psf/requests@v2.33.0...v2.33.1) --- updated-dependencies: - dependency-name: requests dependency-version: 2.33.1 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com>

Bumps [pygments](https://github.com/pygments/pygments) from 2.19.2 to 2.20.0. - [Release notes](https://github.com/pygments/pygments/releases) - [Changelog](https://github.com/pygments/pygments/blob/master/CHANGES) - [Commits](pygments/pygments@2.19.2...2.20.0) --- updated-dependencies: - dependency-name: pygments dependency-version: 2.20.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com>

Bumps [sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid) from 2.0.0 to 2.0.1. - [Changelog](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/CHANGELOG.md) - [Commits](mgaitan/sphinxcontrib-mermaid@2.0.0...2.0.1) --- updated-dependencies: - dependency-name: sphinxcontrib-mermaid dependency-version: 2.0.1 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com>

Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 4.6.2 to 7.0.0. - [Release notes](https://github.com/actions/upload-artifact/releases) - [Commits](actions/upload-artifact@ea165f8...bbbca2d) --- updated-dependencies: - dependency-name: actions/upload-artifact dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com>

Bumps [actions/checkout](https://github.com/actions/checkout) from 4.2.2 to 6.0.2. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@v4.2.2...de0fac2) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 6.0.2 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com>

Bumps [actions/cache](https://github.com/actions/cache) from 4.2.3 to 5.0.4. - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](actions/cache@5a3ec84...6682284) --- updated-dependencies: - dependency-name: actions/cache dependency-version: 5.0.4 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com>

Bumps [shivammathur/setup-php](https://github.com/shivammathur/setup-php) from 2.34.1 to 2.37.0. - [Release notes](https://github.com/shivammathur/setup-php/releases) - [Commits](shivammathur/setup-php@2.34.1...accd612) --- updated-dependencies: - dependency-name: shivammathur/setup-php dependency-version: 2.37.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com>

Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 4.3.0 to 8.0.1. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](actions/download-artifact@d3f86a1...3e5f45b) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-version: 8.0.1 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

Agent-Logs-Url: https://github.com/skjnldsv/documentation/sessions/e2f6fe71-2793-4c59-80fb-073d6f45204e Co-authored-by: skjnldsv <14975046+skjnldsv@users.noreply.github.com>

skjnldsv · 2026-04-02T07:35:40Z

Alright, it's good to go now, when merged, the other branches should be triggered to build their own version of the pages

szaimen

🐘

skjnldsv · 2026-04-03T07:31:43Z

/backport 3916ae8 to stable33

skjnldsv requested review from Altahrim, AndyScherzinger, blizzz, nickvergessen, sorbaugh and st3iny March 29, 2026 07:49

skjnldsv self-assigned this Mar 29, 2026

skjnldsv added enhancement 3. to review technical debt labels Mar 29, 2026

skjnldsv commented Mar 29, 2026

View reviewed changes

Comment thread .github/dependabot.yml

skjnldsv commented Mar 29, 2026

View reviewed changes

Comment thread go.php/index.html

skjnldsv commented Mar 29, 2026

View reviewed changes

Comment thread go.php/index.html Outdated

ChristophWurst reviewed Apr 1, 2026

View reviewed changes

Comment thread go.php

kesselb reviewed Apr 1, 2026

View reviewed changes

Comment thread build/index-template.html Outdated

kesselb requested a review from Copilot April 1, 2026 08:00

Copilot AI reviewed Apr 1, 2026

View reviewed changes

kesselb reviewed Apr 1, 2026

View reviewed changes

Comment thread .github/workflows/update-workflow.yml Outdated

skjnldsv closed this Apr 1, 2026

skjnldsv reopened this Apr 1, 2026

skjnldsv requested review from ChristophWurst and kesselb April 1, 2026 09:40

This comment has been minimized.

Sign in to view

This comment was marked as resolved.

Sign in to view

skjnldsv and others added 22 commits April 2, 2026 08:55

feat: add documentation auto-update trigger workflow

745d86f

Add update-workflow.yml to automatically dispatch documentation builds when triggered externally, enabling continuous deployment.

fix: move user_manual English redirect to user_manual/index.html

263511e

Move user_manual_index.html to user_manual/index.html to align the English language redirect with the per-language URL structure.

Add stable32 & stable33 auto deploy

a50b071

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>

fix: runner from ubuntu-latest-low to ubuntu-latest

51fa0da

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>

fix(ci): restore python 3.12

ed1ea52

Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>

fix: update go link for admin-php-modules

efbe408

https://github.com/skjnldsv/documentation/commit/4f59e8ba2dafd9fbcdb156fe8dca42a8346d9a0e Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>

fix: use git ls-remote to detect stable branches

b5184f2

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com> Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

fix: apply fixes from reviews

1b94fcc

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

chore: restore dependabot config

882ca27

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

fix: index generation and add tests

69e5f86

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

fix: pdf generation and style

5f31bb8

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

fix: do not fail if root index.html have no changes

d1f4681

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

fix: restore missing main conf.py

46892c4

fix: use actual release version in PDF output instead of latest

3916ae8

Agent-Logs-Url: https://github.com/skjnldsv/documentation/sessions/e2f6fe71-2793-4c59-80fb-073d6f45204e Co-authored-by: skjnldsv <14975046+skjnldsv@users.noreply.github.com>

kesselb approved these changes Apr 2, 2026

View reviewed changes

szaimen approved these changes Apr 2, 2026

View reviewed changes

skjnldsv merged commit 6b9accd into nextcloud:master Apr 2, 2026
11 of 12 checks passed

backportbot Bot added the backport-request label Apr 3, 2026

backportbot Bot mentioned this pull request Apr 3, 2026

[stable33] fix: use actual release version in PDF output instead of latest #14226

Merged

backportbot Bot removed the backport-request label Apr 3, 2026

Uh oh!

Conversation

skjnldsv commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What this changes

How it works

TODO after

Notes

How to test

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment was marked as resolved.

skjnldsv commented Apr 1, 2026

Uh oh!

skjnldsv commented Apr 1, 2026

Uh oh!

kesselb commented Apr 1, 2026

Uh oh!

kesselb commented Apr 1, 2026

Uh oh!

kesselb commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

skjnldsv commented Apr 2, 2026

Uh oh!

skjnldsv commented Apr 2, 2026

Uh oh!

szaimen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

skjnldsv commented Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

skjnldsv commented Mar 29, 2026 •

edited

Loading

kesselb commented Apr 1, 2026 •

edited

Loading