feat: add social plugin (#172)

Author: mschoettle

Dockerfile

@@ -3,7 +3,7 @@ FROM ghcr.io/astral-sh/uv:0.9.18-python3.13-alpine AS dependencies
 
 COPY --from=ghcr.io/astral-sh/uv:0.9.18 /uv /uvx /bin/
 
-RUN apk add --no-cache git pngquant
+RUN apk add --no-cache git pngquant cairo
 
 WORKDIR /app
 

layouts/custom.yml

@@ -0,0 +1,133 @@
+# Docs: https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#customization
+# Partially inspired by: https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/social/templates/default/variant.yml
+
+definitions:
+  # Background color
+  - &background_color >-
+    {{ layout.background_color }}
+
+  # Text color
+  - &color >-
+    white
+
+  # Font family (default: Roboto)
+  - &font_family >-
+    {%- if layout.font_family -%}
+      {{ layout.font_family }}
+    {%- elif config.theme.font is mapping -%}
+      {{ config.theme.font.get("text", "Roboto") }}
+    {%- else -%}
+      Roboto
+    {%- endif -%}
+
+  # Font variant
+  - &font_variant >-
+    {%- if layout.font_variant -%}
+      {{ layout.font_variant }}
+    {%- endif -%}
+
+  # Site description
+  - &site_name >-
+    {{ config.site_name }}
+
+  # Page title
+  - &page_title >-
+    {{ page.meta.get("title", page.title) }}
+
+  # Page title with site name
+  - &page_title_with_site_name >-
+    {%- if not page.is_homepage -%}
+      {{ page.meta.get("title", page.title) }} - {{ config.site_name }}
+    {%- else -%}
+      {{ config.site_name }}
+    {%- endif -%}
+
+  - &page_description >-
+    {%- if layout.description -%}
+      {{ layout.description }}
+    {%- else -%}
+      {{ page.meta.get("description", config.site_description) | x }}
+    {%- endif -%}
+
+
+# Meta tags
+tags:
+
+  # Open Graph
+  og:type: website
+  og:title: *page_title_with_site_name
+  og:description: *page_description
+  og:image: "{{ image.url }}"
+  og:image:type: "{{ image.type }}"
+  og:image:width: "{{ image.width }}"
+  og:image:height: "{{ image.height }}"
+  og:url: "{{ page.canonical_url }}"
+
+  # Twitter
+  twitter:card: summary_large_image
+  twitter:title: *page_title_with_site_name
+  twitter:description: *page_description
+  twitter:image: "{{ image.url }}"
+
+
+size: { width: 1200, height: 630 }
+layers:
+  # Background color
+  - background:
+      color: *background_color
+  # Circles for fancier background
+  - size: { width: 2400, height: 2400 }
+    offset: { x: -1024, y: 64 }
+    icon:
+      value: material/circle
+      color: "#5c6bc0"
+  - size: { width: 1800, height: 1800 }
+    offset: { x: 512, y: -1024 }
+    icon:
+      value: material/circle
+      color: "#3949ab"
+  # Logo
+  - size: { width: 64, height: 64 }
+    offset: { x: 64, y: 64 }
+    icon:
+      value: fontawesome/solid/code
+      color: white
+  # Site name
+  - size: { width: 768, height: 42 }
+    offset: { x: 160, y: 74 }
+    typography:
+      content: *site_name
+      color: *color
+      font:
+        family: *font_family
+        variant: *font_variant
+        style: Bold
+  # Page title
+  - size: { width: 885, height: 256 }
+    offset: { x: 62, y: 192 }
+    typography:
+      content: *page_title
+      overflow: shrink
+      align: start
+      color: *color
+      line:
+        amount: 3
+        height: 1.25
+      font:
+        family: *font_family
+        variant: *font_variant
+        style: Bold
+  # Page description
+  - size: { width: 885, height: 64 }
+    offset: { x: 64, y: 512 }
+    typography:
+      content: *page_description
+      align: start
+      color: *color
+      line:
+        amount: 2
+        height: 1.5
+      font:
+        family: *font_family
+        variant: *font_variant
+        style: Regular

mkdocs.yml

@@ -129,6 +129,11 @@ plugins:
       tags_hierarchy: true
       shadow_tags:
         - archived
+  - social:
+      enabled: !ENV [CI, false]
+      cards_layout: custom
+      cards_layout_options:
+        background_color: "#4051b5"
   # optimize images
   # https://squidfunk.github.io/mkdocs-material/plugins/optimize/
   - optimize: