⚙️ [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/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/build-zensical-site.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/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/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/inject-site-scripts.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/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/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/install-zensical.ps1"'

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

@@ -0,0 +1,3 @@
+$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/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/structure-site.ps1" -WorkingDirectory "${{ inputs.WorkingDirectory }}" -Name "${{ inputs.Name }}"'

.github/actions/Structure-Site/src/structure-site.ps1

@@ -0,0 +1,77 @@
+param(
+    [Parameter(Mandatory)]
+    [string]$WorkingDirectory,
+
+    [Parameter()]
+    [string]$Name
+)
+
+$ErrorActionPreference = 'Stop'
+
+$resolvedWorkingDirectory = Resolve-Path -Path $WorkingDirectory | Select-Object -ExpandProperty Path
+$siteOutputPath = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'outputs/site'
+$docsOutputPath = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'outputs/docs'
+$moduleSourcePath = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'src'
+$moduleName = if ([string]::IsNullOrEmpty($Name)) { $env:GITHUB_REPOSITORY_NAME } else { $Name }
+
+$functionDocsFolder = New-Item -Path (Join-Path -Path $siteOutputPath -ChildPath 'docs/Functions') -ItemType Directory -Force
+Copy-Item -Path (Join-Path -Path $docsOutputPath -ChildPath '*') -Destination $functionDocsFolder.FullName -Recurse -Force
+
+Write-Host "Function Docs Folder: $($functionDocsFolder.FullName)"
+Write-Host "Module Name:          $moduleName"
+Write-Host "Module Source Path:   $moduleSourcePath"
+Write-Host "Site Output Path:     $siteOutputPath"
+
+$aboutDocsFolder = New-Item -Path (Join-Path -Path $siteOutputPath -ChildPath 'docs/About') -ItemType Directory -Force
+$aboutSourceFolder = Join-Path -Path $moduleSourcePath -ChildPath 'en-US'
+if (Test-Path -Path $aboutSourceFolder) {
+    Get-ChildItem -Path $aboutSourceFolder -Filter '*.txt' | Copy-Item -Destination $aboutDocsFolder.FullName -Force -PassThru |
+        Rename-Item -NewName { $_.Name -replace '\.txt$', '.md' }
+}
+
+$assetsFolder = New-Item -Path (Join-Path -Path $siteOutputPath -ChildPath 'docs/Assets') -ItemType Directory -Force
+$iconPath = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'icon/icon.png'
+if (Test-Path -Path $iconPath) {
+    Copy-Item -Path $iconPath -Destination $assetsFolder.FullName -Force
+}
+
+$readmePath = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'README.md'
+$readmeTargetPath = Join-Path -Path $siteOutputPath -ChildPath 'docs/README.md'
+Copy-Item -Path $readmePath -Destination $readmeTargetPath -Force
+
+$possiblePaths = @(
+    '.github/zensical.toml',
+    'docs/zensical.toml',
+    'zensical.toml'
+)
+
+$docsConfigSourcePath = $null
+foreach ($relativePath in $possiblePaths) {
+    $candidatePath = Join-Path -Path $resolvedWorkingDirectory -ChildPath $relativePath
+    if (Test-Path -Path $candidatePath) {
+        $docsConfigSourcePath = $candidatePath
+        break
+    }
+}
+
+if (-not $docsConfigSourcePath) {
+    throw "Documentation config file not found. Expected one of: $($possiblePaths -join ', ')"
+}
+
+$docsConfigFileName = [System.IO.Path]::GetFileName($docsConfigSourcePath)
+$docsConfigTargetPath = Join-Path -Path $siteOutputPath -ChildPath $docsConfigFileName
+
+$docsConfigContent = Get-Content -Path $docsConfigSourcePath -Raw
+$docsConfigContent = $docsConfigContent.Replace('-{{ REPO_NAME }}-', $moduleName)
+$docsConfigContent = $docsConfigContent.Replace('-{{ REPO_OWNER }}-', $env:GITHUB_REPOSITORY_OWNER)
+
+if ($docsConfigFileName -eq 'zensical.toml') {
+    if ($docsConfigContent -match '(?m)^\s*site_dir\s*=') {
+        $docsConfigContent = $docsConfigContent -replace '(?m)^\s*site_dir\s*=.*$', 'site_dir = "_site"'
+    } else {
+        $docsConfigContent = $docsConfigContent -replace '(?m)^\[project\]\s*$', "[project]`nsite_dir = ""_site"""
+    }
+}
+
+Set-Content -Path $docsConfigTargetPath -Value $docsConfigContent -Force
+Write-Host "Build Config Type:    $docsConfigFileName"

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

@@ -276,9 +276,7 @@
       env:
         PSMODULE_TEST_PSMODULE_INPUT_Name: ${{ inputs.Name }}
         PSMODULE_TEST_PSMODULE_INPUT_Settings: ${{ inputs.Settings }}
-      run: |
-        # Get test paths
-        ${{ github.action_path }}/src/main.ps1
+      run: ${{ github.action_path }}/src/main.ps1
 
     - name: Invoke-Pester
       uses: PSModule/Invoke-Pester@4ff33199141fdf22568990b6107fe3148ae93a1c # v5.1.0