docs: switch the user guide to Markdown

.gitattributes

@@ -21,7 +21,6 @@ utils/                       export-ignore
 .php-cs-fixer.dist.php       export-ignore
 .php-cs-fixer.no-header.php  export-ignore
 .php-cs-fixer.tests.php      export-ignore
-.php-cs-fixer.user-guide.php export-ignore
 structarmed-baseline.php     export-ignore
 structarmed.php              export-ignore
 phpstan-baseline.php         export-ignore
@@ -35,8 +34,6 @@ rector.php                   export-ignore
 AGENTS.md                    export-ignore
 
 # source user guide
-user_guide_src/ export-ignore
 docs/           export-ignore
 mkdocs.yml      export-ignore
-.nojekyll       export-ignore
 phpdoc.dist.xml export-ignore

.github/scripts/deploy-userguide

@@ -33,9 +33,11 @@ echo "Merging files from $1 to $2"
 # Prepare the source
 cd $SOURCE
 git checkout master
-cd user_guide_src
-make html
-make epub
+export NO_MKDOCS_2_WARNING=1
+export SITE_URL=https://codeigniter.com/user_guide/
+mkdocs build --strict
+python admin/llms.py
+python admin/anchors.py
 
 # Prepare the target
 cd $TARGET
@@ -49,11 +51,7 @@ cp -Rf ${SOURCE}/LICENSE ./
 cp -Rf ${SOURCE}/admin/userguide/. ./
 
 # Copy files
-cp -Rf ${SOURCE}/user_guide_src/build/html ./docs
-cp -Rf ${SOURCE}/user_guide_src/build/epub/CodeIgniter.epub ./CodeIgniter${VERSION}.epub
-
-# Ensure underscore prefixed files are published
-touch ${TARGET}/docs/.nojekyll
+cp -Rf ${SOURCE}/site ./docs
 
 # Commit the changes
 git add .

.github/workflows/deploy-distributables.yml

@@ -176,10 +176,10 @@ jobs:
         with:
           python-version: '3.12'
 
-      - name: Install Sphinx
+      - name: Install MkDocs
         run: |
           python -m pip install --upgrade pip
-          pip install -r ./source/user_guide_src/requirements.txt
+          pip install -r ./source/docs/requirements.txt
 
       - name: Chmod
         run: chmod +x ./source/.github/scripts/deploy-userguide

.github/workflows/deploy-userguide-latest.yml

@@ -1,83 +1,101 @@
 # When changes are pushed to the develop branch,
-# build the current version of the User Guide
-# with Sphinx and deploy it to the gh-pages branch.
-#
-# @todo Consolidate checkouts
+# build the develop and the next minor versions of the User Guide
+# with MkDocs and deploy them to GitHub Pages.
 name: Deploy User Guide (latest)
 
 on:
   push:
     branches:
       - 'develop'
     paths:
-      - 'user_guide_src/**'
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'admin/anchors.py'
+      - 'admin/llms.py'
+      - '.github/workflows/deploy-userguide-latest.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 permissions:
   contents: read
 
 jobs:
   build:
-    name: Deploy to gh-pages
-    permissions:
-      # Allow push to branch gh-pages
-      contents: write
+    name: Build User Guide
     if: (github.repository == 'codeigniter4/CodeIgniter4')
     runs-on: ubuntu-24.04
     steps:
-      - name: Checkout
+      - name: Checkout develop
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
+          path: develop
           persist-credentials: false
 
-      - name: Setup PHP
-        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
+      - name: Checkout next minor
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          php-version: '8.2'
-          coverage: none
+          ref: '4.8'
+          path: next
+          persist-credentials: false
 
       - name: Setup Python
         uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: '3.12'
 
-      - name: Install Sphinx
+      - name: Install MkDocs
         run: |
           python -m pip install --upgrade pip
-          pip install -r user_guide_src/requirements.txt
+          pip install -r develop/docs/requirements.txt
 
-      # Build the latest User Guide
-      - name: Build Docs with Sphinx
-        run: make html
-        working-directory: user_guide_src
+      - name: Setup Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
 
-      - name: Add "Edit this page" links
+      - name: Build the sites
+        env:
+          NO_MKDOCS_2_WARNING: '1'
+          BASE_URL: https://codeigniter4.github.io/CodeIgniter4
         run: |
