Add Azure Static Web Apps deployment with Bicep IaC and automated CI/CD

.devcontainer/devcontainer.json

@@ -5,7 +5,8 @@
     "ghcr.io/devcontainers/features/git-lfs:1": {},
     "ghcr.io/devcontainers/features/node:1": {
       "version": "20"
-    }
+    },
+    "ghcr.io/devcontainers/features/azure-cli:1": {}
   },
   "customizations": {
     "vscode": {
@@ -14,12 +15,13 @@
         "GitHub.copilot-chat",
         "ms-dotnettools.csharp",
         "ms-dotnettools.vscode-dotnet-runtime",
-        "ms-azuretools.vscode-azure-mcp-server"
+        "ms-azuretools.vscode-azure-mcp-server",
+        "ms-azuretools.vscode-bicep"
       ]
     }
   },
-  "postCreateCommand": "dotnet tool install -g docfx",
+  "postCreateCommand": "dotnet tool install -g docfx && az bicep install",
   "remoteEnv": {
     "PATH": "${containerEnv:PATH}:${containerEnv:HOME}/.dotnet/tools"
   }
-}
+}

.github/workflows/azure-swa-deploy.yml

@@ -0,0 +1,72 @@
+# name: Deploy to Azure Static Web Apps
+
+# on:
+#   push:
+#     branches:
+#       - main
+#     paths:
+#       - 'docs/**'
+#   pull_request:
+#     types: [opened, synchronize, reopened, closed]
+#     branches:
+#       - main
+#     paths:
+#       - 'docs/**'
+#   workflow_dispatch:
+
+# # Sets permissions for GITHUB_TOKEN
+# permissions:
+#   contents: read
+#   pull-requests: write
+
+# # Allow only one concurrent deployment
+# concurrency:
+#   group: "azure-swa"
+#   cancel-in-progress: false
+
+# jobs:
+#   build_and_deploy:
+#     # Only run on push or if PR is not closed
+#     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.action != 'closed')
+#     runs-on: ubuntu-latest
+#     name: Build and Deploy
+#     steps:
+#       - name: Checkout
+#         uses: actions/checkout@v4
+#         with:
+#           fetch-depth: 1
+
+#       - name: Setup .NET
+#         uses: actions/setup-dotnet@v4
+#         with:
+#           dotnet-version: 8.x
+
+#       - name: Install DocFX
+#         run: dotnet tool update -g docfx
+
+#       - name: Build documentation
+#         run: docfx docs/docfx.json
+
+#       - name: Deploy to Azure Static Web Apps
+#         id: deploy
+#         uses: Azure/static-web-apps-deploy@v1
+#         with:
+#           azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
+#           repo_token: ${{ secrets.GITHUB_TOKEN }}
+#           action: upload
+#           app_location: "docs/_site"
+#           api_location: ""
+#           output_location: ""
+#           skip_app_build: true
+
+#   close_pull_request:
+#     # Only run when PR is closed
+#     if: github.event_name == 'pull_request' && github.event.action == 'closed'
+#     runs-on: ubuntu-latest
+#     name: Close Pull Request
+#     steps:
+#       - name: Close Pull Request
+#         uses: Azure/static-web-apps-deploy@v1
+#         with:
+#           azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
+#           action: close

.gitignore

@@ -53,4 +53,12 @@ CodeCoverage/
 TestResult.xml
 nunit-*.xml
 
