Skip to content

Documentation Template

The ConnectSoft Documentation Template provides a ready-to-use solution for building comprehensive documentation sites using MkDocs and the Material theme. This template generates a complete documentation project structure with CI/CD integration, automated publishing, and best practices for technical documentation.

Overview

The Documentation Template generates a production-ready documentation site that can be hosted on Azure Static Web Apps, GitHub Pages, or any static hosting service. It includes pre-configured MkDocs setup with Material theme, navigation structure, and automated build and deployment pipelines.

When to Use This Template

Use the Documentation Template when:

  • Creating documentation for microservices, libraries, or platforms
  • Building API documentation sites
  • Creating developer guides and tutorials
  • Building knowledge bases and wikis
  • Documenting architecture and design decisions
  • Creating user manuals and help documentation

Key Features

MkDocs Integration

  • Material Theme: Modern, responsive documentation theme
  • Search Functionality: Built-in full-text search
  • Navigation: Hierarchical navigation structure
  • Code Highlighting: Syntax highlighting for code blocks
  • Markdown Support: Full Markdown support with extensions

Documentation Structure

  • Organized Sections: Logical organization of content
  • Table of Contents: Auto-generated TOC
  • Cross-References: Link between pages
  • Versioning: Support for versioned documentation
  • Multi-Language: Support for internationalization

CI/CD Integration

  • Automated Builds: Build documentation on commits
  • Automated Deployment: Deploy to hosting service
  • Preview Builds: Preview documentation for pull requests
  • Version Management: Track documentation versions

Best Practices

  • Structured Content: Consistent structure and formatting
  • SEO Optimization: Search engine optimization
  • Accessibility: WCAG compliance
  • Performance: Fast page loads and navigation

Generated Structure

The template generates a complete documentation project:

YourDocumentationName/
├── docs/
│   ├── index.md
│   ├── getting-started/
│   ├── guides/
│   ├── reference/
│   └── ...
├── mkdocs.yml
├── requirements.txt
├── azure-pipelines.yml
└── README.md

Template Parameters

Parameter Type Required Default Description
DocumentationName string Yes Documentation Name of the documentation site
SiteDescription string Yes Documentation Site description
Author string No ConnectSoft Author name
RepositoryUrl string No "" Repository URL for edit links

Quick Start

Step 1: Create Documentation Site

dotnet new connectsoft-documentation \
  --name MyProjectDocs \
  --site-description "My Project Documentation"

Step 2: Add Content

Add markdown files to the docs/ directory and update mkdocs.yml navigation.

Step 3: Build Locally

mkdocs serve

Step 4: Deploy

The CI/CD pipeline automatically builds and deploys documentation on commits.

Configuration

mkdocs.yml

The template generates a pre-configured mkdocs.yml with:

  • Material theme configuration
  • Navigation structure
  • Plugin configuration
  • Search configuration
  • Extensions enabled

Customization

  • Theme: Customize Material theme colors and options
  • Navigation: Organize content in hierarchical structure
  • Plugins: Add MkDocs plugins for additional features
  • Extensions: Configure Markdown extensions

Integration with AI Factory

The Documentation Template is used by:

  • Documentation Writer Agent: Generates documentation sites
  • Knowledge Management Agent: Creates knowledge bases
  • Project Bootstrap: Includes documentation in new projects

Best Practices

Content Organization

  • Use clear, descriptive page titles
  • Organize content hierarchically
  • Maintain consistent structure
  • Use cross-references effectively

Writing Style

  • Write for your audience
  • Use clear, concise language
  • Include code examples
  • Add diagrams and visuals

Maintenance

  • Keep content up to date
  • Review and update regularly
  • Gather user feedback
  • Improve based on analytics