Skip to content

Documentation Site

This guide shows you how to add an MkDocs documentation site to your existing SAIF application, with Azure DevOps pipelines that deploy to docs.saif.com.

On this page

📋 Prerequisites

  • ✅ Existing SAIF API project
  • ✅ Python 3.x with pip (MkDocs CLI is installed via docs/requirements.txt)
  • ✅ Azure DevOps access

🚀 Quick Start

1. Add the Feature

From your project root directory:

dotnet new saif-feature-docs-site --project_id <your-project-id>

Example:

dotnet new saif-feature-docs-site --project_id it-api-sys-myapp

This adds the following files to your project:

File Purpose
mkdocs.yml MkDocs Material theme configuration
docs/index.md Documentation landing page
docs/.nav.yml Navigation structure
docs/requirements.txt Python dependencies for MkDocs
.azdo/azure-docs.yml Deploy pipeline
.azdo/azure-docs-pr.yml PR validation pipeline
.azdo/vars/docs.yml Pipeline variables

2. Preview Locally

pip install -r docs/requirements.txt
mkdocs serve

Open http://localhost:8000 to preview your site.

3. Add Content

  1. Add Markdown files under the docs/ directory
  2. Update docs/.nav.yml to include new pages in the navigation
  3. Commit and push — the PR pipeline validates your docs build
  4. After merge, trigger the deploy pipeline to publish to docs.saif.com

⚙️ Configuration Options

The template accepts the following parameters:

Parameter Description Default
--project_id Project identifier used for pipeline names and URL path (required)
--container_folder_name URL path segment at docs.saif.com/{folder}/ Defaults to project_id
--site_name Display name for the documentation site Defaults to project_id

Example with all options:

dotnet new saif-feature-docs-site \
  --project_id it-api-sys-myapp \
  --container_folder_name myapp \
  --site_name "My Application"

This would deploy to docs.saif.com/myapp/.

Container folder names must be unique

The container_folder_name determines the URL path on docs.saif.com. Deploying will overwrite any existing content at that path. Defaults to your project ID, which is guaranteed to be unique.

📂 Project Structure

After adding the docs-site feature, your project will have:

your-project/
├── mkdocs.yml                    # Site configuration
├── docs/
│   ├── .nav.yml                  # Navigation structure
│   ├── index.md                  # Landing page
│   └── requirements.txt         # Python dependencies
└── .azdo/
    ├── azure-docs.yml            # Deploy pipeline
    ├── azure-docs-pr.yml         # PR validation pipeline
    └── vars/
        └── docs.yml              # Pipeline variables

🔄 Pipelines

The feature creates two Azure DevOps pipelines:

Pipeline Name Trigger
Deploy {project_id}-docs Manual — run after merge to deploy
PR Validation {project_id}-docs-pr Automatic on PRs touching docs/, mkdocs.yml, or .azdo/vars/docs.yml

New Projects

For new projects created with saif new, you will be prompted whether to include a documentation site:

? Include Docs Site? (y/n)

Select Yes to include it. After project creation, setup.ps1 runs automatically and calls saif new saif-feature-docs-site to scaffold the docs files and create pipelines.

To skip the prompt, pass the flag explicitly:

# Include docs site without prompting
saif new saif-api-exp --include_docs_site true

# Exclude docs site without prompting
saif new saif-api-exp --include_docs_site false

Dry runs skip setup

saif new saif-api-exp --dry-run will not scaffold the docs site because setup.ps1 is never executed in dry-run mode.

Existing Projects

When adding to an existing project with dotnet new, you need to create the pipelines manually in Azure DevOps:

  1. Go to Pipelines → New Pipeline
  2. Select your repository
  3. Choose Existing Azure Pipelines YAML file
  4. Select .azdo/azure-docs.yml and name it {project_id}-docs
  5. Repeat for .azdo/azure-docs-pr.yml and name it {project_id}-docs-pr

🎨 Customization

Edit docs/.nav.yml to control page ordering:

nav:
  - index.md
  - getting-started.md
  - guides
  - reference

The awesome-nav plugin auto-discovers pages and uses .nav.yml files for ordering.

Theme

The site uses MkDocs Material with SAIF brand styling loaded from the shared docs.saif.com stylesheet. Customize mkdocs.yml to add plugins, extensions, or theme overrides.