# 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](https://docs.saif.com).

[TOC]

## 📋 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:

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

**Example:**

```bash
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

```bash
pip install -r docs/requirements.txt
mkdocs serve
```

Open [http://localhost:8000](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:**

```bash
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/`.

!!! warning "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:

```bash
# 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
```

!!! note "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

### Navigation

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

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

The [awesome-nav](https://github.com/lukasgeiter/mkdocs-awesome-nav) plugin auto-discovers pages and uses `.nav.yml` files for ordering.

### Theme

The site uses [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) with SAIF brand styling loaded from the shared `docs.saif.com` stylesheet. Customize `mkdocs.yml` to add plugins, extensions, or theme overrides.