Documentation Site Template Use Cases

Product or platform documentation

Use the template to stand up a dedicated docs repo or a docs/ site next to a service: run dotnet new connectsoft-documentation, set siteTitle, siteDescription, and repoUrl to your real Azure DevOps or GitHub URL, then add pages under docs/ and extend nav in mkdocs.yml.

API and developer guides

The generated API Reference page is a stub. Replace it with hand-written API docs, or generate OpenAPI-based pages later. The Material stack supports code blocks, tabs, and Mermaid for sequence diagrams.

Architecture Decision Records (ADRs)

Teams that want log4brains timelines and ADR workflows use the included npm run adr:* scripts and docs/adr/. CI can merge the ADR build into the main static site (see azure-pipelines-documentation.yml in the template).

Factory or agent-driven scaffolding

Automation (for example Software Factory agents using connectsoft-documentation-site-generator) should follow Parameters and verify with dotnet new connectsoft-documentation -h—do not invent flags beyond the template.

This site vs the template

ConnectSoft.Documentation (this website) is a large, curated instance: same MkDocs/Material stack, but Docs/ folder naming, use_directory_urls: false, and a full navigation tree. The template is a minimal starting point.