Add commit shasums and last updated date on documentation site

Note: Some plugins, such as mkdocs-macros-plugin, can retrieve Git details, but they offer limited flexibility in terms of information placement, styling, and formatting. A better approach was to create a custom hook and override the header.

Author: ShahanaFarooqui

docs/hooks/git-info.py

@@ -0,0 +1,40 @@
+import subprocess
+import os
+
+def on_config(config):
+    """
+    Hook to add git commit information. This runs once when MkDocs loads the config.
+    """
+    try:
+        repo_root = os.path.dirname(os.path.abspath(config.config_file_path))
+        commit_hash = os.environ.get('DOCS_COMMIT_SHA')
+        
+        if commit_hash:
+            print(f"Using commit from DOCS_COMMIT_SHA env: {commit_hash[:7]}")
+            short_hash = commit_hash[:7]
+            commit_date = subprocess.check_output(
+                ['git', 'log', '-1', '--format=%cd', '--date=short', commit_hash],
+                cwd=repo_root,
+                stderr=subprocess.STDOUT
+            ).decode('utf-8').strip()
+            print(f"Git hook: Loaded commit info {short_hash} • {commit_date}")
+        else:
+            # No commit details in not provided via env
+            print("DOCS_COMMIT_SHA not set")
+        
+        # Add to extra context (available in templates if needed)
+        if 'extra' not in config:
+            config['extra'] = {}
+        
+        config['extra']['git'] = {
+            'commit': commit_hash,
+            'short_commit': short_hash,
+            'date': commit_date,
+        }
+        
+    except subprocess.CalledProcessError as e:
+        print(f"Warning: Could not get git information: {e}")
+    except Exception as e:
+        print(f"Warning: Error in git hook: {e}")
+
+    return config

docs/mkdocs.yml

@@ -4,13 +4,10 @@ docs_dir: src
 repo_url: https://github.com/Blockstream/greenlight
 edit_uri: tree/main/docs/src
 
-plugins:
-  - search
-  - social
-  - redirects:
-      redirect_maps:
-        'reference/partner-certs.md': 'getting-started/certs.md'
-
+hooks:
+  - hooks/git-info.py
+extra_css:
+  - assets/stylesheets/git-info.css
 markdown_extensions:
   - admonition
   - attr_list
@@ -33,6 +30,7 @@ markdown_extensions:
       base_path: ["../examples/rust/snippets", "../examples/python/snippets"]
 theme:
   name: material
+  custom_dir: overrides
   logo: assets/logo.png
   favicon: assets/logo.png
   palette:
@@ -53,14 +51,13 @@ theme:
       toggle:
         icon: material/weather-sunny
         name: Switch to light mode
-
   features:
     - navigation.tabs
-    - content.code.annotate
     - navigation.instant
     - navigation.tabs.sticky
     - navigation.sections
     - navigation.indexes
+    - content.code.annotate
     - content.tabs.link
     - content.code.copy
 
@@ -93,3 +90,7 @@ nav:
     - About: about/index.md
     - Frequently Asked Questions: about/faq.md
     - Changelog: about/changelog.md
+extra:
+  generator: false
+copyright: |
+  © 2024 Greenlight All rights reserved.

docs/overrides/partials/header.html

@@ -0,0 +1,85 @@
+{%- set class = "md-header" -%}
+{%- if "navigation.tabs.sticky" in features -%}
+  {%- set class = class ~ " md-header--shadow md-header--lifted" -%}
+{%- elif "navigation.tabs" not in features -%}
+  {%- set class = class ~ " md-header--shadow" -%}
+{%- endif -%}
+<header class="{{ class }}" data-md-component="header">
+  <nav class="md-header__inner md-grid" aria-label="{{ lang.t('header') }}">
+    <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
+      {% include "partials/logo.html" %}
+    </a>
+    <label class="md-header__button md-icon" for="__drawer">
+      {% set icon = config.theme.icon.menu or "material/menu" %}
+      {% include ".icons/" ~ icon ~ ".svg" %}
+    </label>
+    <div class="md-header__title" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        <div class="md-header__topic">
+          <span class="md-ellipsis">
+            {{ config.site_name }}
+          </span>
+        </div>
+        <div class="md-header__topic" data-md-component="header-topic">
+          <span class="md-ellipsis">
+            {% if page.meta and page.meta.title %}
+              {{ page.meta.title }}
+            {% else %}
+              {{ page.title }}
+            {% endif %}
+          </span>
+        </div>
+      </div>
+    </div>
+    {% if config.theme.palette %}
+      {% if not config.theme.palette is mapping %}
+        {% include "partials/palette.html" %}
+      {% endif %}
+    {% endif %}
+    {% if config.extra.alternate %}
+      {% include "partials/alternate.html" %}
+    {% endif %}
+    {% if "material/search" in config.plugins %}
+      <label class="md-header__button md-icon" for="__search">
+        {% set icon = config.theme.icon.search or "material/magnify" %}
+        {% include ".icons/" ~ icon ~ ".svg" %}
+      </label>
+      {% include "partials/search.html" %}
+    {% endif %}
+    {% if config.repo_url %}
+      <div class="md-header__source">
+        {% include "partials/source.html" %}
+        {% if config.extra.git %}
+        <div class="git-info-bar">
+          <div class="md-grid">
+            <div class="git-info-item">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M11.93 8.5a4.002 4.002 0 0 1-7.86 0H.75a.75.75 0 0 1 0-1.5h3.32a4.002 4.002 0 0 1 7.86 0h3.32a.75.75 0 0 1 0 1.5Zm-1.43-.75a2.5 2.5 0 1 0-5 0 2.5 2.5 0 0 0 5 0Z"/>
+              </svg>
+              <a href="{{ config.repo_url }}/commit/{{ config.extra.git.commit }}" target="_blank" title="Go to Commit">
+                {{ config.extra.git.short_commit }}
+              </a>
+            </div>
+            <div class="git-info-item" title="Last Updated">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm7-3.25v2.992l2.028.812a.75.75 0 0 1-.557 1.392l-2.5-1A.751.751 0 0 1 7 8.25v-3.5a.75.75 0 0 1 1.5 0Z"/>
+              </svg>
+              {{ config.extra.git.date }}
+            </div>
+          </div>
+        </div>
+        {% endif %}
+      </div>
+    {% endif %}
+  </nav>
+  {% if "navigation.tabs.sticky" in features %}
+    {% if "navigation.tabs" in features %}
+      {% include "partials/tabs.html" %}
+    {% endif %}
+  {% endif %}
+</header>
+{% if "navigation.tabs" in features %}
+  {% if "navigation.tabs.sticky" not in features %}
+    {% include "partials/tabs.html" %}
+  {% endif %}
+{% endif %}

docs/src/assets/stylesheets/git-info.css

@@ -0,0 +1,34 @@
+.git-info-bar {
+  font-size: 0.5rem;
+}
+
+.git-info-bar .md-grid {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  opacity: .75;
+}
+
+.git-info-item {
+  display: flex;
+  align-items: center;
+  gap: 0.2rem;
+  padding-right: 0.3rem;
+}
+
+.git-info-item:last-child {
+  padding-right: 1rem;
+}
+
+.git-info-item svg {
+  width: 0.5rem;
+  height: 0.5rem;
+}
+
+.git-info-item a {
+  text-decoration: none;
+}
+
+.git-info-item a:hover {
+  text-decoration: none;
+}