⚙️ [Maintenance]: Minor docs-site switch to Zensical

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

@@ -40,9 +40,7 @@
         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,14 @@
+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
+      run: '& "${{ github.action_path }}/src/main.ps1" -WorkingDirectory "${{ inputs.WorkingDirectory }}"'

.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,32 @@
+#Requires -Version 7.0
+
+[CmdletBinding()]
+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/Cleanup-PSModulePrereleases/action.yml

@@ -29,6 +29,4 @@
       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 @@
         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
+```

.github/actions/Inject-SiteScripts/action.yml

@@ -0,0 +1,18 @@
+name: Inject-SiteScripts
+description: Inject shared JavaScript snippets into generated site HTML files.
+
+inputs:
+  SitePath:
+    description: Path to the generated site output directory.
+    required: true
+  WorkflowPath:
+    description: Path to the checked out workflow repository root.
+    required: false
+    default: _wf
+
+runs:
+  using: composite
+  steps:
+    - name: Inject site scripts
+      shell: pwsh
+      run: '& "${{ github.action_path }}/src/main.ps1" -SitePath "${{ inputs.SitePath }}" -WorkflowPath "${{ inputs.WorkflowPath }}"'

.github/actions/Inject-SiteScripts/src/inject-site-scripts.ps1

@@ -0,0 +1,41 @@
+param(
+    [Parameter(Mandatory)]
+    [string]$SitePath,
+
+    [Parameter(Mandatory)]
+    [string]$WorkflowPath
+)
+
+$resolvedSitePath = Resolve-Path -Path $SitePath -ErrorAction Stop | Select-Object -ExpandProperty Path
+$injectorsPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath "$WorkflowPath/.github/scripts/site-injectors"
+
+if (-not (Test-Path -Path $injectorsPath)) {
+    throw "Expected site injector folder at $injectorsPath but it was not found."
+}
+
+$injectorScripts = Get-ChildItem -Path $injectorsPath -File -Filter '*.js' | Sort-Object -Property Name
+if (-not $injectorScripts) {
+    Write-Host "No site injector scripts found under $injectorsPath."
+    exit 0
+}
+
+Get-ChildItem -Path $resolvedSitePath -Filter '*.html' -Recurse | ForEach-Object {
+    $html = Get-Content -Path $_.FullName -Raw
+    $modified = $false
+
+    foreach ($injectorScript in $injectorScripts) {
+        $marker = "data-psmodule-site-injector=""$($injectorScript.Name)"""
+        if ($html -match [Regex]::Escape($marker)) {
+            continue
+        }
+
+        $scriptContent = Get-Content -Path $injectorScript.FullName -Raw
+        $injectedScript = "<script $marker>$scriptContent</script>"
+        $html = $html -replace '</body>', "$injectedScript`n</body>"
+        $modified = $true
+    }
+
+    if ($modified) {
+        Set-Content -Path $_.FullName -Value $html -NoNewline
+    }
+}

.github/actions/Inject-SiteScripts/src/main.ps1

@@ -0,0 +1,44 @@
+#Requires -Version 7.0
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [string]$SitePath,
+
+    [Parameter(Mandatory)]
+    [string]$WorkflowPath
+)
+
+$resolvedSitePath = Resolve-Path -Path $SitePath -ErrorAction Stop | Select-Object -ExpandProperty Path
+$injectorsPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath "$WorkflowPath/.github/scripts/site-injectors"
+
+if (-not (Test-Path -Path $injectorsPath)) {
+    throw "Expected site injector folder at $injectorsPath but it was not found."
+}
+
+$injectorScripts = Get-ChildItem -Path $injectorsPath -File -Filter '*.js' | Sort-Object -Property Name
+if (-not $injectorScripts) {
+    Write-Host "No site injector scripts found under $injectorsPath."
+    exit 0
+}
+
+Get-ChildItem -Path $resolvedSitePath -Filter '*.html' -Recurse | ForEach-Object {
+    $html = Get-Content -Path $_.FullName -Raw
+    $modified = $false
+
+    foreach ($injectorScript in $injectorScripts) {
+        $marker = "data-psmodule-site-injector=""$($injectorScript.Name)"""
+        if ($html -match [Regex]::Escape($marker)) {
+            continue
+        }
+
+        $scriptContent = Get-Content -Path $injectorScript.FullName -Raw
+        $injectedScript = "<script $marker>$scriptContent</script>"
+        $html = $html -replace '</body>', "$injectedScript`n</body>"
+        $modified = $true
+    }
+
+    if ($modified) {
+        Set-Content -Path $_.FullName -Value $html -NoNewline
+    }
+}

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

