Skip to content

Documentation Template

Current implementation

This page describes what exists in source today, with its limitations. Existence of code is not evidence of publication, deployment or tested guarantees.

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.