Fix documentation build

.github/scripts/build-documentation.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# preparing fake remote
+mkdir .build
+git config user.name ci-bot
+git config user.email [email protected]
+git remote add gh-pages ./.build
+cd ./.build
+git init
+git checkout -b gh-pages
+git config receive.denyCurrentBranch ignore
+cd -
+
+# build documentation for main branch
+poetry run mike deploy --push --remote gh-pages dev
+
+# build documentation for 8.x
+git checkout tags/8.2.2
+poetry run mike deploy --push --remote gh-pages --update-aliases 8.2.2 latest
+poetry run mike set-default --push latest
+
+# build documentation for 9.x
+git checkout 9.0 # currently a branch, will be a tag later on
+poetry run mike deploy --push --remote gh-pages 9.0-BETA
+
+# clean fake remote
+cd ./.build
+git reset --hard gh-pages
+cd -

.github/workflows/documentation.yml

@@ -45,28 +45,16 @@ jobs:
         id: pages
         uses: actions/configure-pages@v4
 
-      - name: Build documentation for 8.x
-        run: poetry run mike deploy --push --update-aliases dev
+      - name: Build documentation
+        run: ./.github/scripts/build-documentation.sh
 
-      - name: Checkout latest 8.x tag
-        run: git checkout tags/8.2.2
-
-      - name: Build documentation for 8.x
-        run: poetry run mike deploy --push --update-aliases 8.2.2 latest
-
-      - name: Checkout latest 8.x tag
-        run: git checkout 9.0 # currently a branch, will be a tag later on
-
-      - name: Build documentation for 9.x
-        run: poetry run mike deploy --push --update-aliases 9.0-BETA
-
-      - name: Flag default version
-        run: mike set-default --push latest
+      - name: Check
+        run: ls ./.build
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./site
+          path: ./.build
 
   deploy:
     name: Deploy to GitHub Pages

.gitignore

@@ -4,4 +4,5 @@ vendor/
 .phpunit.result.cache
 tests/cache/
 tools/phpstan/cache/
-site/
+site/
+.build/

docs/assets/javascripts/version-select.js

@@ -0,0 +1,59 @@
+window.addEventListener("DOMContentLoaded", function() {
+    if (document.querySelector('.md-version')) {
+        return
+    }
+
+    const originUrl = window.location.origin
+    const fullUrl = window.location.href
+
+    const rawDiff = fullUrl.split(originUrl).join('')
+    const currentVersionInUrl = rawDiff.substring(1, rawDiff.length - 1)
+
+    fetch(`${originUrl}/versions.json`)
+        .then((response) => response.json())
+
+        /**
+         * @typedef {Object} Version
+         * @property {string} version
+         * @property {string} title
+         * @property {string[]} aliases
+         *
+         * @type {Version[]}
+         */
+        .then((versions) => {
+            /**
+             * @type {Version}
+             */
+            let currentVersion = false
+            versions.forEach((current) => {
+                if (current.version === currentVersionInUrl ||
+                    current.aliases.indexOf(currentVersionInUrl) > -1) {
+                    currentVersion = current
+                }
+            })
+
+            if (!currentVersion) {
+                return
+            }
+
+            let output = '<div class="md-version">'
+            output = output.concat(`<button class="md-version__current" aria-label="Select version">${currentVersion.title}</button>`)
+            output = output.concat('<ul class="md-version__list">')
+
+            versions.forEach((current) => {
+                let title = current.title;
+                if (current.aliases.length > 0) {
+                    title = title.concat(' (', current.aliases.join(', '), ')');
+                }
+
+                output = output.concat(`<li class="md-version__item"><a href="${originUrl}/${current.version}/" class="md-version__link">${title}</a></li>`)
+            })
+
+            output = output.concat('</ul></div>')
+
+            const selectContainer = document.createElement('div')
+            selectContainer.classList.add('md-version')
+            selectContainer.innerHTML = output
+            document.querySelector('.md-header__topic').append(selectContainer)
+        })
+})

mkdocs.yaml

@@ -65,6 +65,7 @@ extra:
   generator: false
   version:
     provider: mike
+    version_selector: false
 
 markdown_extensions:
   - admonition
@@ -87,5 +88,7 @@ plugins:
 
 extra_javascript:
   - assets/javascripts/highlight.min.js
+  - path: assets/javascripts/version-select.js
+    defer: true
 extra_css:
   - assets/stylesheets/highlight-github.min.css