feat(seo): comprehensive SEO, social sharing, and LLM discoverability (#1060)

* feat(seo): comprehensive SEO, social sharing, and LLM discoverability optimization

Add OpenGraph + Twitter Cards via sphinxext-opengraph with per-page auto-generated
social preview cards. Add JSON-LD structured data (SoftwareApplication, DataCatalog,
Dataset, BreadcrumbList) to layout.html. Create robots.txt with AI crawler rules
(GPTBot, ClaudeBot, PerplexityBot, Google-Extended). Add meta descriptions to 7 key
pages. Create llms.txt and llms-full.txt for AI agent discoverability. Expand PyPI
metadata with 18 keywords, 16 classifiers, and 8 project URLs. Generate OG social
card image (1200x630). Configure sitemap_excludes and html_title for cleaner search
results. Add sphinxext-opengraph to docs dependencies.

* fix(seo): redesign OG social card with proper MOABB brand identity

Replace generic card with brand-aligned design using the actual MOABB
palette (navy, teal, sky blue), signature three-mountain curves as
visual motif, brain logo, paradigm tag chips, stat highlights, and
a clean footer with URL, pip install command, and DOI.

* fix(seo): redesign OG card with data visualization and updated stats

Replace card with editorial-scientific design featuring:
- Paradigm distribution horizontal bar chart (P300:69, MI:62, SSVEP:16,
  c-VEP:8, RS:3) with colorblind-safe palette
- Updated stats: 158 datasets, 3.5K subjects, 9.1K sessions
- Evaluation strategies section
- Decorative EEG waveform traces
- MOABB brand logo and palette
- Clean footer with URL, pip, Python version, license, DOI

* fix(seo): redesign OG card with MOABB bubble plot and updated stats

Replace card with data-driven design featuring:
- Packed-circle visualization of all 158 datasets colored by paradigm
  (blue=MI, coral=P300, green=SSVEP, mauve=c-VEP), circle area
  proportional to subject count — the signature MOABB visual
- Updated stats: 158 datasets, 3,513 subjects
- Light background for contrast on social feeds
- Clean left panel: logo, title, subtitle, stats, color legend
- Readable at thumbnail size (600x315): title + stats + data clusters
  all clearly visible

* fix(seo): redesign OG card with MOABB bubble plot and updated stats

Replace PIL-generated card with HTML-rendered design using headless
Chrome at 2x retina resolution for crisp typography. Split-panel layout
with navy gradient left panel (clip-path diagonal, mountain motif
overlay), teal accent stripe, and light right panel featuring:

- Headline: "158 open EEG datasets for reproducible BCI benchmarking"
- Syntax-highlighted code snippet showing the real MOABB API
- Stats row: 158 datasets, 3,513 subjects, 9.1k sessions
- Paradigm pills (Motor Imagery, P300/ERP, SSVEP, c-VEP) with
  per-paradigm colors, plus tool pills (MNE-Python, scikit-learn)
- DOI and URL footer

Typography: JetBrains Mono (code/stats) + Source Serif 4 (headlines)
matching the documentation font system. Generator HTML kept at
docs/source/_static/social_card_gen.html for re-rendering when stats
change.

* fix(seo): allow crawlers to access _static/ for OG image and CSS

Remove Disallow for /docs/_static/ in robots.txt. Blocking it prevented
Googlebot and social preview crawlers from fetching the OG card image
and stylesheets, suppressing rich link previews — directly undermining
the social sharing features added in this PR.

Addresses review comment on robots.txt:17.

* feat(seo): add Google Search Console verification file

Add google07a8f2e31a591297.html to html_extra_path so it deploys at
the docs root for domain ownership verification in Google Search
Console.

* fix(docs): update dataset and subject counts across all pages

Update outdated "67+ datasets, 1735+ subjects" to the current
"158 datasets, 3500+ subjects" in homepage hero, conf.py OG/carousel,
index.rst meta description, dataset_summary.rst meta description,
llms.txt, and llms-full.txt.

* fix(seo): update OG card with full logo, Speech Imagery, and Resting State

- Use full MOABB logo (mountains + brain + wordmark) instead of icon-only
- Add Speech Imagery and Resting State paradigm pills
- Verified example code snippet imports work correctly

* fix(seo): fix OG card logo rendering and missing footer bar

- Use moabb_notext.svg (no background rect) + HTML wordmark instead of
  moabb_logo.svg which had a white rect that broke the invert filter
- Fix footer bar not rendering: switch from position:absolute to
  position:fixed for reliable anchoring in headless Chrome
- Footer now shows: moabb.neurotechx.com, pip install moabb, DOI
- BSD-3-Clause label visible on left panel above footer

* fix(seo): fix logo rendering - show full brain+mountain detail

Remove CSS filter (brightness(0) invert(1)) that was flattening the
logo into a featureless white silhouette. The original SVG colors
(light blue, teal, dark slate mountains + white brain circuits) render
correctly on the dark navy panel without any filter. Also increase
logo size from 120px to 160px for better visibility.

* fix(seo): bigger logo, matching wordmark, simpler code snippet

- Logo icon: 160px → 220px
- Wordmark: 58px → 72px to match logo proportions
- Code snippet simplified to 3-line working example:
  paradigm, evaluation, results = process(pipelines)

* fix(seo): enlarge logo, remove flat base rectangle

- Logo enlarged to 340px (fills left panel), wordmark 86px
- Cropped flat colored base from mountain SVG (the rectangular block
  at the bottom) — now shows only the mountain peaks + brain icon
- Logo embedded as data URI PNG to avoid SVG rendering issues

* fix(seo): remove hidden BSD-3 license label from OG card

* fix(seo): add CITE IF YOU USE label next to DOI in footer

* fix(ci): exclude social_card_gen.html from codespell (base64 false positive)

Author: bruAristimunha

.pre-commit-config.yaml

@@ -50,7 +50,7 @@ repos:
           - --skip="./.*,*.csv,*.json,*.ambr"
           - --quiet-level=2
         exclude_types: [ csv, json, svg, pdf ]
-        exclude: ^tests/|generated/
+        exclude: ^tests/|generated/|social_card_gen\.html$
 
   - repo: https://github.com/adrienverge/yamllint.git
     rev: v1.38.0

docs/source/_static/moabb_og_card.png

@@ -17,7 +17,7 @@
         </p>
 
         <ul class="moabb-hero-highlights mb-4">
-          <li><strong>67+ open EEG datasets, with 1735+ subjects</strong> (Motor Imagery, P300, SSVEP, and more)</li>
+          <li><strong>158 open EEG datasets, with 3500+ subjects</strong> (Motor Imagery, P300, SSVEP, c-VEP, and more)</li>
           <li><strong>Fair evaluations</strong> (within-session, cross-session, cross-subject)</li>
           <li><strong>Built on MNE + scikit-learn</strong> for flexible pipelines</li>
         </ul>

docs/source/_static/social_card_gen.html

@@ -2,6 +2,104 @@
 
 {% block extrahead %}
     <link rel="canonical" href="https://moabb.neurotechx.com/docs/{{ pagename }}.html" />
+
+    {# --- JSON-LD Structured Data --- #}
+    {% if pagename == 'index' %}
+    <script type="application/ld+json">
+    {
+      "@context": "https://schema.org",
+      "@type": "SoftwareApplication",
+      "name": "MOABB",
+      "alternateName": "Mother of all BCI Benchmarks",
+      "description": "Open-source Python package for reproducible EEG-based BCI benchmarking. Compare pipelines across 67+ datasets, multiple paradigms, and standardized evaluation strategies.",
+      "url": "https://moabb.neurotechx.com/docs/",
+      "applicationCategory": "Scientific Software",
+      "operatingSystem": "Cross-platform",
+      "programmingLanguage": "Python",
+      "license": "https://opensource.org/licenses/BSD-3-Clause",
+      "offers": {
+        "@type": "Offer",
+        "price": "0",
+        "priceCurrency": "USD"
+      },
+      "author": {
+        "@type": "Organization",
+        "name": "NeuroTechX",
+        "url": "https://neurotechx.com"
+      },
+      "codeRepository": "https://github.com/NeuroTechX/moabb",
+      "citation": {
+        "@type": "ScholarlyArticle",
+        "name": "The largest EEG-based BCI reproducibility study for open science: the MOABB benchmark",
+        "identifier": "10.5281/zenodo.10034223"
+      },
+      "softwareVersion": "{{ version }}",
+      "keywords": ["EEG", "BCI", "brain-computer interface", "benchmark", "motor imagery", "P300", "SSVEP", "neuroscience", "reproducibility", "open science"]
+    }
+    </script>
+    {% elif pagename == 'dataset_summary' %}
+    <script type="application/ld+json">
+    {
+      "@context": "https://schema.org",
+      "@type": "DataCatalog",
+      "name": "MOABB Dataset Catalog",
+      "description": "Catalog of 67+ open EEG datasets for BCI research, covering Motor Imagery, P300, SSVEP, c-VEP, and Resting State paradigms.",
+      "url": "https://moabb.neurotechx.com/docs/dataset_summary.html",
+      "provider": {
+        "@type": "Organization",
+        "name": "NeuroTechX",
+        "url": "https://neurotechx.com"
+      },
+      "keywords": ["EEG datasets", "BCI datasets", "open data", "motor imagery", "P300", "SSVEP"]
+    }
+    </script>
+    {% elif pagename.startswith('generated/moabb.datasets.') %}
+    <script type="application/ld+json">
+    {
+      "@context": "https://schema.org",
+      "@type": "Dataset",
+      "name": "{{ title | replace('moabb.datasets.', '') }}",
+      "description": "EEG dataset for brain-computer interface research, part of the MOABB benchmark suite.",
+      "url": "https://moabb.neurotechx.com/docs/{{ pagename }}.html",
+      "license": "https://opensource.org/licenses/BSD-3-Clause",
+      "isPartOf": {
+        "@type": "DataCatalog",
+        "name": "MOABB Dataset Catalog",
+        "url": "https://moabb.neurotechx.com/docs/dataset_summary.html"
+      },
+      "creator": {
+        "@type": "Organization",
+        "name": "NeuroTechX",
+        "url": "https://neurotechx.com"
+      }
+    }
+    </script>
+    {% endif %}
+
+    {# BreadcrumbList for all non-homepage pages #}
+    {% if pagename != 'index' %}
+    <script type="application/ld+json">
+    {
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      "itemListElement": [
+        {
+          "@type": "ListItem",
+          "position": 1,
+          "name": "MOABB",
+          "item": "https://moabb.neurotechx.com/docs/"
+        },
+        {
+          "@type": "ListItem",
+          "position": 2,
+          "name": "{{ title }}",
+          "item": "https://moabb.neurotechx.com/docs/{{ pagename }}.html"
+        }
+      ]
+    }
+    </script>
+    {% endif %}
+
     {{ super() }}
 {% endblock %}
 

docs/source/_templates/homepage.html

@@ -1,3 +1,7 @@
+.. meta::
+   :description: MOABB API reference - Datasets, Paradigms, Evaluations, Pipelines, and analysis tools for EEG-based BCI benchmarking in Python.
+   :keywords: MOABB API, BCI Python API, EEG analysis, motor imagery paradigm, P300 paradigm, cross-session evaluation
+
 =====================
 API and Main Concepts
 =====================

docs/source/_templates/layout.html

@@ -1,3 +1,7 @@
+.. meta::
+   :description: How to cite MOABB in academic publications. BibTeX entries for the MOABB software (Zenodo DOI 10.5281/zenodo.10034223) and the MOABB benchmark paper.
+   :keywords: cite MOABB, MOABB BibTeX, MOABB DOI, BCI benchmark citation, MOABB paper
+
 Citing MOABB and related publications
 ============================================
 

docs/source/api.rst

@@ -50,6 +50,10 @@
 # The full version, including alpha/beta/rc tags
 release = f"{moabb.__version__}-dev"
 
+# Control the page title suffix in <title> tags for SEO
+html_title = "MOABB Documentation"
+html_short_title = "MOABB"
+
 
 # -- General configuration ---------------------------------------------------
 
@@ -85,6 +89,7 @@
     "sphinx_favicon",
     "sphinxcontrib.jquery",
     "sphinx_sitemap",
+    "sphinxext.opengraph",
 ]
 
 _build_sitemap = os.environ.get("MOABB_BUILD_SITEMAP", "1").strip().lower()
@@ -315,6 +320,39 @@ def linkcode_resolve(domain, info):  # noqa: C901
 
 # Sitemap configuration
 sitemap_url_scheme = "{link}"
+sitemap_excludes = [
+    "genindex",
+    "py-modindex",
+    "search",
+    "auto_examples/*/sg_execution_times",
+    "auto_examples/sg_execution_times",
+]
+
+# -- OpenGraph / social sharing meta tags (sphinxext-opengraph) -----------
+ogp_site_url = "https://moabb.neurotechx.com/docs/"
+ogp_site_name = "MOABB - Mother of all BCI Benchmarks"
+ogp_image = "https://moabb.neurotechx.com/docs/_static/moabb_og_card.png"
+ogp_image_alt = (
+    "MOABB - Mother of all BCI Benchmarks: "
+    "158 open EEG datasets for reproducible BCI research"
+)
+ogp_description_length = 200
+ogp_type = "website"
+ogp_custom_meta_tags = [
+    '<meta name="twitter:card" content="summary_large_image" />',
+    '<meta name="twitter:site" content="@NeuroTechX" />',
+]
+
+# Auto-generate unique social preview cards per page (uses matplotlib).
+# Each page gets its own card with the page title, site name, and description.
+# The static moabb_og_card.png is the fallback for pages without auto-generated cards.
+ogp_social_cards = {
+    "image": "_static/moabb_logo.png",
+    "line_color": "#4a90d9",
+}
+
+# Extra files to copy to build output root (robots.txt, llms.txt, etc.)
+html_extra_path = ["robots.txt", "llms.txt", "llms-full.txt", "google07a8f2e31a591297.html"]
 
 html_css_files = [
     "css/custom.css",
@@ -385,7 +423,7 @@ def linkcode_resolve(domain, info):  # noqa: C901
     "carousel": [
         dict(
             title="Datasets",
-            text="Access 67+ open EEG datasets for motor imagery, P300, and SSVEP paradigms.",
+            text="Access 158 open EEG datasets for motor imagery, P300, SSVEP, and c-VEP paradigms.",
             url="dataset_summary.html",
             img="datasets_overview.png",
             alt="Datasets overview",

docs/source/cite.rst

@@ -1,3 +1,7 @@
+.. meta::
+   :description: Browse 158 open EEG datasets for BCI research in MOABB. Filter by paradigm (Motor Imagery, P300, SSVEP, c-VEP), subject count, channels, and license. Interactive table with CSV export.
+   :keywords: EEG datasets, BCI datasets, motor imagery dataset, P300 dataset, SSVEP dataset, open EEG data, brain-computer interface data
+
 .. _data_summary:
 
 .. automodule:: moabb.datasets

docs/source/conf.py

@@ -0,0 +1 @@
+google-site-verification: google07a8f2e31a591297.html