-          cd user_guide_src
-          # Fix permissions
-          sudo chown -R runner:docker build/html/
-          php add-edit-this-page build/html/
+          mkdir pages
+
+          for name in develop next; do
+            if [ ! -f "${name}/mkdocs.yml" ]; then
+              echo "::notice::The ${name} branch has no mkdocs.yml, so it is not deployed."
+              continue
+            fi
+
+            (
+              cd "${name}"
+              SITE_URL="${BASE_URL}/${name}/" mkdocs build --strict
+              python admin/llms.py
+              python admin/anchors.py
+            )
+
+            mv "${name}/site" "pages/${name}"
+          done
+
+          cp develop/docs/overrides/assets/versions.json pages/versions.json
+          echo '<!doctype html><meta http-equiv="refresh" content="0; url=develop/">' > pages/index.html
 
-      # Create an artifact of the html output
       - name: Upload artifact
-        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
-          name: HTML Documentation
-          path: user_guide_src/build/html/
-
-      # Commit changes to the gh-pages branch
-      - name: Commit changes
-        run: |
-          git clone https://github.com/codeigniter4/CodeIgniter4.git --branch gh-pages --single-branch gh-pages
-          cp -r user_guide_src/build/html/* gh-pages/
-          cd gh-pages
-          git config --local user.email "action@github.com"
-          git config --local user.name "${GITHUB_ACTOR}"
-          git add .
-          # Ignore failures due to lack of changes
-          git commit -m "Update User Guide" -a || true
+          path: pages
 
-      - name: Push changes
-        working-directory: gh-pages
-        env:
-          PUSH_TOKEN: ${{ secrets.ACCESS_TOKEN }}
-        run: bash ${GITHUB_WORKSPACE}/.github/scripts/secure-git-push https://github.com/codeigniter4/CodeIgniter4.git HEAD:gh-pages
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.github/workflows/test-userguide.yml

@@ -1,13 +1,12 @@
 # When a Pull Request is opened that modifies
 # the User Guide source, build the User Guide
-# with Sphinx or MkDocs and let the contributor
+# with MkDocs and let the contributor
 # know of any errors.
 name: Test User Guide
 
 on:
   pull_request:
     paths:
-      - 'user_guide_src/**'
       - 'docs/**'
       - 'mkdocs.yml'
       - 'admin/anchors.py'
@@ -23,33 +22,8 @@ permissions:
   contents: read
 
 jobs:
-  syntax_check:
-    name: Check User Guide syntax
-    runs-on: ubuntu-24.04
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Setup Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
-        with:
-          python-version: '3.12'
-
-      - name: Install Sphinx
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r user_guide_src/requirements.txt
-
-      - name: Detect usage of tabs in RST files
-        run: php utils/check_tabs_in_rst.php
-
-      - name: Build Docs with Sphinx
-        run: make html SPHINXOPTS="-W --keep-going -w /tmp/sphinx-log"
-        working-directory: user_guide_src
-
   markdown_check:
-    name: Check Markdown User Guide
+    name: Check User Guide
     runs-on: ubuntu-24.04
 
     steps:

.github/workflows/verify-release.yml

@@ -1,6 +1,6 @@
 # When a release is published, verify that the release pipeline delivered
 # everything: the distributable repos, the new framework version on
-# Packagist, and the user guide with its ePub.
+# Packagist, and the user guide.
 #
 # Use "Run workflow" with the release tag to verify an existing release.
 name: Verify Release
@@ -123,23 +123,21 @@ jobs:
     timeout-minutes: 30
 
     steps:
-      - name: Check that the ePub was added
+      - name: Check that the user guide was added
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          version="${TAG#v}"
-
           for i in $(seq 1 30); do
-            if gh api "repos/codeigniter4/userguide/contents/CodeIgniter${version}.epub" --jq '.name' > /dev/null 2>&1; then
-              echo "CodeIgniter${version}.epub is in the userguide repo."
+            if gh api "repos/codeigniter4/userguide/contents/docs/llms.txt" --jq '.name' > /dev/null 2>&1; then
+              echo "docs/llms.txt is in the userguide repo."
               exit 0
             fi
 
-            echo "Attempt ${i}: CodeIgniter${version}.epub is not yet in the userguide repo."
+            echo "Attempt ${i}: docs/llms.txt is not yet in the userguide repo."
             sleep 30
           done
 
-          echo "Timed out waiting for CodeIgniter${version}.epub."
+          echo "Timed out waiting for docs/llms.txt."
           exit 1
 
       - name: Check that the user guide workflows succeeded

.php-cs-fixer.dist.php

@@ -30,7 +30,6 @@
         __FILE__,
         __DIR__ . '/.php-cs-fixer.no-header.php',
         __DIR__ . '/.php-cs-fixer.tests.php',
-        __DIR__ . '/.php-cs-fixer.user-guide.php',
         __DIR__ . '/preload.php',
         __DIR__ . '/rector.php',
         __DIR__ . '/spark',