Add GitHub Pages documentation site via MkDocs

[Laveesh Rohra (larohra)]

Summary

Adds a GitHub Pages documentation site for this repo, powered by MkDocs Material, modeled on Azure/azure-functions-golang-worker PR #60 as referenced in Azure/azure-functions-bucees-planning#1283.

Closes Azure/azure-functions-bucees-planning#1283.

Sample view -

What's included

• mkdocs.yml with Material theme, navigation (Home / Getting started / Concepts / Reference), and repository edit links.
• pyproject.toml docs optional dependency extra (mkdocs-material==9.7.7) with the dependency captured in uv.lock; no standalone requirements file.
• .github/workflows/docs.yml using astral-sh/setup-uv: uv sync --extra docs --no-install-project --locked, then uv run --no-sync mkdocs build --strict; deploys only on pushes to main or manual dispatch.
• New docs/index.md and docs/getting-started.md landing/quickstart pages adapted from README.md.
• Existing docs wired into the public nav. Internal process docs (front-matter-reference.md and docs/frds/) remain intentionally out of the public nav.
• Relative links that pointed outside docs/ converted to absolute GitHub URLs so they work both on GitHub and under MkDocs.
• README, CONTRIBUTING, and AGENTS guidance updated; local preview is now uv sync --extra docs --no-install-project followed by uv run mkdocs serve.
• update-schema-docs skill extended to keep the new landing pages synchronized when schema changes add user-facing capability.

Why MkDocs

MkDocs is markdown-native, provides search/dark mode/navigation through Material, and matches the proven Azure Functions workflow pattern in PR #60. Sphinx would add unnecessary format/tooling overhead, while default Jekyll would provide weaker navigation and search.

Validation

uv sync --extra docs --no-install-project --locked and uv run --no-sync mkdocs build --strict both pass with exit code 0. Remaining output is INFO-level for intentionally omitted internal docs and pre-existing anchor/link notices.

Manual follow-up

After merge, a repo admin must set Settings → Pages → Source: GitHub Actions once. Subsequent pushes to main publish automatically.

[Laveesh Rohra (larohra)]

Copilot address these comments

[Copilot]

Pull request overview

Adds a GitHub Pages documentation site for azure-functions-agents-runtime using MkDocs Material, wiring existing docs/ content into a public nav and introducing landing/onboarding pages and a deployment workflow.

Changes:

• Add MkDocs configuration and new docs landing pages (docs/index.md, docs/getting-started.md) and link the published site from README.md.
• Introduce a docs extra in pyproject.toml for mkdocs-material and add a GitHub Actions workflow to build/deploy the site.
• Update existing docs to use GitHub-absolute links so they work both in-repo and when rendered by MkDocs.

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Adds a prominent link to the published GitHub Pages documentation site.
pyproject.toml	Adds a docs optional dependency extra for mkdocs-material.
mkdocs.yml	Configures MkDocs Material theme, extensions, validation, and navigation.
docs/workflows.md	Converts sample links to GitHub-absolute URLs for MkDocs compatibility.
docs/triggers.md	Converts sample link to GitHub-absolute URL for MkDocs compatibility.
docs/index.md	Adds a new documentation site landing page adapted from the README.
docs/getting-started.md	Adds a new documentation site onboarding/quickstart page.
docs/frds/README.md	Converts internal-process links to GitHub-absolute URLs.
docs/architecture.md	Converts README link to GitHub-absolute URL for MkDocs compatibility.
CONTRIBUTING.md	Documents local preview steps and CI behavior for docs builds.
AGENTS.md	Updates documentation conventions to include the new docs site workflow/pages.
.gitignore	Ignores MkDocs build output (site/).
.github/workflows/docs.yml	Adds build + deploy workflow for publishing docs to GitHub Pages.
.github/skills/update-schema-docs/SKILL.md	Extends the skill’s guidance to include syncing new docs landing pages on schema changes.

Suppressed comments (2)

.github/workflows/docs.yml:57

• actions/upload-pages-artifact is referenced by a moving tag (@v3). Pin it to an immutable commit SHA to reduce supply-chain risk and ensure builds are reproducible.

      - name: Upload GitHub Pages artifact
        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
        uses: actions/upload-pages-artifact@v3
        with:
          path: site

.github/workflows/docs.yml:76

• actions/deploy-pages is referenced by a moving tag (@v4). Pin it to an immutable commit SHA for reproducible deployments and reduced supply-chain risk.

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Laveesh Rohra (larohra)]

Copilot fix it

[Copilot]

Copilot fix it

Fixed in 54d874e — requirements.txt quickstart now defaults to azurefunctions-agents-runtime[monitor] with a note on omitting the extra if you don't want Azure Monitor / App Insights export. Other open threads (front-matter reference linking, uv.lock feed access) are ongoing discussions without a concrete ask, so left as-is.

[Tsuyoshi Ushio (TsuyoshiUshio)]

LGTM