Skip to content

Documentation Template

The ConnectSoft Documentation Template (ConnectSoft.DocumentationTemplate) scaffolds an MkDocs site with Material for MkDocs, optional log4brains ADRs, and a sample Azure Pipelines definition. It is the same template used when agents run dotnet new connectsoft-documentation.

Canonical parameter reference (do not duplicate tables here): Documentation Template Parameters on ConnectSoft.Documentation.

What the template actually ships

  • mkdocs.yml: Material theme; plugins search, panzoom, exclude; Mermaid via pymdownx.superfences (not mkdocs-mermaid2-plugin).
  • requirements.txt: Python deps for the plugins above (mkdocs-material, mkdocs-panzoom-plugin, mkdocs-exclude).
  • docs/: index.md, architecture.md, use-cases.md, api/reference.md, tutorials/getting-started.md, includes/, docs/adr/ sample ADR.
  • package.json: log4brains scripts (adr:preview, adr:new, adr:build).
  • azure-pipelines-documentation.yml: sample build (MkDocs + ADRs + artifact)—not azure-pipelines.yml at repo root by that exact name.
  • staticwebapp.config.json, .log4brains.yml, .sln.

Copyright line 1975 in mkdocs.yml is a template token replaced by the current year at scaffold time (currentYear in .template.config/template.json).

Template parameters (summary)

Symbol Role
siteTitle Site title / branding
siteDescription Meta description
repoUrl Repo URL for edit links and repo_url
buildDefinitionNumber Optional CI placeholder string

CLI: dotnet new connectsoft-documentation -h (kebab-case: --site-title, --site-description, --repo-url, --build-definition-number / -bdn).

Generated layout (accurate)

YourName/
├── docs/
│   ├── index.md
│   ├── architecture.md
│   ├── use-cases.md
│   ├── api/reference.md
│   ├── tutorials/getting-started.md
│   ├── adr/
│   └── includes/
├── mkdocs.yml
├── requirements.txt
├── package.json
├── azure-pipelines-documentation.yml
├── staticwebapp.config.json
├── README.md
└── *.sln

Quick start

dotnet new install <PATH_OR_NUPKG_TO_ConnectSoft.DocumentationTemplate>
dotnet new connectsoft-documentation -n MyOrg.MyDocs -o ./MyOrg.MyDocs \
  --site-title "My Org Docs" \
  --site-description "Technical documentation" \
  --repo-url "https://dev.azure.com/org/project/_git/MyOrg.MyDocs"
cd ./MyOrg.MyDocs
pip install -r requirements.txt
mkdocs serve

Scope: template vs agents

  • Template: static scaffold + sample pipeline + ADR tooling hooks.
  • Documentation Site Generator Agent (see documentation-site-generator-agent.md): installs template, runs dotnet new, verifies mkdocs build, may help with nav edits, extra pipelines, or hosting—those extras are not guaranteed by the template alone.