Merge pull request #25 from ONS-Innovation/mkdocs_refresh

KEH-893 | MkDocs Refresh

Author: TotalDwarf03

.github/workflows/deploy_mkdocs.yml

@@ -1,43 +1,32 @@
-# Simple workflow for deploying static content to GitHub Pages
-name: Deploy static content to Pages
-
+# A GitHub Actions workflow to deploy MkDocs documentation to GitHub Pages on push to the master or main branch.
+---
+name: Deploy MkDocs
 on:
-  # Runs on pushes targeting the default branch
   push:
-    branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    branches:
+      - master 
+      - main
 permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
+  contents: write
 jobs:
-  # Single deploy job since we're just deploying
   deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
         with:
-          # Upload entire repository
-          path: './mkdocs_deployment'
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache 
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: pip install -r mkdocs_requirements.txt
+      - run: mkdocs gh-deploy --force

docs/documentation.md

@@ -48,20 +48,22 @@ In order to build an MkDocs deployment or serve the documentation locally, we ne
 
 ## Updating MkDocs Deployment
 
+### GitHub Action to Deploy Documentation
+
+A GitHub Action is set up to automatically deploy the documentation to GitHub Pages whenever a commit is made to the `main` branch. This action is triggered by a push event to the `main` branch and runs the `mkdocs gh-deploy` command to build and deploy the documentation.
+
+### Manual Deployment
+
 If changes are made within `/docs`, the GitHub Pages deployment will need to be updated. Assuming you have already installed [MkDocs](https://www.mkdocs.org/getting-started/#installation) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/getting-started/#installation), do the following:
 
 1. Navigate to the projects root directory.
 
-2. Delete the existing `/mkdocs_deployment` directory.
-
-3. Build the MkDocs deployment.
+2. Deploy the documentation to GitHub Pages.
 
     ```bash
-    mkdocs build
+    mkdocs gh-deploy
     ```
 
-4. Rename the `/site` directory to `/mkdocs_deployment`. This allows git to track the build so GitHub Pages can redeploy it.
-
-5. Commit and Push changes.
+3. This will build the documentation and deploy it to the `gh-pages` branch of your repository. The documentation will be available at `https://ONS-Innovation.github.io/<repository-name>/`.
 
-Once completed, a GitHub Action will redeploy the new build to GitHub Pages.
+**Please Note:** The `gh-deploy` command will overwrite the `gh-pages` branch and make the local changes available on GitHub Pages. Make sure that these changes are appropriate and have been reviewed before deployment.