Documentation Site Template Runbook

1. Scaffold

dotnet new install <PATH_TO_ConnectSoft.DocumentationTemplate>
dotnet new connectsoft-documentation -n MyProduct.Docs -o ./out/MyProduct.Docs \
  --site-title "My Product Docs" \
  --site-description "Technical documentation for My Product" \
  --repo-url "https://dev.azure.com/org/project/_git/MyProduct.Docs"

Confirm flags with dotnet new connectsoft-documentation -h. Full symbol table: Parameters.

2. Python environment

cd ./out/MyProduct.Docs
pip install -r requirements.txt
mkdocs serve

Open the local URL (default http://127.0.0.1:8000). Production build: mkdocs build → output in site/.

3. ADRs (optional)

• Install Node.js LTS and npm
• npm install if the template adds lockfiles; use npm run adr:preview / npm run adr:new / npm run adr:build as documented in the generated README

4. CI/CD

• Use or adapt azure-pipelines-documentation.yml
• Pipeline variables (pool, approvals, artifact names) are Azure DevOps concerns—not dotnet new parameters

5. Troubleshooting

Symptom	Check
Plugin "exclude" not installed	pip install -r requirements.txt (includes mkdocs-exclude)
Plugin "panzoom" not installed	Install mkdocs-panzoom-plugin per requirements.txt
Copyright shows 1975	Run scaffold via dotnet new so currentYear replaces the token, or edit mkdocs.yml manually

6. See also

• Overview
• Parameters