-_site/
+_site/
+
+# Azure Static Web Apps
+.azure/
+swa-cli.config.json
+
+# Bicep build artifacts
+infra/*.json
+!infra/bicep.parameters.json

DEPLOYMENT.md

@@ -0,0 +1,171 @@
+# Azure Static Web Apps Deployment - Quick Start
+
+This guide walks you through deploying your DocFX wiki to Azure Static Web Apps in minutes.
+
+## Prerequisites
+
+- Azure subscription ([free trial available](https://azure.microsoft.com/free/))
+- Azure CLI installed ([install guide](https://learn.microsoft.com/cli/azure/install-azure-cli))
+- GitHub repository access (for setting secrets)
+
+## Step-by-Step Deployment
+
+### 1. Clone and Customize
+
+```bash
+# Clone the repository
+git clone https://github.com/YOUR-USERNAME/docfx-wiki.git
+cd docfx-wiki
+
+# Edit the parameters file
+cd infra
+nano bicep.parameters.json  # or use your preferred editor
+```
+
+**Edit these values in `bicep.parameters.json`:**
+
+```json
+{
+  "parameters": {
+    "staticWebAppName": {
+      "value": "my-unique-wiki-name"  // ⚠️ Must be globally unique
+    },
+    "location": {
+      "value": "eastus2"  // Choose your preferred region
+    },
+    "sku": {
+      "value": "Free"  // Free or Standard
+    }
+  }
+}
+```
+
+### 2. Login to Azure
+
+```bash
+az login
+```
+
+### 3. Deploy Infrastructure (One Command!)
+
+```bash
+# Create resource group and deploy in one go
+RESOURCE_GROUP="rg-docfx-wiki"
+LOCATION="eastus2"
+
+az group create --name $RESOURCE_GROUP --location $LOCATION && \
+az deployment group create \
+  --resource-group $RESOURCE_GROUP \
+  --template-file main.bicep \
+  --parameters bicep.parameters.json
+```
+
+✅ **Success!** Your Azure Static Web App is now created.
+
+### 4. Get Your Deployment Token
+
+```bash
+DEPLOYMENT_TOKEN=$(az deployment group show \
+  --resource-group $RESOURCE_GROUP \
+  --name main \
+  --query properties.outputs.deploymentToken.value \
+  --output tsv)
+
+echo "Your deployment token: $DEPLOYMENT_TOKEN"
+```
+
+⚠️ **Important:** Copy this token - you'll need it in the next step.
+
+### 5. Add Secret to GitHub
+
+1. Go to your GitHub repository
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Click **New repository secret**
+4. Set:
+   - **Name:** `AZURE_STATIC_WEB_APPS_API_TOKEN`
+   - **Value:** Paste the deployment token from step 4
+5. Click **Add secret**
+
+### 6. Trigger Deployment
+
+Option A: Push to main branch
+```bash
+git add .
+git commit -m "Update documentation"
+git push origin main
+```
+
+Option B: Manual trigger
+1. Go to **Actions** tab in GitHub
+2. Select **Deploy to Azure Static Web Apps**
+3. Click **Run workflow**
+
+### 7. View Your Site
+
+Get your site URL:
+```bash
+az staticwebapp show \
+  --name $(jq -r '.parameters.staticWebAppName.value' bicep.parameters.json) \
+  --resource-group $RESOURCE_GROUP \
+  --query defaultHostname \
+  --output tsv
+```
+
+Or find it in the Azure Portal:
+- Go to [portal.azure.com](https://portal.azure.com)
+- Navigate to your resource group
+- Click on your Static Web App
+- Copy the URL from the Overview page
+
+## What Happens Next?
+
+✨ **Automatic Deployments:** Every time you push changes to the `docs/**` folder on the `main` branch, GitHub Actions will:
+1. Build your DocFX site
+2. Deploy it to Azure Static Web Apps
+3. Make it available at your custom URL
+
+## Troubleshooting
+
+### "Static Web App name already exists"
+- Change `staticWebAppName` in `bicep.parameters.json` to a unique value
+- Re-run the deployment command
+
+### "Deployment token not working"
+- Regenerate the token:
+  ```bash
+  az staticwebapp secrets list \
+    --name YOUR_APP_NAME \
+    --resource-group $RESOURCE_GROUP
+  ```
+- Update the GitHub secret with the new token
+
+### "Workflow not triggering"
+- Check that the workflow file exists: `.github/workflows/azure-swa-deploy.yml`
+- Verify the secret name is exactly: `AZURE_STATIC_WEB_APPS_API_TOKEN`
+- Check workflow runs under the **Actions** tab
+
+### "Site shows 404 or not found"
+- Wait 2-3 minutes after first deployment
+- Clear your browser cache
+- Check the deployment status in GitHub Actions
+
+## Cleanup
+
+To delete all resources and stop charges:
+
+```bash
+az group delete --name $RESOURCE_GROUP --yes --no-wait
+```
+
+## Next Steps
+
+- 📝 [Edit your wiki content](../docs/content/)
+- 🎨 [Customize DocFX templates](../docs/docfx.json)
+- 🔧 [Configure routing](../staticwebapp.config.json)
+- 📊 [Monitor with Application Insights](https://learn.microsoft.com/azure/static-web-apps/monitor)
+
+## Support
+
+- 📖 [Azure Static Web Apps Documentation](https://learn.microsoft.com/azure/static-web-apps/)
+- 💬 [GitHub Discussions](https://github.com/YOUR-USERNAME/docfx-wiki/discussions)
+- 🐛 [Report Issues](https://github.com/YOUR-USERNAME/docfx-wiki/issues)

README.md

@@ -1,13 +1,50 @@
-# docfx-wiki
+# DocFX Wiki
 
-Lightweight wiki-style documentation site built with [DocFX](https://github.com/dotnet/docfx). Author content in Markdown, build a static site, and (optionally) publish to GitHub Pages.
+A proof of concept (PoC) wiki-style documentation site built with [DocFX](https://github.com/dotnet/docfx). It demonstrates a simple, yet feature-rich wiki experience (navigation, search, static hosting) while keeping authoring lightweight with Markdown.
 
-## Quick start
+The focus of this repo is to provide a reusable template so others can quickly start a wiki in their own environment and deploy it with minimal setup.
+
+## Publish
+
+Click the green `Use this template` button in the top right of this page and choose `create a new repository`, then pick one of the following deployment options:
+
+### Option 1: GitHub Pages
+
+- Workflow: `.github/workflows/publish-site.yml`
+
+Enable GitHub Pages for the new repo created from this template:
+
+1. In the repo, go to **Settings** → **Pages**.
+2. Under **Build and deployment**, set **Source** to **GitHub Actions**.
+3. Deploy to GitHub Pages by pushing a change under `docs/` to `main` or run the workflow via **Actions**.
+
+### Option 2: Azure Static Web Apps
+
+- Workflow: `.github/workflows/azure-swa-deploy.yml`
+- Requires a repo secret named `AZURE_STATIC_WEB_APPS_API_TOKEN`
+
+Quick deploy (Codespaces recommended):
+
+1. Edit the `infra/bicep.parameters.json` as desired.
+2. Authenticate to Azure using `az login` and select the desired subscription
+3. Run the deployment script:
+```bash
+./deploy-azure.sh
+```
+4. Copy the deployment token from the Azure Static Web App in the Azure Portal.
+5. Create a repo secret in this repository named `AZURE_STATIC_WEB_APPS_API_TOKEN` with the deployment token as the value.
+6. Uncomment `.github/workflows/azure-swa-deploy.yml` and run the workflow via **Actions**. 
+
+or
+
+Manual setup: see `DEPLOYMENT.md`.
+
+## Local Development
 
 ### Option A: GitHub Codespaces (recommended)
 
 1. Create a Codespace from this repo.
-2. Wait for the dev container to finish provisioning (it installs DocFX).
+2. Wait for the dev container to finish provisioning.
 3. Start the local site server:
 
 ```bash
@@ -58,10 +95,7 @@ docfx docs/docfx.json
 
 Output goes to `docs/_site/`.
 
-## Publish
-
-This repo includes a GitHub Actions workflow that builds the site and deploys `docs/_site` to GitHub Pages on pushes to `main`.
-
 ## Learn more
 
-- DocFX project: https://github.com/dotnet/docfx
+- DocFX project: https://github.com/dotnet/docfx
+- Azure Static Web Apps: https://learn.microsoft.com/azure/static-web-apps/