docs(seo): SPARROW structured-data + social + self-hosted assets parity

.github/workflows/deploy-docs.yml

@@ -16,6 +16,8 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:

docs-requirements.txt

@@ -4,3 +4,5 @@ mkdocs-material-extensions>=1.3
 pymdown-extensions>=10.0
 mkdocstrings>=0.27
 mkdocstrings-python>=1.0
+mkdocs-callouts
+mkdocs-git-revision-date-localized-plugin

mkdocs.yml

@@ -9,8 +9,9 @@ copyright: Copyright (c) 2023 Microsoft Corporation
 
 theme:
   name: material
-  favicon: https://zenodo.org/records/15376499/files/cat.png
-  logo: https://zenodo.org/records/15376499/files/cat.png
+  custom_dir: overrides
+  favicon: assets/cat.png
+  logo: assets/cat.png
   icon:
     menu: material/menu
     alternate: material/translate
@@ -99,6 +100,11 @@ markdown_extensions:
       pygments_lang_class: true
 
 plugins:
+  - callouts
   - search
   - meta
   - tags
+  - git-revision-date-localized:
+      type: date
+      enable_creation_date: true
+      fallback_to_build_date: true

overrides/main.html

@@ -0,0 +1,90 @@
+{% extends "base.html" %}
+
+{#
+  Theme override for SEO structured data and a clean homepage <title>.
+  Schema is gated on page.file.src_path (unique per page). Homepage uses a
+  connected @graph (WebSite + SoftwareSourceCode + Organization) per schema review.
+#}
+
+{% block htmltitle %}
+  {%- if page and page.file and page.file.src_path == "index.md" -%}
+  <title>SPARROW: Solar-Powered Edge AI for Biodiversity Monitoring | Microsoft AI for Good</title>
+  {%- else -%}
+  {{ super() }}
+  {%- endif -%}
+{% endblock %}
+
+{% block extrahead %}
+  {{ super() }}
+
+  {%- set social_title = page.meta.title if page and page.meta and page.meta.title else (page.title if page and page.title else config.site_name) -%}
+  {%- set social_desc = page.meta.description if page and page.meta and page.meta.description else config.site_description -%}
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="{{ config.site_name }}">
+  <meta property="og:title" content="{{ social_title | striptags }}">
+  <meta property="og:description" content="{{ social_desc | striptags }}">
+  <meta property="og:url" content="{{ page.canonical_url if page and page.canonical_url else config.site_url }}">
+  <meta property="og:image" content="{{ config.site_url }}assets/cat.png">
+  <meta property="og:image:alt" content="SPARROW: solar-powered edge AI device for biodiversity monitoring by Microsoft AI for Good Lab">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="{{ social_title | striptags }}">
+  <meta name="twitter:description" content="{{ social_desc | striptags }}">
+  <meta name="twitter:image" content="{{ config.site_url }}assets/cat.png">
+  <meta name="twitter:image:alt" content="SPARROW: solar-powered edge AI device for biodiversity monitoring by Microsoft AI for Good Lab">
+  {#- TODO(design): swap in a 1200x630 banner + add og:image:width/height when delivered -#}
+
+  {%- if page and page.file and page.file.src_path == "index.md" %}
+  <script type="application/ld+json">
+  {{- {
+    "@context": "https://schema.org",
+    "@graph": [
+      {
+        "@type": "WebSite",
+        "@id": config.site_url ~ "#website",
+        "url": config.site_url,
+        "name": config.site_name,
+        "inLanguage": "en",
+        "description": config.site_description,
+        "publisher": { "@id": "https://www.microsoft.com/en-us/ai/ai-for-good#organization" }
+      },
+      {
+        "@type": "SoftwareSourceCode",
+        "@id": config.site_url ~ "#software",
+        "name": config.site_name,
+        "description": config.site_description,
+        "url": config.site_url,
+        "mainEntityOfPage": config.site_url,
+        "codeRepository": config.repo_url,
+        "programmingLanguage": "Python",
+        "runtimePlatform": "NVIDIA Jetson",
+        "isAccessibleForFree": true,
+        "license": "https://github.com/microsoft/SPARROW/blob/main/LICENSE",
+        "creator": { "@id": "https://www.microsoft.com/en-us/ai/ai-for-good#organization" },
+        "maintainer": { "@id": "https://www.microsoft.com/en-us/ai/ai-for-good#organization" },
+        "sameAs": ["https://github.com/microsoft/SPARROW"],
+        "keywords": ["SPARROW", "edge AI biodiversity", "solar powered camera trap", "NVIDIA Jetson camera trap", "Starlink wildlife", "remote wildlife monitoring", "bioacoustic edge device"]
+      },
+      {
+        "@type": "Organization",
+        "@id": "https://www.microsoft.com/en-us/ai/ai-for-good#organization",
+        "name": "Microsoft AI for Good Lab",
+        "url": "https://www.microsoft.com/en-us/ai/ai-for-good"
+      }
+    ]
+  } | tojson -}}
+  </script>
+  {%- endif %}
+
+  {%- if page and page.file and page.file.src_path != "index.md" and page.canonical_url %}
+  <script type="application/ld+json">
+  {{- {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "itemListElement": [
+      { "@type": "ListItem", "position": 1, "name": "SPARROW", "item": config.site_url },
+      { "@type": "ListItem", "position": 2, "name": page.title | striptags, "item": page.canonical_url }
+    ]
+  } | tojson -}}
+  </script>
+  {%- endif %}
+{% endblock %}