deploy auto generated docs to GitHub pages

.github/scripts/generate-docs-workflow.psm1

@@ -0,0 +1,34 @@
+function Format-AutoGeneratedMarkdownFile {
+  [CmdletBinding()]
+  param ([string]$Version)
+
+  foreach ($File in Get-ChildItem ./docs/helpers/*.md) {
+    # Add front matter
+    $Frontmatter = ""
+    $FrontMatter += "---`r`n"
+    $FrontMatter += "WARNING: `"PLEASE DO NOT MODIFY THIS FILE, IT'LL BE OVERWRITTEN`"`r`n"
+    $FrontMatter += "layout: `"../../layouts/main.astro`"`r`n"
+    $FrontMatter += "title: `"$($File.BaseName)`"`r`n"
+    $FrontMatter += "module: `"BenchPress.Azure`"`r`n"
+    $FrontMatter += "version: `"$Version`"`r`n"
+    $FrontMatter += "updatedOn: `"$(Get-Date -Format "yyyy-MM-dd HH:mm K")`"`r`n"
+    $FrontMatter += "---`r`n"
+    # Fix escaping issues
+    $Content = Get-Content $File -Raw
+    $Content = $Content -Replace '\\`', '`'
+    $Content = $Content -Replace "\\\[", "["
+    $Content = $Content -Replace "\\\]", "]"
+    # Fix syntax highlighting
+    $Lines = $Content -Split "`r`n"
+    for ($i = 0; $i -lt $Lines.Length; $i++) {
+      if ($Lines[$i] -match "^## SYNTAX") {
+        $j = $i + 2
+        if ($Lines[$j] -match '```') {
+          $Lines[$j] = $Lines[$j] -Replace '```', '```powershell'
+        }
+      }
+    }
+    # Write out the file back
+    Set-Content $File ($FrontMatter + ($Lines -join "`r`n"))
+  }
+}

.github/workflows/cd-publish-docs-branch.yml

@@ -0,0 +1,85 @@
+---
+# yamllint disable line-length
+name: "Publish docs to GitHub Pages"
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - docs
+    paths:
+      - docs/**
+      - docs-site/**
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+env:
+  BUILD_PATH: "./docs-site"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          ref: docs
+          token: ${{ secrets.DOCS_ACTION_TOKEN }}
+
+      - name: Copy from docs/helpers to docs-site/src/pages/docs
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Path "./docs-site/src/pages/docs" -Force
+          Copy-Item -Path "./docs/helpers/*" -Destination "./docs-site/src/pages/docs" -Include "*.md" -Recurse -Force
+
+      - name: Detect package manager
+        id: detect-package-manager
+        run: |
+          {
+            echo 'manager=npm'
+            echo 'command=ci'
+            echo 'runner=npx --no-install'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: "16"
+          cache: ${{ steps.detect-package-manager.outputs.manager }}
+          cache-dependency-path: ${{ env.BUILD_PATH }}/package-lock.json
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v2
+
+      - name: Install dependencies
+        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
+        working-directory: ${{ env.BUILD_PATH }}
+
+      - name: Build with Astro
+        run: |
+          ${{ steps.detect-package-manager.outputs.runner }} astro build \
+            --site "${{ steps.pages.outputs.origin }}" \
+            --base "${{ steps.pages.outputs.base_path }}"
+        working-directory: ${{ env.BUILD_PATH }}
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ${{ env.BUILD_PATH }}/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -111,3 +111,5 @@ StyleCopReport.xml
 !?*.[Cc]ache/
 
 megalinter-reports/
+
+node_modules

docs-site/astro.config.mjs

@@ -0,0 +1,15 @@
+import { defineConfig } from "astro/config";
+
+import tailwind from "@astrojs/tailwind";
+
+export default defineConfig({
+  base: "/benchpress",
+  markdown: {
+    shikiConfig: {
+      theme: "dark-plus"
+    }
+  },
+  integrations: [tailwind({
+    config: { applyBaseStyles: false },
+  })]
+});