feat: give every page a link preview

Links to this site get shared on Discord, Reddit and forums, where a
page with no Open Graph tags renders as a grey rectangle. The pages
already carry a per-page title and description, so a theme override
fills the tags from those; mkdocs-material would otherwise only emit
them through its social plugin, which pulls in Pillow and CairoSVG to
render a preview image these pages do not need.

docs_assets/overrides/main.html

@@ -0,0 +1,30 @@
+{% extends "base.html" %}
+
+{#
+  Open Graph and Twitter card tags.
+
+  mkdocs-material only emits these through its social plugin, which pulls in
+  Pillow and CairoSVG to render preview images. The pages here already carry a
+  per-page title and description, so the tags can be filled from those without
+  taking on two image dependencies. The links get shared on Discord, Reddit and
+  forums, where a bare URL with no preview is the difference between a card and
+  a grey rectangle.
+#}
+{% block extrahead %}
+  {% set page_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 page_description = page.meta.description if page and page.meta and page.meta.description else config.site_description %}
+  {% set page_url = page.canonical_url if page and page.canonical_url else config.site_url %}
+  {% set preview_image = config.site_url ~ 'assets/images/logo.png' if config.site_url else '' %}
+
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="{{ config.site_name }}">
+  <meta property="og:title" content="{{ page_title }}">
+  <meta property="og:description" content="{{ page_description }}">
+  {% if page_url %}<meta property="og:url" content="{{ page_url }}">{% endif %}
+  {% if preview_image %}<meta property="og:image" content="{{ preview_image }}">{% endif %}
+
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="{{ page_title }}">
+  <meta name="twitter:description" content="{{ page_description }}">
+  {% if preview_image %}<meta name="twitter:image" content="{{ preview_image }}">{% endif %}
+{% endblock %}

mkdocs.yml

@@ -16,6 +16,10 @@ copyright: MIT for the tooling. BIOS and firmware files are third-party system
   software, preserved for personal backup, archival and interoperability.
 theme:
   name: material
+  # Open Graph tags live in overrides/main.html: the social plugin that
+  # would otherwise emit them needs Pillow and CairoSVG only to render a
+  # preview image the pages do not need.
+  custom_dir: docs_assets/overrides
   palette:
   - media: (prefers-color-scheme)
     toggle:
@@ -188,6 +192,7 @@ nav:
   - Timex: systems/timex.md
   - Tomy: systems/tomy.md
   - VTech: systems/vtech.md
+  - Videoton: systems/videoton.md
   - Vircon: systems/vircon.md
   - ZC: systems/zc.md
   - sdlpal: systems/sdlpal.md
@@ -258,13 +263,18 @@ nav:
     - vitaQuakeII: emulators/vitaquake2.md
     - yabasanshiro: emulators/yabasanshiro.md
     - Yuzu: emulators/yuzu.md
-  - Community forks (119):
+  - Community forks (125):
     - 2600.emu: emulators/2600-emu.md
     - EightyOne: emulators/81.md
     - a5200: emulators/a5200.md
     - ACE-DL: emulators/ace-dl.md
+    - AetherSX2: emulators/aethersx2.md
     - Anarch: emulators/anarch.md
     - AppleWin: emulators/applewin.md
+    - aPS3e: emulators/aps3e.md
+    - ARMSX1: emulators/armsx1.md
+    - ARMSX2: emulators/armsx2.md
+    - aX360e: emulators/ax360e.md
     - Azahar: emulators/azahar.md
     - AzaharPlus: emulators/azaharplus.md
     - b2: emulators/b2.md
@@ -279,6 +289,7 @@ nav:
     - bk-emulator: emulators/bk.md
     - blueMSX: emulators/bluemsx.md
     - bsnes-jg: emulators/bsnes-jg.md
+    - C64.emu: emulators/c64-emu.md
     - Caprice32: emulators/cap32.md
     - ChimeraSNES: emulators/chimerasnes.md
     - Citra: emulators/citra.md
@@ -513,18 +524,21 @@ nav:
     - Stone Soup: emulators/stonesoup.md
     - UME 2015: emulators/ume2015.md
     - VBA-Next: emulators/vba_next.md
-  - Embedded HLE (5):
+  - Embedded HLE (6):
     - 3dSen: emulators/3dsen.md
+    - Altirra: emulators/altirra.md
     - izapple2: emulators/izapple2.md
     - Lindbergh Loader: emulators/lindbergh-loader.md
     - MFME: emulators/mfme.md
     - PCSX-ReARMed: emulators/pcsx_rearmed.md
-  - Launchers (2):
+  - Launchers (3):
+    - ArcadeFlashWeb: emulators/arcadeflashweb.md
     - Dolphin Launcher: emulators/dolphin_launcher.md
     - Parallel Launcher: emulators/parallel-launcher.md
-  - Other (37):
+  - Other (38):
     - ares: emulators/ares.md
     - Basilisk II: emulators/basiliskii.md
+    - beebem: emulators/beebem.md
     - Beetle GBA (Mednafen): emulators/beetle_gba.md
     - BigPEmu: emulators/bigpemu.md
     - Cemu: emulators/cemu.md

scripts/generate_site.py

@@ -4051,6 +4051,10 @@ copyright: MIT for the tooling. BIOS and firmware files are third-party system
   software, preserved for personal backup, archival and interoperability.
 theme:
   name: material
+  # Open Graph tags live in overrides/main.html: the social plugin that
+  # would otherwise emit them needs Pillow and CairoSVG only to render a
+  # preview image the pages do not need.
+  custom_dir: docs_assets/overrides
   palette:
   - media: (prefers-color-scheme)
     toggle: