From f4042b9acc2a522268fbd8a1b979d34b0970491e Mon Sep 17 00:00:00 2001
From: aryasadeghi1 <aryasadeghi@microsoft.com>
Date: Fri, 17 Jul 2026 17:21:32 +1000
Subject: [PATCH] docs: derive site version from the latest GitHub release

The version chip in the docs header rendered site.version, a string
hard-coded in docs/_config.yml that had to be bumped by hand every
release. It drifts: dev currently carries v4.6.1 while the latest release
is v4.6.0, so the published site advertises a version that isn't out yet.

Read the version from site.github.latest_release instead and drop the
config key. That metadata comes from jekyll-github-metadata, which GitHub
Pages always has enabled. Local builds without a token resolve it to
nothing, so the header hides the chip instead of showing an empty value.

Pages only rebuilds on a push to its source branch, and the release is
published after that push, so add a step to the release job that requests
a Pages rebuild once the release exists. It has to live in that job: a
release created with GITHUB_TOKEN doesn't emit an event that a separate
workflow could trigger on.

Closes #561
---
 .github/workflows/python-publish.yml | 13 +++++++++++++
 docs/_config.yml                     |  7 ++++---
 docs/_includes/header.html           |  9 ++++++++-
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml
index dac76bf7..5b1effb8 100644
--- a/.github/workflows/python-publish.yml
+++ b/.github/workflows/python-publish.yml
@@ -169,6 +169,9 @@ jobs:
     name: Release
     runs-on: ubuntu-latest
     needs: [checks]
+    permissions:
+      contents: write
+      pages: write
     if: startsWith(github.ref, 'refs/tags/')
     steps:
       - uses: actions/checkout@v1
@@ -207,3 +210,13 @@ jobs:
           prerelease: ${{ contains(env.TAG, 'rc') }}
           files: |
             dist/*
+
+      # The docs header reads the version from the latest release, but Pages only
+      # rebuilds on a push to its branch, and the release lands after that push.
+      # Ask for a rebuild here so the site picks up the tag we just published.
+      # Has to live in this job: a release made with GITHUB_TOKEN doesn't fire the
+      # release event, so a workflow keyed on it would never run.
+      - name: Rebuild docs site
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh api --method POST repos/${{ github.repository }}/pages/builds
diff --git a/docs/_config.yml b/docs/_config.yml
index f4438765..ed2b7344 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -33,10 +33,11 @@ url: "https://azure.github.io" # the base hostname & protocol for your site, e.g
 github:
   repo: https://github.com/Azure/aaz-dev-tools
 
-pypi: https://pypi.org/project/aaz-dev/
+# Used by jekyll-github-metadata to resolve site.github.* when building outside
+# of GitHub Pages. Pages infers it, local builds wont.
+repository: Azure/aaz-dev-tools
 
-# TODO: get version number from github
-version: v4.6.1
+pypi: https://pypi.org/project/aaz-dev/
 
 # Build settings
 theme: minima
diff --git a/docs/_includes/header.html b/docs/_includes/header.html
index 8bf41728..f6fa08ed 100644
--- a/docs/_includes/header.html
+++ b/docs/_includes/header.html
@@ -27,12 +27,19 @@
           ></path></svg
         ><span class="h4 text-semibold ml-2">GitHub Repo</span></a
       >
+      {% comment %}
+        Populated from the latest GitHub release. Empty on local builds without
+        a JEKYLL_GITHUB_TOKEN, so hide the whole block rather than show a blank.
+      {% endcomment %}
+      {% assign latest_version = site.github.latest_release.tag_name %}
+      {% if latest_version %}
       <div class="hide-sm border-left">
         <div class="pl-2 pr-2">
           <span class="color-fg-muted text-normal">Version: </span>
-          <span>{{ site.version }}</span>
+          <span>{{ latest_version }}</span>
         </div>
       </div>
+      {% endif %}
     </div>
   </div>
 </header>