test: move social parity matrix to compatibility suite

Signed-off-by: squidfunk <martin.donath@squidfunk.com>
2026-10-08 05:41:24 +00:00 · 2026-09-30 09:59:03 +02:00
1 parent 9f9b25b7ab
commit 49b2d94be4
@@ -1,69 +0,0 @@
-# Social plugin compatibility matrix
-
-These projects compare the user-visible output of Material for MkDocs and
-Zensical with the same `mkdocs.yml` and source files. Run the matrix from the
-repository root:
-
-```console
-/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/bin/python \
-  scripts/social_compatibility.py \
-  --mkdocs /Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/bin/mkdocs \
-  --zensical .venv/bin/zensical
-```
-
-| Case | Behavior |
-| --- | --- |
-| `basic` | Custom layout, root and nested card routes, page title and metadata |
-| `filters` | Include precedence, exclude patterns, page-level opt-out |
-| `metadata` | Meta plugin inheritance and page-level layout options |
-| `multiple` | Ordered plugin instances, separate card directories and metadata |
-| `no-site-url` | Cards generated without public image metadata |
-| `image-only` | Bundled image-only layout and a local SVG dependency |
-| `bundled` | Default, accent, invert and variant layouts with typography |
-| `logo-icon` | Explicit theme logo icon and omitted font settings |
-| `debug` | Build-time debug grid and color settings |
-| `blog` | Cards for generated blog views and posts |
-| `disabled` | Disabled plugin stays disabled despite a page opt-in |
-| `cards-off` | Global card switch with a page-level opt-in |
-| `paths` | Flat URLs, alternate card directory and custom layout directory |
-| `layout-options` | Bundled-layout image, logo, title, description and page overrides |
-| `layer-composition` | YAML definitions, SVG background, icon, origins and offsets |
-| `theme-defaults` | Palette list, SVG/PNG logos, exact font face and variant fallback |
-| `custom-typography` | Custom alignment, wrapping, shrinking and line spacing |
-| `template-context` | Page file and URL values inside custom tag templates |
-| `lifecycle` | Cached rebuilds after image, page metadata and layout edits |
-| `recoverable-error` | Missing image with ignored card-generation error |
-| `deprecated` | Deprecated `cards_color` and `cards_font` settings |
-| `debug-no-grid` | Debug overlay without a grid |
-
-The check compares generated card paths, dimensions and every card's mean RGB
-pixel difference, plus each page's social metadata. A case passes when the
-metadata and dimensions match and every card's mean RGB difference is at most
-1 on a 0–255 scale. The `lifecycle` case also rebuilds both engines after each
-exact source edit and checks that the expected output changed. PNG file bytes
-may differ between image libraries even when the visible output is the same.
-Build logs and full output are kept in a temporary directory only while the
-command runs; pass `--output PATH` to keep them for inspection.
-
-The cases using typography or debug labels download Roboto from Google Fonts
-on their first build. Use `--font-cache PATH` to seed both temporary projects
-from an existing Material font cache and run without a network connection.
-
-On 2026-09-23, 19 of 22 cases passed the strict pixel threshold using Material
-for MkDocs 9.7.1 with Pillow 12.1.1 and this Zensical branch. One remaining
-case is an accepted rasterization difference; the other two are behavior gaps:
-
- `custom-typography`: text placement matches visually. Different text
-  rasterizers exceed the strict pixel threshold (maximum mean RGB difference
-  3.636), but this is not considered a user-visible defect.
- `template-context`: Material exposes `page.file.src_uri` to layout templates;
-  the Zensical build fails because that value is undefined.
- `lifecycle`: after a cached SVG background edit, Material retains its old
-  card while Zensical updates it. The initial build and later layout edit match.
-
-The full matrix currently exits nonzero because of the strict pixel threshold
-and the two behavior gaps.
-It does not prove every custom layout, live `serve` edit, remote font, or error
-policy combination. Configuration keys are represented across this matrix and
-the Python integration tests, but a finite set of cases cannot prove universal
-behavioral parity.
@@ -1 +0,0 @@
-# Advanced
@@ -1 +0,0 @@
-# Guide
@@ -1,6 +0,0 @@
---
-title: Home & Intro
-description: A concise & useful description.
---
-
-# Welcome
@@ -1,12 +0,0 @@
-tags:
-  og:type: website
-  og:title: '{{ page.meta.get("title", page.title) }}'
-  og:description: '{{ page.meta.get("description", config.site_description) | x }}'
-  og:image: '{{ image.url }}'
-  og:image:width: '{{ image.width }}'
-  og:image:height: '{{ image.height }}'
-  og:url: '{{ page.canonical_url }}'
-  twitter:card: summary_large_image
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#123456' }
@@ -1,10 +0,0 @@
-site_name: Social parity
-site_description: A small parity site.
-site_url: https://example.test/docs/
-site_dir: site
-theme:
-  name: material
-plugins:
-  - social:
-      cache: false
-      cards_layout: flat
@@ -1 +0,0 @@
-# Journal
@@ -1,5 +0,0 @@
---
-date: 2026-09-20
---
-
-# First post
@@ -1,5 +0,0 @@
---
-date: 2026-09-21
---
-
-# Second post
@@ -1 +0,0 @@
-# Home
@@ -1,6 +0,0 @@
-tags:
-  og:title: '{{ page.meta.get("title", page.title) }}'
-  og:image: '{{ image.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#123456' }
@@ -1,9 +0,0 @@
-site_name: Social blog
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - blog
-  - social:
-      cache: false
-      cards_layout: flat
@@ -1,7 +0,0 @@
---
-title: An accent card
-social:
-  cards_layout: default/accent
---
-
-# Accent
@@ -1,6 +0,0 @@
---
-title: A thoughtful beginning
-description: A concise introduction to the project.
---
-
-# Home
@@ -1,7 +0,0 @@
---
-title: An inverted card
-social:
-  cards_layout: default/invert
---
-
-# Invert
@@ -1,7 +0,0 @@
---
-title: A variant card
-social:
-  cards_layout: default/variant
---
-
-# Variant
@@ -1,19 +0,0 @@
-site_name: Bundled cards
-site_description: A site description for cards.
-site_url: https://example.test/docs/
-site_dir: site
-theme:
-  name: material
-  palette:
-    primary: deep purple
-  font:
-    text: Roboto
-plugins:
-  - social:
-      cache: false
-      cache_dir: social-cache
-      cards_layout: default
-      cards_layout_options:
-        background_color: '#4c1d95'
-        color: '#ffffff'
-        font_family: Roboto
@@ -1,3 +0,0 @@
-# Home
-
-Global card generation is disabled for this page.
@@ -1,8 +0,0 @@
---
-social:
-  cards: true
---
-
-# Page opt-in
-
-This page explicitly enables a card.
@@ -1,6 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-  x:mode: opt-in
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#234567' }
@@ -1,9 +0,0 @@
-site_name: Global cards off
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards: false
-      cards_layout: flat
@@ -1,6 +0,0 @@
---
-title: Custom typography
-description: A short description to inspect bottom alignment.
---
-
-# Home
@@ -1,6 +0,0 @@
---
-title: A very long headline that should wrap over several lines before the type becomes too small
-description: A longer description which should fit into two lines and reveal whether end alignment and line spacing match.
---
-
-# Long typography
@@ -1,24 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-  x:title: '{{ page.title }}'
-size: { width: 600, height: 315 }
-layers:
-  - background: { color: '#14263d' }
-  - size: { width: 500, height: 110 }
-    offset: { x: 50, y: 40 }
-    typography:
-      content: '{{ page.meta.get("title", page.title) }}'
-      align: center
-      overflow: shrink
-      color: '#ffffff'
-      line: { amount: 2, height: 1.25 }
-      font: { family: Roboto, style: Bold }
-  - size: { width: 500, height: 65 }
-    offset: { x: 50, y: 220 }
-    typography:
-      content: '{{ page.meta.get("description", "") }}'
-      align: end bottom
-      overflow: truncate
-      color: '#bdd4eb'
-      line: { amount: 2, height: 1.1 }
-      font: { family: Roboto, style: Regular }
@@ -1,9 +0,0 @@
-site_name: Custom typography
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cache_dir: social-cache
-      cards_layout: type
@@ -1 +0,0 @@
-# Home
@@ -1,5 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#324a62' }
@@ -1,13 +0,0 @@
-site_name: Debug without grid
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cache_dir: social-cache
-      cards_layout: flat
-      debug: true
-      debug_on_build: true
-      debug_grid: false
-      debug_color: blue
@@ -1 +0,0 @@
-# Debug view
@@ -1,5 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#123456' }
@@ -1,14 +0,0 @@
-site_name: Debug cards
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cache_dir: social-cache
-      cards_layout: flat
-      debug: true
-      debug_on_build: true
-      debug_grid: true
-      debug_grid_step: 32
-      debug_color: red
@@ -1 +0,0 @@
-# Home
@@ -1,5 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#102030' }
@@ -1,10 +0,0 @@
-site_name: Deprecated social options
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: flat
-      cards_color: { fill: '#102030', text: '#ffffff' }
-      cards_font: Roboto
@@ -1,3 +0,0 @@
-# Home
-
-The disabled plugin must not generate a card or social metadata.
@@ -1,8 +0,0 @@
---
-social:
-  cards: true
---
-
-# Page opt-in
-
-A page override must not re-enable a disabled plugin.
@@ -1,7 +0,0 @@
-site_name: Disabled social plugin
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      enabled: false
@@ -1 +0,0 @@
-# Include wins over exclude
@@ -1 +0,0 @@
-# Included guide
@@ -1,6 +0,0 @@
---
-social:
-  cards: false
---
-
-# Page opt-out
@@ -1 +0,0 @@
-# Home
@@ -1,5 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#abcdef' }
@@ -1,10 +0,0 @@
-site_name: Social filters
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: flat
-      cards_include: ['guides/**']
-      cards_exclude: ['guides/hidden.md']
@@ -1,3 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
-  <rect width="1200" height="630" fill="#345678"/>
-</svg>
@@ -1 +0,0 @@
-# Image card
@@ -1,10 +0,0 @@
-site_name: Social image only
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: default/only/image
-      cards_layout_options:
-        background_image: docs/background.svg
@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="400" height="200">
-  <rect width="400" height="200" fill="#1b334d"/>
-  <circle cx="200" cy="100" r="65" fill="#527da8"/>
-</svg>
@@ -1 +0,0 @@
-# Home
@@ -1,15 +0,0 @@
-definitions:
-  - &accent '#eeaa66'
-tags:
-  og:image: '{{ image.url }}'
-  x:layer: composed
-size: { width: 400, height: 200 }
-layers:
-  - background: { image: docs/background.svg }
-  - size: { width: 100, height: 40 }
-    offset: { x: 20, y: 20 }
-    background: { color: *accent }
-  - size: { width: 80, height: 80 }
-    offset: { x: 16, y: 16 }
-    origin: end bottom
-    icon: { value: material/star, color: '#ffffff' }
@@ -1,8 +0,0 @@
-site_name: Layer composition
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: composed
@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
-  <rect width="1200" height="630" fill="#2d4059"/>
-  <circle cx="1050" cy="400" r="180" fill="#4d6680"/>
-</svg>
@@ -1,8 +0,0 @@
---
-title: Home title
-description: Home description.
---
-
-# Home
-
-The global layout options supply the visible title and description.
@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
-  <rect width="100" height="100" rx="12" fill="#ffffff"/>
-  <circle cx="50" cy="50" r="32" fill="#2d4059"/>
-</svg>
@@ -1,15 +0,0 @@
---
-title: Page title
-description: Page description.
-social:
-  cards_layout_options:
-    background_image: null
-    color: '#ffe0a3'
-    logo: null
-    title: Page card title
-    description: Page card description
---
-
-# Override
-
-This page merges its layout options with the global settings.
@@ -1,23 +0,0 @@
-site_name: Layout options
-site_description: Default card description.
-site_url: https://example.test/docs/
-site_dir: site
-theme:
-  name: material
-  palette:
-    primary: teal
-  font:
-    text: Roboto
-plugins:
-  - social:
-      cache: false
-      cache_dir: social-cache
-      cards_layout: default
-      cards_layout_options:
-        background_color: '#2d4059'
-        background_image: docs/background.svg
-        color: '#ffffff'
-        font_family: Roboto
-        logo: docs/logo.svg
-        title: Global title
-        description: Global description
@@ -1,3 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="320" height="168">
-  <rect width="320" height="168" fill="red"/>
-</svg>
@@ -1,5 +0,0 @@
---
-title: Before title
---
-
-# Home
@@ -1,6 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-  x:title: '{{ page.meta.get("title", page.title) }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { image: docs/background.svg, color: transparent }
@@ -1,9 +0,0 @@
-site_name: Cached social lifecycle
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: true
-      cache_dir: social-cache
-      cards_layout: flat
@@ -1,20 +0,0 @@
-[
-  {
-    "path": "docs/background.svg",
-    "before": "fill=\"red\"",
-    "after": "fill=\"blue\"",
-    "changes": ["cards"]
-  },
-  {
-    "path": "docs/index.md",
-    "before": "Before title",
-    "after": "After title",
-    "changes": ["pages"]
-  },
-  {
-    "path": "layouts/flat.yml",
-    "before": "color: transparent",
-    "after": "color: '#73628a'",
-    "changes": ["cards"]
-  }
-]
@@ -1,6 +0,0 @@
---
-title: A bright idea
-description: A card with a logo icon.
---
-
-# Home
@@ -1,11 +0,0 @@
-site_name: Logo icon cards
-site_url: https://example.test/docs/
-site_dir: site
-theme:
-  name: material
-  icon:
-    logo: material/star
-plugins:
-  - social:
-      cache: false
-      cache_dir: social-cache
@@ -1,4 +0,0 @@
-social:
-  cards_layout_options:
-    background_color: '#445566'
-    label: inherited
@@ -1 +0,0 @@
-# Inherited options
@@ -1,8 +0,0 @@
---
-social:
-  cards_layout_options:
-    background_color: '#778899'
-    label: page
---
-
-# Page options
@@ -1 +0,0 @@
-# Global options
@@ -1,6 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-  x:label: '{{ layout.label }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '{{ layout.background_color }}' }
@@ -1,12 +0,0 @@
-site_name: Social metadata
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - meta
-  - social:
-      cache: false
-      cards_layout: flat
-      cards_layout_options:
-        background_color: '#112233'
-        label: global
@@ -1 +0,0 @@
-# Guide
@@ -1 +0,0 @@
-# Home
@@ -1,6 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-  x:instance: '{{ layout.label }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '{{ layout.color }}' }
@@ -1,17 +0,0 @@
-site_name: Social instances
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: flat
-      cards_dir: assets/cards/first
-      cards_include: ['index.md']
-      cards_layout_options: { label: first, color: '#102030' }
-  - social:
-      cache: false
-      cards_layout: flat
-      cards_dir: assets/cards/second
-      cards_include: ['guide.md']
-      cards_layout_options: { label: second, color: '#405060' }
@@ -1 +0,0 @@
-# Home
@@ -1,5 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#123456' }
@@ -1,7 +0,0 @@
-site_name: Social without URL
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: flat
@@ -1,6 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-  og:url: '{{ page.canonical_url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#486284' }
@@ -1 +0,0 @@
-# Guides
@@ -1 +0,0 @@
-# Home
@@ -1 +0,0 @@
-# Nested index
@@ -1,11 +0,0 @@
-site_name: Flat URL paths
-site_url: https://example.test/docs/
-site_dir: site
-use_directory_urls: false
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_dir: assets/cards
-      cards_layout_dir: card-layouts
-      cards_layout: flat
@@ -1 +0,0 @@
-# Home
@@ -1,5 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { image: docs/does-not-exist.svg }
@@ -1,10 +0,0 @@
-site_name: Recoverable social error
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: missing-image
-      log: true
-      log_level: ignore
@@ -1 +0,0 @@
-# Advanced
@@ -1 +0,0 @@
-# Home
@@ -1,7 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-  x:source: '{{ page.file.src_uri }}'
-  x:page: '{{ page.url }}'
-size: { width: 320, height: 168 }
-layers:
-  - background: { color: '#357192' }
@@ -1,8 +0,0 @@
-site_name: Social template context
-site_url: https://example.test/docs/
-site_dir: site
-theme: { name: material }
-plugins:
-  - social:
-      cache: false
-      cards_layout: context
@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
-  <circle cx="50" cy="50" r="48" fill="#1f2937"/>
-  <path d="M25 50h50M50 25v50" stroke="#ffffff" stroke-width="10"/>
-</svg>
@@ -1,7 +0,0 @@
---
-title: Italic
-social:
-  cards_layout: exact
---
-
-# Exact font face
@@ -1,6 +0,0 @@
---
-title: Theme colors
-description: Card colors and logo come from the theme.
---
-
-# Home
@@ -1,9 +0,0 @@
---
-title: PNG logo
-description: This page uses a raster logo through its layout options.
-social:
-  cards_layout_options:
-    logo: docs/assets/logo.png
---
-
-# PNG logo
@@ -1,9 +0,0 @@
---
-title: Heavier font variant
-description: This page selects the Black variant of Roboto.
-social:
-  cards_layout_options:
-    font_variant: Black
---
-
-# Variant
@@ -1,12 +0,0 @@
-tags:
-  og:image: '{{ image.url }}'
-size: { width: 1200, height: 630 }
-layers:
-  - background: { color: '#ffc107' }
-  - size: { width: 900, height: 150 }
-    offset: { x: 64, y: 180 }
-    typography:
-      content: '{{ page.title }}'
-      color: '#000000'
-      line: { amount: 1, height: 1.25 }
-      font: { family: Roboto, variant: Black, style: Italic }
@@ -1,21 +0,0 @@
-site_name: Theme defaults
-site_description: Theme-derived card settings.
-site_url: https://example.test/docs/
-site_dir: site
-theme:
-  name: material
-  logo: assets/logo.svg
-  palette:
-    - media: '(prefers-color-scheme: light)'
-      primary: amber
-      accent: deep orange
-    - media: '(prefers-color-scheme: dark)'
-      primary: indigo
-      accent: pink
-  font:
-    text: Roboto
-plugins:
-  - social:
-      cache: false
-      cache_dir: social-cache
-      cards_layout: default