From 83d590e790c2c2c3163bcbeef18b08dfccf531cd Mon Sep 17 00:00:00 2001
From: Gautam Sheth <gautamdsheth@outlook.com>
Date: Thu, 21 May 2026 22:53:36 +0300
Subject: [PATCH 1/2] Update documentation build workflows and Dockerfiles to
 use latest versions of DocFX and .NET

---
 .github/workflows/builddocsite.yml            | 19 ++++++++++++-------
 .github/workflows/checkdocumentationbuild.yml | 13 +++++++++----
 pages/Dockerfile-Linux                        |  9 ++++-----
 pages/Dockerfile-Windows                      | 11 +++++++----
 pages/articles/buildingdocker.md              |  6 +++---
 .../material/partials/head.tmpl.partial       |  2 +-
 .../material/partials/scripts.tmpl.partial    |  2 +-
 7 files changed, 37 insertions(+), 25 deletions(-)

diff --git a/.github/workflows/builddocsite.yml b/.github/workflows/builddocsite.yml
index 3e08d07ed3..2d88a6fccd 100644
--- a/.github/workflows/builddocsite.yml
+++ b/.github/workflows/builddocsite.yml
@@ -7,6 +7,10 @@ on:
 
 permissions: read-all
 
+env:
+  DOCFX_VERSION: 2.78.5
+  DOTNET_VERSION: 10.x
+
 jobs:
   documentation:
     runs-on: ubuntu-latest
@@ -18,26 +22,27 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Checkout master branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: master
           path: master
       - name: Checkout dev branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: dev
           path: dev
       - name: Checkout gh-pages branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: gh-pages
           path: gh-pages
-      - name: Setup .NET 7.0
-        uses: actions/setup-dotnet@v4
+      - name: Setup .NET 10.0
+        uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: 7.x
+          dotnet-version: ${{ env.DOTNET_VERSION }}
       
-      - run: dotnet tool install -g docfx --version 2.72.1
+      - name: Install DocFX
+        run: dotnet tool install -g docfx --version ${{ env.DOCFX_VERSION }}
       
       - name: Build docs
         shell: pwsh
diff --git a/.github/workflows/checkdocumentationbuild.yml b/.github/workflows/checkdocumentationbuild.yml
index 846e437985..8ec8c14f1e 100644
--- a/.github/workflows/checkdocumentationbuild.yml
+++ b/.github/workflows/checkdocumentationbuild.yml
@@ -10,6 +10,10 @@ on:
 
 permissions: read-all
 
+env:
+  DOCFX_VERSION: 2.78.5
+  DOTNET_VERSION: 10.x
+
 jobs:
   docfx:
     
@@ -27,12 +31,13 @@ jobs:
         with:
           ref: gh-pages
           path: gh-pages
-      - name: Setup .NET 7.0
-        uses: actions/setup-dotnet@v4
+      - name: Setup .NET 10.0
+        uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: 7.x
+          dotnet-version: ${{ env.DOTNET_VERSION }}
       
-      - run: dotnet tool install -g docfx --version 2.72.1
+      - name: Install DocFX
+        run: dotnet tool install -g docfx --version ${{ env.DOCFX_VERSION }}
       
       - name: Build docs
         shell: pwsh
diff --git a/pages/Dockerfile-Linux b/pages/Dockerfile-Linux
index 6cceeb35b5..4134ebc245 100644
--- a/pages/Dockerfile-Linux
+++ b/pages/Dockerfile-Linux
@@ -1,6 +1,5 @@
-FROM mono:6.12.0.182
+FROM mcr.microsoft.com/dotnet/sdk:10.0
 
-RUN apt update && apt upgrade -y && apt install wget unzip -y;
-RUN wget wget https://github.com/dotnet/docfx/releases/download/v2.51/docfx.zip; \
-    unzip docfx.zip -d /usr/local/lib/docfx; \
-    chmod +x /usr/local/lib/docfx/docfx.exe; \
+ARG DOCFX_VERSION=2.78.5
+
+RUN dotnet tool install docfx --tool-path /usr/local/bin --version ${DOCFX_VERSION}
diff --git a/pages/Dockerfile-Windows b/pages/Dockerfile-Windows
index 5ad0eb953d..b23131814a 100644
--- a/pages/Dockerfile-Windows
+++ b/pages/Dockerfile-Windows
@@ -1,6 +1,9 @@
-FROM mcr.microsoft.com/windows/servercore:10.0.17763.2366-amd64
+FROM mcr.microsoft.com/dotnet/sdk:10.0-windowsservercore-ltsc2022
 
 SHELL ["powershell", "-command"]
