Skip to content

Deploying to the Shared Docs Site

How to publish documentation from your repo to docs.saif.com. No per-repo Terraform needed — cloud-foundations owns the infrastructure.

File Structure

Add the following to your repo:

.azdo/
  azure-docs.yml        # deploy pipeline (manual trigger)
  azure-docs-pr.yml     # PR validation pipeline (no deploy)
  vars/
    docs.yml            # docs config variables
docs/
  requirements.txt      # Python dependencies for MkDocs
mkdocs.yml              # your MkDocs config

SAIF Brand Styling

All docs sites share a common SAIF-branded stylesheet hosted by cloud-foundations at docs.saif.com/assets/stylesheets/saif-docs-theme.css. Add it to your mkdocs.yml:

extra_css:
  - https://docs.saif.com/assets/stylesheets/saif-docs-theme.css

This provides SAIF Evergreen/Pacific branding with light and dark mode support. The stylesheet is maintained in cloud-foundations at docs/assets/stylesheets/saif-docs-theme.css. Pages render unstyled if offline during local mkdocs serve.

vars/docs.yml

variables:
  - name: projectId
    value: 'your-repo-name'
  - name: documentationSourceDirectory
    value: '../../'
  - name: outputDirectory
    value: 'staticsite'
  - name: siteType
    value: 'mkdocs'
  - name: containerFolderName
    value: 'your-folder-name'        # sets your URL path: docs.saif.com/{folder}/

azure-docs.yml

name: $(MajorVersion).$(MinorVersion).$(PatchVersion)

trigger: none
pr: none

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: TerraformCloud
  - template: templates/versioning.yml
  - template: vars/docs.yml
  - template: vars/vars.yml
  - template: saif-vars.yml@templates

resources:
  repositories:
    - repository: templates
      type: git
      name: SAIF/pipeline-templates
      ref: refs/heads/main

stages:
  - template: azure-docs-v2.yml@templates
    parameters:
      projectId: ${{ variables.projectId }}
      documentationSourceDirectory: ${{ variables.documentationSourceDirectory }}
      outputDirectory: ${{ variables.outputDirectory }}
      siteType: ${{ variables.siteType }}
      containerFolderName: ${{ variables.containerFolderName }}
      # deployToPlatformDev: true   # uncomment to also deploy to platformdev

azure-docs-pr.yml

name: $(MajorVersion).$(MinorVersion).$(PatchVersion)$(PreReleaseVersionSeparator)$(PreReleaseVersion)$(RevisionSeparator)$(Revision)

trigger: none

pr:
  branches:
    include:
      - main
  paths:
    include:
      - .azdo/azure-docs-pr.yml
      - .azdo/vars/docs.yml
      - docs/*
      - mkdocs.yml

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: TerraformCloud
  - template: templates/versioning.yml
  - template: vars/docs.yml
  - template: vars/vars.yml
  - template: saif-vars.yml@templates

resources:
  repositories:
    - repository: templates
      type: git
      name: SAIF/pipeline-templates
      ref: refs/heads/main

stages:
  - template: azure-docs-pr-v2.yml@templates
    parameters:
      projectId: ${{ variables.projectId }}
      documentationSourceDirectory: ${{ variables.documentationSourceDirectory }}
      outputDirectory: ${{ variables.outputDirectory }}
      siteType: ${{ variables.siteType }}
      containerFolderName: ${{ variables.containerFolderName }}

Then register both pipeline files in Azure DevOps. No additional service connections or permissions are required.

Troubleshooting

Build succeeds but content doesn't appear at docs.saif.com/{folder}/

  • Confirm containerFolderName in your vars file matches exactly what you expect in the URL
  • Check that the pipeline ran against the correct environment (the storage account is per-environment)
  • Verify the Front Door cache isn't serving stale content — it may take a few minutes to propagate

mkdocs build fails with a missing plugin or extension

  • Add the dependency to docs/requirements.txt in your repo — the build activity installs from this file automatically