Update documentation build workflows and Dockerfiles to use latest versions of DocFX and .NET

.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

.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

.gitignore

@@ -151,6 +151,7 @@ publish/
 
 # Local .NET tools installed by signing workflows
 /.store/
+/.tools/
 /sign
 /sign.exe
 

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}

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}"

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

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.

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

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"> 

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">