Skip to content

Hosting Documentation

This documentation is based on Markdown. MkDocs is recommended for hosting.

Important for Private Repositories

The repository does not need to be public. You only host the generated static site from the site folder.

This allows users to access documentation without direct access to source code.

Local Preview

In the LoopCheck repository root:

pip install mkdocs mkdocs-material
mkdocs serve

Then open in your browser:

  • http://127.0.0.1:8000

Static Build

mkdocs build

The static output is created in:

  • site/

Deployment Options

  • Azure Static Web Apps
  • Internal Nginx/Apache server
  • Artifact upload in CI pipeline

Recommended for enterprise environments:

  • Azure Static Web Apps with Entra ID login
  • or internal server with VPN/SSO

Azure Static Web Apps Setup

  1. Create a new Static Web App in Azure.
  2. Create an Azure DevOps pipeline for this repository.

  3. Add the Static Web App deployment token as a secret pipeline variable:

  4. Variable name: azure_static_web_apps_api_token

  5. Use the pipeline file from the repository root:

  6. azure-pipelines.yml

  7. Set build details in the pipeline:

  8. App location: .

  9. Output location: site
  10. Build command: pip install mkdocs mkdocs-material && mkdocs build --strict
  11. Push changes to main. The pipeline deploys the docs automatically.

Pipeline file location:

  • azure-pipelines.yml

Access Protection for Internal Users

  • Configure authentication with Microsoft Entra ID in your Static Web App.
  • Restrict access to your company tenant or specific groups.
  • Keep repository access limited to maintainers.

Secure Access

  • Allow only authenticated users
  • Separate reader and maintainer roles
  • Deploy only from approved branches

Azure DevOps Notes

  • If the pipeline cannot deploy, verify that the secret variable name is exactly azure_static_web_apps_api_token.
  • If push operations to Azure DevOps fail with HTTP 400, Git may need HTTP/1.1 enabled locally.
  • The Static Web App does not need direct repository linking in the portal when deployment is handled by Azure DevOps.
  • Add a CI job that builds automatically on changes in the doc folder
  • Add link checks and Markdown linting to the pipeline
  • Plan versioning for releases