How microsoft/mu works
Project type and purpose
• This repo is not an application or service, but a documentation site project for “Project Mu.”
• It uses MkDocs (a static site generator) plus custom Python scripts to build, test, and deploy documentation.
• Continuous-integration (CI) workflows automate linting, testing, building, and publishing of the generated site.
File structure
a. Top‐level files & scripts
• README.md, CONTRIBUTING.md, LICENSE.txt, SECURITY.md, .gitignore, MkDocs config (mkdocs_base.yml), Python build tools (DocBuild.py, Test_DocBuild.py, Utf8Test.py), requirements.txt.
b. docs/ directory
• Markdown source for all documentation (“WhatAndWhy”, “How”, “DeveloperDocs”, etc.), plus docs/img for images.
c. theme/ directory
• Custom MkDocs theme assets (CSS, JS, images) under theme/assets.
d. CI/CD configurations
• Azure Pipelines YAML (azure-pipelines-pr-gate.yml)
• GitHub Actions workflows under .github/workflows (auto-approve, label-issues, stale, triage, etc.)
e. Testing & linting
• Python tests (Test_DocBuild.py), UTF-8 validation (Utf8Test.py), .flake8, cspell.json spelling config, .markdownlint.yaml.
README for additional insights
• Primary build commands:
1. pip install --upgrade -r requirements.txt
2. DocBuild.py --Build --Clean --yml mkdocs_base.yml
3. mkdocs serve (or mkdocs build in CI).
• Publishes to https://microsoft.github.io/mu/ via GitHub Pages / Azure static-site hosting.
Elements
• Labels: “Docs Source”, “Theme Assets”, “DocBuild.py”, “MkDocs Engine”, “CI/CD”, “Quality Gate”, “Hosting”.
• From Docs Source & Theme → DocBuild.py
• DocBuild.py → MkDocs Engine
• MkDocs Engine → Generated Site
• CI/CD → triggers lint/tests & build → deployment
• Output → Hosting
• Blue rectangles for code artifacts (scripts, source).
• Orange clouds for external services (GitHub, Azure).