From 2879f489c4c1798cb4bd36e09b08f665ddbc0587 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Tue, 11 Aug 2026 05:33:42 +0200
Subject: [PATCH] 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 | 30 ++++++++++++++++++++++++++++++
mkdocs.yml | 22 ++++++++++++++++++----
scripts/generate_site.py | 4 ++++
3 files changed, 52 insertions(+), 4 deletions(-)
create mode 100644 docs_assets/overrides/main.html
diff --git a/docs_assets/overrides/main.html b/docs_assets/overrides/main.html
new file mode 100644
index 00000000..3bce5e10
--- /dev/null
+++ b/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 '' %}
+
+
+
+
+
+ {% if page_url %}{% endif %}
+ {% if preview_image %}{% endif %}
+
+
+
+
+ {% if preview_image %}{% endif %}
+{% endblock %}
diff --git a/mkdocs.yml b/mkdocs.yml
index 0b155c15..24cb28de 100644
--- a/mkdocs.yml
+++ b/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
diff --git a/scripts/generate_site.py b/scripts/generate_site.py
index 11b24416..e8e5d3ad 100644
--- a/scripts/generate_site.py
+++ b/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: