Merge pull request #15 from microsoft/seo/pw-infra-structured-data

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

Author: zhmiao

.github/workflows/deploy-docs.yml

@@ -6,8 +6,10 @@ on:
       - main
     paths:
       - 'docs/**'
+      - 'overrides/**'
       - 'mkdocs.yml'
       - 'docs-requirements.txt'
+  workflow_dispatch:
 
 jobs:
   deploy:
@@ -16,6 +18,8 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:

docs-requirements.txt

@@ -5,3 +5,5 @@ mkdocs-material-extensions
 pymdown-extensions
 mkdocstrings
 mkdocstrings-python
+mkdocs-callouts
+mkdocs-git-revision-date-localized-plugin

docs/assets/cat.png

@@ -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

mkdocs.yml

@@ -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. 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>PyTorch-Wildlife: Open-Source Conservation Deep Learning Framework | 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="PyTorch-Wildlife: open-source conservation deep learning framework 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="PyTorch-Wildlife: open-source conservation deep learning framework 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": "Python",
+        "isAccessibleForFree": true,
+        "license": "https://github.com/microsoft/Pytorch-Wildlife/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/Pytorch-Wildlife", "https://pypi.org/project/PytorchWildlife/", "https://arxiv.org/abs/2405.12930"],
+        "keywords": ["PyTorch-Wildlife", "wildlife AI framework", "conservation deep learning framework", "wildlife model zoo", "camera trap detection", "species classification"]
+      },
+      {
+        "@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": "PyTorch-Wildlife", "item": config.site_url },
+      { "@type": "ListItem", "position": 2, "name": page.title | striptags, "item": page.canonical_url }
+    ]
+  } | tojson -}}
+  </script>
+  {%- endif %}
+{% endblock %}