Documentation Deployment¶

Overview¶

The portfolio documentation is deployed to two platforms for redundancy and accessibility:

1. Azure Static Web App (Primary) - Production deployment
2. GitHub Pages (Secondary) - Backup and development preview

Deployment Targets¶

1. Azure Static Web App (Primary)¶

URL: https://docs.portfolio.onedna.nl (custom domain)

Features:

• Custom domain support
• SSL/TLS certificates
• Staging environments for PRs
• Azure CDN integration
• Production-grade hosting

Workflow: .github/workflows/deploy-docs.yml

Triggers:

• Push to main branch (docs changes)
• Pull requests (creates preview environment)
• Manual workflow dispatch

Requirements:

• Azure Static Web App resource
• AZURE_STATIC_WEB_APPS_API_TOKEN secret in GitHub

2. GitHub Pages (Secondary)¶

URL: https://svenrelijveld1995.github.io/portfolio/

Features:

• Free hosting
• Automatic SSL
• Fast global CDN
• No configuration required
• Backup deployment

Workflow: .github/workflows/deploy-docs-github-pages.yml

Triggers:

• Push to main branch (docs changes)
• Manual workflow dispatch

Requirements:

• GitHub Pages enabled in repository settings
• pages: write permission

Deployment Architecture¶

Setup Instructions¶

Azure Static Web App Deployment¶

1. Create Azure Resources¶

# Deploy infrastructure
az deployment sub create \
  --location westeurope \
  --template-file infra/main.bicep \
  --parameters infra/parameters.dev.json

2. Get Deployment Token¶

# Get the deployment token
az staticwebapp secrets list \
  --name onedna-dev-portfolio-westeurope-swa-abc123 \
  --query "properties.apiKey" -o tsv

3. Add GitHub Secret¶

1. Go to repository Settings → Secrets and variables → Actions
2. Click New repository secret
3. Name: AZURE_STATIC_WEB_APPS_API_TOKEN
4. Value: Paste the deployment token
5. Click Add secret

4. Trigger Deployment¶

# Push changes to main
git add .
git commit -m "docs: update documentation"
git push origin main

GitHub Pages Deployment¶

1. Enable GitHub Pages¶

1. Go to repository Settings → Pages
2. Source: GitHub Actions
3. Save

2. Trigger Deployment¶

The workflow runs automatically on push to main. No additional configuration needed!

Workflow Comparison¶

Monitoring Deployments¶

Check Workflow Status¶

1. Go to Actions tab in GitHub
2. View recent workflow runs
3. Click on a run to see details

Azure Static Web App¶

# Check deployment status
az staticwebapp show \
  --name onedna-dev-portfolio-westeurope-swa-abc123 \
  --query "properties.defaultHostname"

GitHub Pages¶

Visit: https://svenrelijveld1995.github.io/portfolio/

Troubleshooting¶

Azure Deployment Fails¶

Issue: AZURE_STATIC_WEB_APPS_API_TOKEN not found

Solution:

1. Verify secret exists in GitHub repository settings
2. Check secret name matches exactly
3. Regenerate token if expired

Issue: Build fails

Solution:

1. Check workflow logs for errors
2. Verify MkDocs dependencies are correct
3. Test build locally: mkdocs build --strict

GitHub Pages Deployment Fails¶

Issue: Pages not enabled

Solution:

1. Go to Settings → Pages
2. Set source to "GitHub Actions"
3. Re-run workflow

Issue: 404 errors

Solution:

1. Wait 5-10 minutes for DNS propagation
2. Clear browser cache
3. Check workflow completed successfully

Manual Deployment¶

Build Locally¶

# Build documentation
mkdocs build

# Output: site/

Deploy to Azure (Manual)¶

# Using Azure CLI
az staticwebapp upload \
  --name onedna-dev-portfolio-westeurope-swa-abc123 \
  --source ./site

Deploy to GitHub Pages (Manual)¶

# Using gh-pages
pip install ghp-import
mkdocs gh-deploy --force

Best Practices¶

1. Test Locally First¶

Always test documentation changes locally before pushing:

mkdocs serve --dev-addr=127.0.0.1:8001

2. Use Strict Mode¶

Build with --strict to catch errors:

mkdocs build --strict

3. Check Links¶

Verify all internal links work before deploying.

4. Monitor Both Deployments¶

Check both Azure and GitHub Pages after deployment to ensure consistency.

5. Use PR Previews¶

For Azure Static Web App, create PRs to get preview environments before merging.

URLs Summary¶

Next Steps¶

• Architecture Overview
• Development Setup
• GitHub Actions Setup
• Azure Infrastructure