docs(seo): hub 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   # full history so git-revision-date-localized can read last-modified dates
 
       - uses: actions/setup-python@v5
         with:

docs-requirements.txt

@@ -2,6 +2,8 @@ mkdocs
 mkdocs-get-deps
 mkdocs-material
 mkdocs-material-extensions
+mkdocs-callouts
+mkdocs-git-revision-date-localized-plugin
 pymdown-extensions
 mkdocstrings
 mkdocstrings-python

docs/index.md

@@ -1,16 +1,17 @@
 ---
-description: "PyTorch-Wildlife: open-source AI platform for wildlife monitoring. MegaDetector, MegaDetector-Acoustic, MegaDetector-Overhead, SPARROW Studio. pip install PytorchWildlife."
+title: "Microsoft Biodiversity: Open-Source Conservation AI Hub"
+description: "Microsoft AI for Good Lab's open-source conservation AI hub for biodiversity and wildlife monitoring: MegaDetector, PyTorch-Wildlife, SPARROW, and more."
 tags:
+  - Microsoft biodiversity AI
+  - open source conservation AI
+  - wildlife monitoring AI tools
+  - AI for Good biodiversity
   - MegaDetector
-  - camera trap AI
-  - wildlife detection
   - PyTorch-Wildlife
   - conservation AI
-  - bioacoustics
-  - overhead detection
 ---
 
-![Biodiversity banner showing animals monitored by AI — camera traps, bioacoustics, and aerial detection — powered by PyTorch-Wildlife and MegaDetector](https://zenodo.org/records/20044680/files/Biodiversity_Banner.png)
+![Microsoft Biodiversity banner showing wildlife monitored by AI across camera traps, bioacoustics, and aerial detection, powered by PyTorch-Wildlife and MegaDetector](assets/biodiversity-banner.png)
 
 <div align="center"> 
 <font size="6"> Open-source AI for camera traps, bioacoustics, and wildlife monitoring </font>

mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: Microsoft Biodiversity
 site_url: https://microsoft.github.io/Biodiversity/
-site_description: "PyTorch-Wildlife — open-source AI for camera traps, bioacoustics, and wildlife monitoring. Includes MegaDetector, MegaDetector-Acoustic, MegaDetector-Overhead, and SPARROW Studio."
+site_description: "Microsoft AI for Good Lab Biodiversity hub: open-source conservation AI for wildlife monitoring. Home of MegaDetector, PyTorch-Wildlife, SPARROW, and MegaDetector-Acoustic."
 docs_dir: docs
 site_dir: site
 repo_url: https://github.com/microsoft/Biodiversity
@@ -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
@@ -181,9 +182,14 @@ markdown_extensions:
 
 
 plugins:
+  - callouts
   - search
   - meta
   - tags
+  - git-revision-date-localized:
+      type: date
+      enable_creation_date: true
+      fallback_to_build_date: true
   - mkdocstrings:
       handlers:
         python:

overrides/main.html

@@ -0,0 +1,106 @@
+{% 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, cannot be copied
+  between pages by accident) rather than a front-matter flag.
+
+  This is the cluster hub, so the homepage carries an Organization entity for
+  the Microsoft AI for Good Lab Biodiversity initiative plus an ItemList that
+  enumerates the sub-projects — the entity anchor that ties the cluster's five
+  documentation sites together for search engines. Interior pages carry a
+  BreadcrumbList. The pattern mirrors microsoft/MegaDetector/overrides/main.html.
+#}
+
+{% block htmltitle %}
+  {%- if page and page.file and page.file.src_path == "index.md" -%}
+  <title>Microsoft Biodiversity: Open-Source AI for Conservation | AI for Good Lab</title>
+  {%- else -%}
+  {{ super() }}
+  {%- endif -%}
+{% endblock %}
+
+{% block extrahead %}
+  {{ super() }}
+
+  {#- Open Graph / Twitter Card social metadata (per-page title/description, local share image) -#}
+  {%- 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/biodiversity-banner.png">
+  <meta property="og:image:alt" content="Microsoft Biodiversity: open-source conservation AI from the 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/biodiversity-banner.png">
+  <meta name="twitter:image:alt" content="Microsoft Biodiversity: open-source conservation AI from the 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" %}
+  {#- Homepage: a connected @graph. The page's main entity is the project
+     collection (CollectionPage -> ItemList), not the Lab itself; the Lab is
+     the publisher Organization. -#}
+  <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" },
+        "sameAs": ["https://github.com/microsoft/Biodiversity"]
+      },
+      {
+        "@type": "CollectionPage",
+        "@id": config.site_url ~ "#webpage",
+        "url": config.site_url,
+        "name": "Microsoft Biodiversity: Open-Source Conservation AI Hub",
+        "inLanguage": "en",
+        "description": config.site_description,
+        "isPartOf": { "@id": config.site_url ~ "#website" },
+        "about": { "@id": "https://www.microsoft.com/en-us/ai/ai-for-good#organization" },
+        "mainEntity": { "@id": config.site_url ~ "#projects" }
+      },
+      {
+        "@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"
+      },
+      {
+        "@type": "ItemList",
+        "@id": config.site_url ~ "#projects",
+        "name": "Microsoft Biodiversity ecosystem projects",
+        "itemListElement": [
+          { "@type": "ListItem", "position": 1, "name": "MegaDetector",         "url": "https://microsoft.github.io/MegaDetector/" },
+          { "@type": "ListItem", "position": 2, "name": "PyTorch-Wildlife",      "url": "https://microsoft.github.io/Pytorch-Wildlife/" },
+          { "@type": "ListItem", "position": 3, "name": "SPARROW",               "url": "https://microsoft.github.io/SPARROW/" }
+        ]
+      }
+    ]
+  } | tojson -}}
+  </script>
+  {%- endif %}
+
+  {%- if page and page.file and page.file.src_path != "index.md" and page.canonical_url %}
+  {#- Interior pages only: BreadcrumbList (no breadcrumb on the homepage) -#}
+  <script type="application/ld+json">
+  {{- {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "itemListElement": [
+      { "@type": "ListItem", "position": 1, "name": "Microsoft Biodiversity", "item": config.site_url },
+      { "@type": "ListItem", "position": 2, "name": page.title | striptags, "item": page.canonical_url }
+    ]
+  } | tojson -}}
+  </script>
+  {%- endif %}
+{% endblock %}