-RUN $ProgressPreference = 'SilentlyContinue'; \
-    Invoke-WebRequest https://github.com/dotnet/docfx/releases/download/v2.51/docfx.zip -OutFile $env:TEMP\docfx.zip; \
-    Expand-Archive $env:TEMP\docfx.zip $env:TEMP\docfx;
+
+ARG DOCFX_VERSION=2.78.5
+
+RUN dotnet tool install docfx --tool-path C:\tools\docfx --version $env:DOCFX_VERSION
+
+ENV PATH="C:\tools\docfx;${PATH}"
diff --git a/pages/articles/buildingdocker.md b/pages/articles/buildingdocker.md
index ecb661e783..c4e76daa2a 100644
--- a/pages/articles/buildingdocker.md
+++ b/pages/articles/buildingdocker.md
@@ -11,7 +11,7 @@ docker build . -f ./pages/Dockerfile-Linux -t pnp.powershell-pages-build
 ## Build Documentation
 
 ```bash
-docker run --rm -it -v $(pwd)/pages:/home pnp.powershell-pages-build /usr/bin/mono /usr/local/lib/docfx/docfx.exe build /home/docfx.json
+docker run --rm -it -v $(pwd)/pages:/workspace -w /workspace pnp.powershell-pages-build docfx build docfx.json
 ```
 
 ## Clean documentation
@@ -32,7 +32,7 @@ docker build . -f ./pages/Dockerfile-Windows -t pnp.powershell-pages-build
 ## Build Documentation
 
 ```bat
-docker run --rm -it -v %cd%\pages:C:\workplace pnp.powershell-pages-build powershell -c Start-Process -NoNewWindow -FilePath $env:TEMP\docfx\docfx.exe -ArgumentList build, C:\workplace\docfx.json -Wait
+docker run --rm -it -v %cd%\pages:C:\workspace -w C:\workspace pnp.powershell-pages-build docfx build docfx.json
 ```
 
 ## Clean documentation