@@ -6,6 +6,4 @@
   steps:
     - name: Install-PSModule
       shell: pwsh
-      run: |
-        # Install-PSModule
-        ${{ github.action_path }}/src/main.ps1
+      run: ${{ github.action_path }}/src/main.ps1

.github/actions/Install-Zensical/README.md

@@ -0,0 +1,14 @@
+# Install-Zensical
+
+Installs the Zensical CLI used by site build workflows.
+
+## Inputs
+
+None.
+
+## Usage
+
+```yaml
+- name: Install Zensical
+  uses: ./_wf/.github/actions/Install-Zensical
+```

.github/actions/Install-Zensical/action.yml

@@ -0,0 +1,9 @@
+name: Install-Zensical
+description: Install Zensical CLI used for documentation site generation.
+
+runs:
+  using: composite
+  steps:
+    - name: Install Zensical CLI
+      shell: pwsh
+      run: '& "${{ github.action_path }}/src/main.ps1"'

.github/actions/Install-Zensical/src/install-zensical.ps1

@@ -0,0 +1,3 @@
+$ErrorActionPreference = 'Stop'
+
+pip install zensical

.github/actions/Install-Zensical/src/main.ps1

@@ -0,0 +1,8 @@
+#Requires -Version 7.0
+
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+
+pip install zensical

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

@@ -46,8 +46,7 @@ runs:
 
     - name: Update Microsoft.PowerShell.PSResourceGet
       shell: pwsh
-      run: |
-        Install-PSResource -Name Microsoft.PowerShell.PSResourceGet -Repository PSGallery -TrustRepository
+      run: Install-PSResource -Name Microsoft.PowerShell.PSResourceGet -Repository PSGallery -TrustRepository
 
     - name: Download module artifact
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

.github/actions/Publish-PSModule/src/publish.ps1

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

.github/actions/Resolve-PSModuleVersion/action.yml

@@ -58,8 +58,7 @@
 
     - name: Install PSSemVer
       shell: pwsh
-      run: |
-        Install-PSResource -Name PSSemVer -Repository PSGallery -TrustRepository
+      run: Install-PSResource -Name PSSemVer -Repository PSGallery -TrustRepository
 
     - name: Resolve module version
       id: resolve
@@ -71,6 +70,4 @@
         PSMODULE_RESOLVE_PSMODULEVERSION_INPUT_Name: ${{ inputs.Name }}
         PSMODULE_RESOLVE_PSMODULEVERSION_INPUT_EventJson: ${{ inputs.EventJson }}
         GITHUB_EVENT_PATH: ${{ inputs.EventPath || github.event_path }}
-      run: |
-        # Resolve module version
-        ${{ github.action_path }}/src/main.ps1
+      run: ${{ github.action_path }}/src/main.ps1

.github/actions/Structure-Site/README.md

@@ -0,0 +1,18 @@
+# Structure-Site
+
+Prepares site content and writes a resolved Zensical config file under `outputs/site`.
+
+## Inputs
+
+- `WorkingDirectory` (required): Build working directory.
+- `Name` (optional): Module name override.
+
+## Usage
+
+```yaml
+- name: Structure site
+  uses: ./_wf/.github/actions/Structure-Site
+  with:
+    WorkingDirectory: .
+    Name: MyModule
+```

.github/actions/Structure-Site/action.yml

@@ -0,0 +1,18 @@
+name: Structure-Site
+description: Structure generated docs and create site config for Zensical.
+
+inputs:
+  WorkingDirectory:
+    description: Working directory for the repository build.
+    required: true
+  Name:
+    description: Optional module name override.
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - name: Structure site content and config
+      shell: pwsh
+      run: '& "${{ github.action_path }}/src/main.ps1" -WorkingDirectory "${{ inputs.WorkingDirectory }}" -Name "${{ inputs.Name }}"'