⚙️ [Maintenance]: Minor docs-site switch to Zensical (#403)

This PR finalizes the documentation pipeline as a clean-cut Zensical
implementation and removes legacy Material/MkDocs fallback behavior.

- Fixes #337

## Changed: Build-Site now runs as Zensical-only

`Build-Site` resolves site configuration from `zensical.toml` and no
longer uses MkDocs compatibility paths.

## Changed: Workflow logic moved to internal actions

Multi-line workflow scripts were extracted into internal composite
actions with script files in `src/` so workflow behavior stays
code-backed and toolable.

## Changed: Shared site script injection is centralized

Navigation-state behavior is injected from framework-owned script files,
replacing repo-local inline payload patterns.

## Technical Details

- Added/updated internal actions for install, site structuring, build,
and script injection.
- Added framework-level site injector scripts under
`.github/scripts/site-injectors/`.
- Updated workflow/action definitions to remove long inline script
blocks.
- Added comment-based help and parameter documentation to newly
introduced PowerShell entry scripts.

## Validation

- Linter checks pass, including `GITHUB_ACTIONS_ZIZMOR`, `BIOME_LINT`,
and `JAVASCRIPT_PRETTIER`.
- Workflow test matrix passes for default and manifest scenarios.
- Downstream verification was completed in
`MariusStorhaug/MariusTestModule` with a merged follow-up (`#56`) and
successful PR/main workflow runs.

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.github/actions/Build-PSModule/action.yml

@@ -40,9 +40,7 @@ runs:
         PSMODULE_BUILD_PSMODULE_INPUT_OutputFolder: ${{ inputs.OutputFolder }}
         PSMODULE_BUILD_PSMODULE_INPUT_Version: ${{ inputs.Version }}
         PSMODULE_BUILD_PSMODULE_INPUT_Prerelease: ${{ inputs.Prerelease }}
-      run: |
-        # Build-PSModule
-        ${{ github.action_path }}/src/main.ps1
+      run: ${{ github.action_path }}/src/main.ps1
 
     - name: Upload module artifact
       uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

.github/actions/Build-ZensicalSite/README.md

@@ -0,0 +1,16 @@
+# Build-ZensicalSite
+
+Builds Zensical documentation site output and normalizes it to `<working-directory>/_site`.
+
+## Inputs
+
+- `WorkingDirectory` (required): Build working directory.
+
+## Usage
+
+```yaml
+- name: Build documentation site with Zensical
+  uses: ./_wf/.github/actions/Build-ZensicalSite
+  with:
+    WorkingDirectory: .
+```

.github/actions/Build-ZensicalSite/action.yml

@@ -0,0 +1,16 @@
+name: Build-ZensicalSite
+description: Build Zensical site output and normalize output folder.
+
+inputs:
+  WorkingDirectory:
+    description: Working directory for the repository build.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Build documentation site
+      shell: pwsh
+      env:
+        INPUT_WORKING_DIRECTORY: ${{ inputs.WorkingDirectory }}
+      run: '& "${{ github.action_path }}/src/main.ps1" -WorkingDirectory "$env:INPUT_WORKING_DIRECTORY"'

.github/actions/Build-ZensicalSite/src/build-zensical-site.ps1

@@ -0,0 +1,29 @@
+param(
+    [Parameter(Mandatory)]
+    [string]$WorkingDirectory
+)
+
+$ErrorActionPreference = 'Stop'
+
+$resolvedWorkingDirectory = Resolve-Path -Path $WorkingDirectory | Select-Object -ExpandProperty Path
+$siteWorkingDirectory = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'outputs/site'
+$outputSitePath = Join-Path -Path $resolvedWorkingDirectory -ChildPath '_site'
+
+Set-Location -Path $siteWorkingDirectory
+
+if (-not (Test-Path -Path 'zensical.toml')) {
+    throw "No documentation config file found in outputs/site. Expected zensical.toml."
+}
+
+zensical build --config-file 'zensical.toml'
+
+if (Test-Path -Path '_site') {
+    if (Test-Path -Path $outputSitePath) {
+        Remove-Item -Path $outputSitePath -Recurse -Force
+    }
+    Move-Item -Path '_site' -Destination $outputSitePath -Force
+}
+
+if (-not (Test-Path -Path $outputSitePath)) {
+    throw "Expected Zensical output at $outputSitePath but it was not created."
+}

.github/actions/Build-ZensicalSite/src/main.ps1

@@ -0,0 +1,50 @@
+#Requires -Version 7.0
+
+<#
+    .SYNOPSIS
+    Builds the Zensical site and normalizes output to the expected _site path.
+
+    .DESCRIPTION
+    Runs zensical build from outputs/site and moves the generated _site directory
+    to <WorkingDirectory>/_site for downstream workflow steps.
+
+    .EXAMPLE
+    ./main.ps1 -WorkingDirectory '.'
+
+    .INPUTS
+    None.
+
+    .OUTPUTS
+    None.
+#>
+[CmdletBinding()]
+param(
+    # Build working directory containing outputs/site and destination _site.
+    [Parameter(Mandatory)]
+    [string]$WorkingDirectory
+)
+
+$ErrorActionPreference = 'Stop'
+
+$resolvedWorkingDirectory = Resolve-Path -Path $WorkingDirectory | Select-Object -ExpandProperty Path
+$siteWorkingDirectory = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'outputs/site'
+$outputSitePath = Join-Path -Path $resolvedWorkingDirectory -ChildPath '_site'
+
+Set-Location -Path $siteWorkingDirectory
+
+if (-not (Test-Path -Path 'zensical.toml')) {
+    throw "No documentation config file found in outputs/site. Expected zensical.toml."
+}
+
+zensical build --config-file 'zensical.toml'
+
+if (Test-Path -Path '_site') {
+    if (Test-Path -Path $outputSitePath) {
+        Remove-Item -Path $outputSitePath -Recurse -Force
+    }
+    Move-Item -Path '_site' -Destination $outputSitePath -Force
+}
+
+if (-not (Test-Path -Path $outputSitePath)) {
+    throw "Expected Zensical output at $outputSitePath but it was not created."
+}

.github/actions/Cleanup-PSModulePrereleases/action.yml

@@ -29,6 +29,4 @@ runs:
       env:
         PSMODULE_CLEANUP_PSMODULEPRERELEASES_INPUT_WhatIf: ${{ inputs.WhatIf }}
         PSMODULE_CLEANUP_PSMODULEPRERELEASES_CONTEXT_ReleaseTag: ${{ env.PSMODULE_PUBLISH_PSMODULE_CONTEXT_ReleaseTag }}
-      run: |
-        # Cleanup prerelease tags
-        ${{ github.action_path }}/src/cleanup.ps1
+      run: ${{ github.action_path }}/src/cleanup.ps1

.github/actions/Cleanup-PSModulePrereleases/src/cleanup.ps1

@@ -3,7 +3,7 @@ param()
 
 $PSStyle.OutputRendering = 'Ansi'
 
-Import-Module -Name 'Helpers' -Force
+Import-Module -Name 'PSModule' -Force
 
 #region Load inputs
 LogGroup 'Load inputs' {

.github/actions/Document-PSModule/action.yml

@@ -27,6 +27,4 @@ runs:
         DOCUMENT_PSMODULE_INPUT_Name: ${{ inputs.Name }}
         DOCUMENT_PSMODULE_INPUT_ShowSummaryOnSuccess: ${{ inputs.ShowSummaryOnSuccess }}
       working-directory: ${{ inputs.WorkingDirectory }}
-      run: |
-        # Build-PSModuleDocumentation
-        ${{ github.action_path }}/src/main.ps1
+      run: ${{ github.action_path }}/src/main.ps1

.github/actions/Expose-TestData/action.yml

@@ -20,5 +20,4 @@ runs:
       shell: pwsh
       env:
         PSMODULE_TEST_DATA: ${{ inputs.TestData }}
-      run: |
-        Import-TestData
+      run: Import-TestData

.github/actions/Inject-SiteScripts/README.md

@@ -0,0 +1,18 @@
+# Inject-SiteScripts
+
+Injects JavaScript snippets from `.github/scripts/site-injectors/*.js` into generated HTML files.
+
+## Inputs
+
+- `SitePath` (required): Path to generated site output.
+- `WorkflowPath` (optional, default `_wf`): Path where workflow repository is checked out.
+
+## Usage
+
+```yaml
+- name: Inject shared site scripts
+  uses: ./_wf/.github/actions/Inject-SiteScripts
+  with:
+    SitePath: ./_site
+    WorkflowPath: _wf
+```