@@ -53,7 +53,7 @@ docker build . -f ./pages/Dockerfile-Windows -t pnp.powershell-pages-build
 ## Build Documentation
 
 ```powershell
-docker run --rm -it -v ${pwd}\pages:C:\workplace pnp.powershell-pages-build powershell -c "Start-Process -NoNewWindow -FilePath `$env:TEMP\docfx\docfx.exe -ArgumentList build, C:\workplace\docfx.json -Wait"
+docker run --rm -it -v ${pwd}\pages:C:\workspace -w C:\workspace pnp.powershell-pages-build docfx build docfx.json
 ```
 
 ## Clean documentation
diff --git a/pages/templates/material/partials/head.tmpl.partial b/pages/templates/material/partials/head.tmpl.partial
index 94497566a2..7f76dcae13 100644
--- a/pages/templates/material/partials/head.tmpl.partial
+++ b/pages/templates/material/partials/head.tmpl.partial
@@ -9,7 +9,7 @@
   <meta name="generator" content="docfx {{_docfxVersion}}">
   {{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
   <link rel="shortcut icon" href="{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
-  <link rel="stylesheet" href="{{_rel}}styles/docfx.vendor.css">
+  <link rel="stylesheet" href="{{_rel}}styles/docfx.vendor.min.css">
   <link rel="stylesheet" href="{{_rel}}styles/docfx.css">
   <link rel="stylesheet" href="{{_rel}}styles/main.css">
   <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet"> 
diff --git a/pages/templates/material/partials/scripts.tmpl.partial b/pages/templates/material/partials/scripts.tmpl.partial
index 868b25ee92..e40333e309 100644
--- a/pages/templates/material/partials/scripts.tmpl.partial
+++ b/pages/templates/material/partials/scripts.tmpl.partial
@@ -1,6 +1,6 @@
 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
 
-<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
+<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.min.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/main.js"></script>
 <script type="text/javascript">

From 2f7399f620eb3525b67b6b44a0c45312fa7b5c97 Mon Sep 17 00:00:00 2001
From: Gautam Sheth <gautamdsheth@outlook.com>
Date: Thu, 21 May 2026 23:07:21 +0300
Subject: [PATCH 2/2] Add documentation for building the site locally and
 update .gitignore

---
 .gitignore                              |   1 +
 pages/articles/buildingdocumentation.md | 234 ++++++++++++++++++++++++
 pages/articles/toc.yml                  |   2 +
 3 files changed, 237 insertions(+)
 create mode 100644 pages/articles/buildingdocumentation.md

diff --git a/.gitignore b/.gitignore
index fd8cd20da4..b40a2304ca 100644
--- a/.gitignore
+++ b/.gitignore
@@ -151,6 +151,7 @@ publish/
 
 # Local .NET tools installed by signing workflows
 /.store/
+/.tools/
 /sign
 /sign.exe
 
diff --git a/pages/articles/buildingdocumentation.md b/pages/articles/buildingdocumentation.md
new file mode 100644
index 0000000000..41fa94f279
--- /dev/null
+++ b/pages/articles/buildingdocumentation.md
@@ -0,0 +1,234 @@
+---
+uid: buildingdocumentation
+---
+
+# Building the documentation site locally
+
+The documentation site is built with [DocFX](https://dotnet.github.io/docfx/). If you're changing articles, cmdlet documentation, the site template, or the documentation build scripts, it's worth building the site locally before you submit your pull request.
+
+There are two useful ways to test the site locally:
+
+- A quick DocFX build from your current checkout. Use this when you changed articles, images, templates, styles, or `pages/docfx.json`.
+- A full build that follows the same folder layout as the GitHub Actions workflow. Use this when you want to test `Build-Site.ps1`, cmdlet documentation copying, generated alias pages, or the final output that gets copied to the `gh-pages` branch.
+
+The GitHub Actions workflows use DocFX 2.78.5 and the .NET SDK 10. The commands below use the same DocFX version.
+
+## Prerequisites
+
+Install the following tools first:
+
+1. [Git](https://git-scm.com/downloads)
+1. [PowerShell 7](https://learn.microsoft.com/powershell/scripting/install/installing-powershell)
+1. [.NET SDK 10](https://dotnet.microsoft.com/download)
+
+You can validate your installation by running:
+
+```powershell
+git --version
+pwsh --version
+dotnet --version
+```
+
+The full build also needs access to the PowerShell Gallery. During that build, `Build-Site.ps1` installs the latest prerelease version of PnP PowerShell in order to discover aliases and generate documentation pages for them.
+
+## Quick build on Windows
+
+Open PowerShell 7 and navigate to your local clone of the repository.
+
+```powershell
+cd C:\repos\powershell
+```
+
+Install DocFX into a local `.tools` folder. This keeps the version used for this repository separate from any globally installed DocFX version.
+
+```powershell
+New-Item -ItemType Directory -Force .\.tools | Out-Null
+dotnet tool install docfx --tool-path .\.tools --version 2.78.5
+```
+
+If you already have DocFX installed in that folder and want to refresh it to the expected version, run:
+
+```powershell
+dotnet tool update docfx --tool-path .\.tools --version 2.78.5
+```
+
+Build the documentation site:
+
+```powershell
+.\.tools\docfx.exe build .\pages\docfx.json
+```
+
+Serve the generated site locally:
+
+```powershell
+.\.tools\docfx.exe serve .\pages\_site --port 8080
+```
+
+Open http://localhost:8080 in your browser. If port 8080 is already in use, pick another port, for example `--port 8091`.
+
+When you're done, remove the generated output:
+
+```powershell
+Remove-Item .\pages\_site, .\pages\obj -Recurse -Force -ErrorAction SilentlyContinue
+```
+
+## Quick build on macOS or Linux
+
+Open a terminal and navigate to your local clone of the repository.
+
+```bash
+cd ~/repos/powershell
+```
+
+Install DocFX into a local `.tools` folder.
+
+```bash
+mkdir -p .tools
+dotnet tool install docfx --tool-path ./.tools --version 2.78.5
+```
+
+If you already have DocFX installed in that folder and want to refresh it to the expected version, run:
+
+```bash
+dotnet tool update docfx --tool-path ./.tools --version 2.78.5
+```
+
+Build the documentation site:
+
+```bash
+./.tools/docfx build ./pages/docfx.json
+```
+
+Serve the generated site locally:
+
+```bash
+./.tools/docfx serve ./pages/_site --port 8080
+```
+
+Open http://localhost:8080 in your browser. If port 8080 is already in use, pick another port, for example `--port 8091`.
+
+When you're done, remove the generated output:
+
+```bash
+rm -rf ./pages/_site ./pages/obj
+```
+
+## Full build on Windows
+
+The documentation site workflow checks out three branches next to each other: `master`, `dev`, and `gh-pages`. The `Build-Site.ps1` script expects that layout and uses paths such as `./dev/pages` and `./gh-pages`.
+
+From your regular repository checkout, create a temporary worktree layout:
+
+```powershell
+$repo = "C:\repos\powershell"
+$root = "C:\repos\powershell-docs-local"
+
+git -C $repo fetch origin
+New-Item -ItemType Directory -Force $root | Out-Null
+
+git -C $repo worktree add "$root\dev" HEAD
+git -C $repo worktree add "$root\master" origin/master
+git -C $repo worktree add "$root\gh-pages" origin/gh-pages
+```
+
+Install DocFX into the temporary build folder and add it to the current session path so `Build-Site.ps1` can call `docfx`:
+
+```powershell
+Push-Location $root
+
+New-Item -ItemType Directory -Force .\.tools | Out-Null
+dotnet tool install docfx --tool-path .\.tools --version 2.78.5
+$env:PATH = "$(Resolve-Path .\.tools);$env:PATH"
+```
+
+Run the same build script used by the workflow:
+
+```powershell
+.\dev\pages\Build-Site.ps1
+```
+
+Serve the generated site:
+
+```powershell
+.\.tools\docfx.exe serve .\dev\pages\_site --port 8080
+```
+
+Open http://localhost:8080 in your browser and check the pages you changed. Press `CTRL+C` in the terminal when you're done serving the site.
+
+Clean up the worktrees from your original checkout:
+
+```powershell
+Pop-Location
+
+git -C $repo worktree remove "$root\dev" --force
+git -C $repo worktree remove "$root\master" --force
+git -C $repo worktree remove "$root\gh-pages" --force
+Remove-Item $root -Recurse -Force -ErrorAction SilentlyContinue
+```
+
+## Full build on macOS or Linux
+
+The same workflow layout can be created with Git worktrees on macOS or Linux.
+
+```bash
+repo=~/repos/powershell
+root=~/repos/powershell-docs-local
+
+git -C "$repo" fetch origin
+mkdir -p "$root"
+
+git -C "$repo" worktree add "$root/dev" HEAD
+git -C "$repo" worktree add "$root/master" origin/master
+git -C "$repo" worktree add "$root/gh-pages" origin/gh-pages
+```
+
+Install DocFX into the temporary build folder and add it to the current session path:
+
+```bash
+cd "$root"
+
+mkdir -p .tools
+dotnet tool install docfx --tool-path ./.tools --version 2.78.5
+export PATH="$(pwd)/.tools:$PATH"
+```
+
+Run the same build script used by the workflow:
+
+```bash
+pwsh ./dev/pages/Build-Site.ps1
+```
+
+Serve the generated site:
+
+
+```bash
+./.tools/docfx serve ./dev/pages/_site --port 8080
+```
+
+Open http://localhost:8080 in your browser and check the pages you changed. Press `CTRL+C` in the terminal when you're done serving the site.
+
+Clean up the worktrees from your original checkout:
+
+```bash
+git -C "$repo" worktree remove "$root/dev" --force
+git -C "$repo" worktree remove "$root/master" --force
+git -C "$repo" worktree remove "$root/gh-pages" --force
+rm -rf "$root"
+```
+
+## What to check in the browser
+
+At minimum, verify the following:
+
+1. The home page loads and is not blank.
+1. The navigation on the left opens the article or cmdlet page you changed.
+1. Search opens without JavaScript errors.
+1. The browser developer tools do not show 404 responses for `docfx.vendor.min.css` or `docfx.vendor.min.js`.
+
+DocFX 2.77 and newer emit the vendor assets as minified files. If the browser shows 404 responses for `docfx.vendor.css` or `docfx.vendor.js`, the template is still using the old asset names and the site can appear as a blank page.
+
+## Build warnings
+
+DocFX can finish successfully while still reporting warnings. Treat warnings in files you touched as something to fix before submitting your pull request. Existing warnings elsewhere in the site should not block you from validating your local change, but do not introduce new ones.
+
+Common warnings are broken file links, broken bookmarks, or links to generated cmdlet pages that are not present in a quick build. If you need to verify generated cmdlet pages, use the full build.
\ No newline at end of file
diff --git a/pages/articles/toc.yml b/pages/articles/toc.yml
index cd91cb5bb9..972a8cb868 100644
--- a/pages/articles/toc.yml
+++ b/pages/articles/toc.yml
@@ -62,6 +62,8 @@
       href: buildinglocalpnpbuild.md
     - name: Running unit tests
       href: runningtests.md
+    - name: Building the documentation site locally
+      href: buildingdocumentation.md
     - name: Building using docker
       href: buildingdocker.md
     - name: Working with permission attributes