Refactor seo.html and support OpenGraph image overrides (#1321)

- Refactor seo.html include and add `page.header.og_image` override
- DRY up handling of page images (`page.header.image`, `page.header.overlay_image`, `page.header.teaser`, and `site.og_image`).
- Allow page images to be set with `header.og_image` page variable in YAML Front Matter as per feature request in #1316.
- Add sample posts for testing `og_image` override
- Set author bio as site OpenGraph default image
- Document `page.header.og_image` OpenGraph override
- Update CHANGELOG and history

Close #1316

CHANGELOG.md

@@ -12,6 +12,8 @@
 - Add support for Staticman v2 endpoint and reCAPTCHA.
 - Add Polish localized UI text strings. [#1304](https://github.com/mmistakes/minimal-mistakes/pull/1304)
 - Add toggleable table of contents via YAML Front Matter. Note: `toc` helper include will be deprecated in next major version. [#1222](https://github.com/mmistakes/minimal-mistakes/issues/1222)
+- Refactor seo.html include to DRY-up page image handling.
+- Add support for setting what image is used by OpenGraph and Twitter via `page.header.og_image`. [#1316](https://github.com/mmistakes/minimal-mistakes/issues/1316)
 
 ### Bug Fixes
 

_includes/seo.html

@@ -54,21 +54,37 @@
   <meta property="og:description" content="{{ seo_description }}">
 {% endif %}
 
+{% assign page_large_image = page.header.og_image | default: page.header.overlay_image | default: page.header.image %}
+{% unless page_large_image contains '://' %}
+  {% assign page_large_image = page_large_image | absolute_url %}
+{% endunless %}
+{% assign page_large_image = page_large_image | escape %}
+
+{% assign page_teaser_image = page.header.teaser | default: site.og_image %}
+{% unless page_teaser_image contains '://' %}
+  {% assign page_teaser_image = page_teaser_image | absolute_url %}
+{% endunless %}
+{% assign page_teaser_image = page_teaser_image | escape %}
+
+{% assign site_og_image = site.og_image %}
+{% unless site_og_image contains '://' %}
+  {% assign site_og_image = site_og_image | absolute_url %}
+{% endunless %}
+{% assign site_og_image = site_og_image | escape %}
+
 {% if site.twitter.username %}
   <meta name="twitter:site" content="@{{ site.twitter.username | replace: "@", "" }}">
   <meta name="twitter:title" content="{{ page.title | default: site.title | markdownify | strip_html | strip_newlines | escape_once }}">
   <meta name="twitter:description" content="{{ seo_description }}">
   <meta name="twitter:url" content="{{ canonical_url }}">
 
-  {% if page.header.image %}
+  {% if page_large_image %}
     <meta name="twitter:card" content="summary_large_image">
-    <meta name="twitter:image" content="{% if page.header.image contains "://" %}{{ page.header.image }}{% else %}{{ page.header.image | absolute_url }}{% endif %}">
+    <meta name="twitter:image" content="{{ page_large_image }}">
   {% else %}
     <meta name="twitter:card" content="summary">
-    {% if page.header.teaser %}
+    {% if page_teaser_image %}
-      <meta name="twitter:image" content="{% if page.header.teaser contains "://" %}{{ page.header.teaser }}{% else %}{{ page.header.teaser | absolute_url }}{% endif %}">
+      <meta name="twitter:image" content="{{ page_teaser_image }}">
-    {% elsif site.og_image %}
-      <meta name="twitter:image" content="{{ site.og_image | absolute_url }}">
     {% endif %}
   {% endif %}
 
@@ -87,14 +103,10 @@
   {% endif %}
 {% endif %}
 
-{% if page.header.image %}
+{% if page_large_image %}
-  <meta property="og:image" content="{% if page.header.image contains "://" %}{{ page.header.image }}{% else %}{{ page.header.image | absolute_url }}{% endif %}">
+  <meta property="og:image" content="{{ page_large_image }}">
-{% elsif page.header.overlay_image %}
+{% elsif page_teaser_image %}
-  <meta property="og:image" content="{% if page.header.overlay_image contains "://" %}{{ page.header.overlay_image }}{% else %}{{ page.header.overlay_image | absolute_url }}{% endif %}">
+  <meta property="og:image" content="{{ page_teaser_image }}">
-{% elsif page.header.teaser %}
-  <meta property="og:image" content="{% if page.header.teaser contains "://" %}{{ page.header.teaser }}{% else %}{{ page.header.teaser | absolute_url }}{% endif %}">
-{% elsif site.og_image %}
-  <meta property="og:image" content="{% if site.og_image contains "://" %}{{ site.og_image }}{% else %}{{ site.og_image | absolute_url }}{% endif %}">
 {% endif %}
 
 {% if page.date %}
@@ -115,7 +127,7 @@
       "@context": "http://schema.org",
       "@type": "Organization",
       "url": {{ seo_url | jsonify }},
-      "logo": {{ site.og_image | absolute_url | jsonify }}
+      "logo": {{ site_og_image | jsonify }}
     }
   </script>
 {% endif %}

docs/_docs/10-layouts.md

@@ -7,7 +7,7 @@ single_layout_gallery:
     alt: "single layout with header example"
   - image_path: /assets/images/mm-layout-single-meta.png
     alt: "single layout with comments and related posts"
-last_modified_at: 2017-10-20T14:26:10-04:00
+last_modified_at: 2017-10-26T15:42:42-04:00
 toc: true
 toc_label: "Included Layouts"
 toc_icon: "columns"
@@ -380,6 +380,19 @@ header:
   cta_url: "https://unsplash.com"
 ```
 
+### OpenGraph & Twitter Card Images
+
+By default the large page header or overlay images are used for sharing previews. If you'd like to set this image to something else use `page.header.og_image` like:
+
+```yaml
+header:
+  image: /assets/images/your-page-image.jpg
+  og_image: /assets/images/your-og-image.jpg
+```
+
+**ProTip:** `og_image` is useful for setting OpenGraph images on pages that don't have a header or overlay image.
+{: .notice--info}
+
 ---
 
 ## Sidebars

docs/_docs/18-history.md

@@ -4,7 +4,7 @@ permalink: /docs/history/
 excerpt: "Change log of enhancements and bug fixes made to the theme."
 sidebar:
   nav: docs
-last_modified_at: 2017-10-20T15:56:30-04:00
+last_modified_at: 2017-10-26T15:33:41-04:00
 toc: true
 ---
 
@@ -22,6 +22,8 @@ toc: true
 - Add support for Staticman v2 endpoint and reCAPTCHA.
 - Add Polish localized UI text strings. [#1304](https://github.com/mmistakes/minimal-mistakes/pull/1304)
 - Add toggleable table of contents via YAML Front Matter. Note: `toc` helper include will be deprecated in next major version. [#1222](https://github.com/mmistakes/minimal-mistakes/issues/1222)
+- Refactor seo.html include to DRY-up page image handling.
+- Add support for setting what image is used by OpenGraph and Twitter via `page.header.og_image`. [#1316](https://github.com/mmistakes/minimal-mistakes/issues/1316)
 
 ### Bug Fixes
 

docs/_includes/seo.html

@@ -1,42 +1,42 @@
 <!-- begin SEO -->
 {% if site.url %}
-{% assign seo_url = site.url | append: site.baseurl %}
+  {% assign seo_url = site.url | append: site.baseurl %}
 {% endif %}
 {% assign seo_url = seo_url | default: site.github.url %}
 
 {% if page.title %}
-{% assign seo_title = page.title | append: " " | append: site.title_separator | append: " " | append: site.title %}
+  {% assign seo_title = page.title | append: " " | append: site.title_separator | append: " " | append: site.title %}
 {% endif %}
 
 {% if seo_title %}
-{% assign seo_title = seo_title | markdownify | strip_html | strip_newlines | escape_once %}
+  {% assign seo_title = seo_title | markdownify | strip_html | strip_newlines | escape_once %}
 {% endif %}
 
 {% if site.url %}
-{% assign canonical_url = page.url | replace: "index.html", "" | prepend: site.url %}
+  {% assign canonical_url = page.url | replace: "index.html", "" | prepend: site.url %}
 {% endif %}
 
 <title>{{ seo_title | default: site.title }}{% if paginator %}{% unless paginator.page == 1 %} {{ site.title_separator }} {{ site.data.ui-text[site.locale].page | default: "Page" }} {{ paginator.page }}{% endunless %}{% endif %}</title>
 
 {% assign seo_description = page.description | default: page.excerpt | default: site.description %}
 {% if seo_description %}
-{% assign seo_description = seo_description | markdownify | strip_html | strip_newlines | escape_once %}
+  {% assign seo_description = seo_description | markdownify | strip_html | strip_newlines | escape_once %}
 {% endif %}
 
 <meta name="description" content="{{ seo_description }}">
 
 {% assign seo_author = page.author | default: page.author[0] | default: site.author.name %}
 {% if seo_author %}
-{% if seo_author.twitter %}
+  {% if seo_author.twitter %}
-  {% assign seo_author_twitter = seo_author.twitter %}
+    {% assign seo_author_twitter = seo_author.twitter %}
-{% else %}
-  {% if site.data.authors and site.data.authors[seo_author] %}
-    {% assign seo_author_twitter = site.data.authors[seo_author].twitter  %}
   {% else %}
-    {% assign seo_author_twitter = seo_author  %}
+    {% if site.data.authors and site.data.authors[seo_author] %}
+      {% assign seo_author_twitter = site.data.authors[seo_author].twitter  %}
+    {% else %}
+      {% assign seo_author_twitter = seo_author  %}
+    {% endif %}
   {% endif %}
-{% endif %}
+  {% assign seo_author_twitter = seo_author_twitter | replace: "@", "" %}
-{% assign seo_author_twitter = seo_author_twitter | replace: "@", "" %}
 {% endif %}
 
 <meta name="author" content="{{ seo_author }}">
@@ -46,105 +46,117 @@
 <meta property="og:title" content="{{ page.title | default: site.title | markdownify | strip_html | strip_newlines | escape_once }}">
 
 {% if seo_url %}
-<link rel="canonical" href="{{ page.url | prepend: seo_url | replace: "/index.html", "/" }}">
+  <link rel="canonical" href="{{ page.url | prepend: seo_url | replace: "/index.html", "/" }}">
-<meta property="og:url" content="{{ page.url | prepend: seo_url | replace: "/index.html", "/" }}">
+  <meta property="og:url" content="{{ page.url | prepend: seo_url | replace: "/index.html", "/" }}">
 {% endif %}
 
 {% if page.excerpt %}
-<meta property="og:description" content="{{ seo_description }}">
+  <meta property="og:description" content="{{ seo_description }}">
 {% endif %}
 
-{% if site.twitter.username %}
+{% assign page_large_image = page.header.og_image | default: page.header.overlay_image | default: page.header.image %}
-<meta name="twitter:site" content="@{{ site.twitter.username | replace: "@", "" }}">
+{% unless page_large_image contains '://' %}
-<meta name="twitter:title" content="{{ page.title | default: site.title | markdownify | strip_html | strip_newlines | escape_once }}">
+  {% assign page_large_image = page_large_image | absolute_url %}
-<meta name="twitter:description" content="{{ seo_description }}">
+{% endunless %}
-<meta name="twitter:url" content="{{ canonical_url }}">
+{% assign page_large_image = page_large_image | escape %}
 
-{% if page.header.image %}
+{% assign page_teaser_image = page.header.teaser | default: site.og_image %}
-  <meta name="twitter:card" content="summary_large_image">
+{% unless page_teaser_image contains '://' %}
-  <meta name="twitter:image" content="{% if page.header.image contains "://" %}{{ page.header.image }}{% else %}{{ page.header.image | absolute_url }}{% endif %}">
+  {% assign page_teaser_image = page_teaser_image | absolute_url %}
-{% else %}
+{% endunless %}
-  <meta name="twitter:card" content="summary">
+{% assign page_teaser_image = page_teaser_image | escape %}
-  {% if page.header.teaser %}
+
-    <meta name="twitter:image" content="{% if page.header.teaser contains "://" %}{{ page.header.teaser }}{% else %}{{ page.header.teaser | absolute_url }}{% endif %}">
+{% assign site_og_image = site.og_image %}
-  {% elsif site.og_image %}
+{% unless site_og_image contains '://' %}
-    <meta name="twitter:image" content="{{ site.og_image | absolute_url }}">
+  {% assign site_og_image = site_og_image | absolute_url %}
+{% endunless %}
+{% assign site_og_image = site_og_image | escape %}
+
+{% if site.twitter.username %}
+  <meta name="twitter:site" content="@{{ site.twitter.username | replace: "@", "" }}">
+  <meta name="twitter:title" content="{{ page.title | default: site.title | markdownify | strip_html | strip_newlines | escape_once }}">
+  <meta name="twitter:description" content="{{ seo_description }}">
+  <meta name="twitter:url" content="{{ canonical_url }}">
+
+  {% if page_large_image %}
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:image" content="{{ page_large_image }}">
+  {% else %}
+    <meta name="twitter:card" content="summary">
+    {% if page_teaser_image %}
+      <meta name="twitter:image" content="{{ page_teaser_image }}">
+    {% endif %}
+  {% endif %}
+
+  {% if seo_author_twitter %}
+    <meta name="twitter:creator" content="@{{ seo_author_twitter }}">
   {% endif %}
 {% endif %}
 
-{% if seo_author_twitter %}
-  <meta name="twitter:creator" content="@{{ seo_author_twitter }}">
-{% endif %}
-{% endif %}
-
 {% if site.facebook %}
-{% if site.facebook.publisher %}
+  {% if site.facebook.publisher %}
-  <meta property="article:publisher" content="{{ site.facebook.publisher }}">
+    <meta property="article:publisher" content="{{ site.facebook.publisher }}">
+  {% endif %}
+
+  {% if site.facebook.app_id %}
+    <meta property="fb:app_id" content="{{ site.facebook.app_id }}">
+  {% endif %}
 {% endif %}
 
-{% if site.facebook.app_id %}
+{% if page_large_image %}
-  <meta property="fb:app_id" content="{{ site.facebook.app_id }}">
+  <meta property="og:image" content="{{ page_large_image }}">
-{% endif %}
+{% elsif page_teaser_image %}
-{% endif %}
+  <meta property="og:image" content="{{ page_teaser_image }}">
-
-{% if page.header.image %}
-<meta property="og:image" content="{% if page.header.image contains "://" %}{{ page.header.image }}{% else %}{{ page.header.image | absolute_url }}{% endif %}">
-{% elsif page.header.overlay_image %}
-<meta property="og:image" content="{% if page.header.overlay_image contains "://" %}{{ page.header.overlay_image }}{% else %}{{ page.header.overlay_image | absolute_url }}{% endif %}">
-{% elsif page.header.teaser %}
-<meta property="og:image" content="{% if page.header.teaser contains "://" %}{{ page.header.teaser }}{% else %}{{ page.header.teaser | absolute_url }}{% endif %}">
-{% elsif site.og_image %}
-<meta property="og:image" content="{% if site.og_image contains "://" %}{{ site.og_image }}{% else %}{{ site.og_image | absolute_url }}{% endif %}">
 {% endif %}
 
 {% if page.date %}
-<meta property="og:type" content="article">
+  <meta property="og:type" content="article">
-<meta property="article:published_time" content="{{ page.date | date_to_xmlschema }}">
+  <meta property="article:published_time" content="{{ page.date | date_to_xmlschema }}">
 {% endif %}
 
 {% if paginator.previous_page %}
-<link rel="prev" href="{{ paginator.previous_page_path | prepend: seo_url }}">
+  <link rel="prev" href="{{ paginator.previous_page_path | prepend: seo_url }}">
 {% endif %}
 {% if paginator.next_page %}
-<link rel="next" href="{{ paginator.next_page_path | prepend: seo_url }}">
+  <link rel="next" href="{{ paginator.next_page_path | prepend: seo_url }}">
 {% endif %}
 
 {% if site.og_image %}
-<script type="application/ld+json">
+  <script type="application/ld+json">
-  {
+    {
-    "@context": "http://schema.org",
+      "@context": "http://schema.org",
-    "@type": "Organization",
+      "@type": "Organization",
-    "url": {{ seo_url | jsonify }},
+      "url": {{ seo_url | jsonify }},
-    "logo": {{ site.og_image | absolute_url | jsonify }}
+      "logo": {{ site_og_image | jsonify }}
-  }
+    }
-</script>
+  </script>
 {% endif %}
 
 {% if site.social %}
-<script type="application/ld+json">
+  <script type="application/ld+json">
-  {
+    {
-    "@context" : "http://schema.org",
+      "@context" : "http://schema.org",
-    "@type" : "{% if site.social.type %}{{ site.social.type }}{% else %}Person{% endif %}",
+      "@type" : "{% if site.social.type %}{{ site.social.type }}{% else %}Person{% endif %}",
-    "name" : "{{ site.social.name | default: site.name }}",
+      "name" : "{{ site.social.name | default: site.name }}",
-    "url" : {{ seo_url | jsonify }},
+      "url" : {{ seo_url | jsonify }},
-    "sameAs" : {{ site.social.links | jsonify }}
+      "sameAs" : {{ site.social.links | jsonify }}
-  }
+    }
-</script>
+  </script>
 {% endif %}
 
 {% if site.google_site_verification %}
-<meta name="google-site-verification" content="{{ site.google_site_verification }}" />
+  <meta name="google-site-verification" content="{{ site.google_site_verification }}" />
 {% endif %}
 {% if site.bing_site_verification %}
-<meta name="msvalidate.01" content="{{ site.bing_site_verification }}">
+  <meta name="msvalidate.01" content="{{ site.bing_site_verification }}">
 {% endif %}
 {% if site.alexa_site_verification %}
-<meta name="alexaVerifyID" content="{{ site.alexa_site_verification }}">
+  <meta name="alexaVerifyID" content="{{ site.alexa_site_verification }}">
 {% endif %}
 {% if site.yandex_site_verification %}
-<meta name="yandex-verification" content="{{ site.yandex_site_verification }}">
+  <meta name="yandex-verification" content="{{ site.yandex_site_verification }}">
 {% endif %}
 {% if site.naver-site-verification %}
-<meta name="naver-site-verification" content="{{ site.naver-site-verification }}">
+  <meta name="naver-site-verification" content="{{ site.naver-site-verification }}">
 {% endif %}
 <!-- end SEO -->

docs/_posts/2010-08-05-post-header-image-og-override.md

@@ -0,0 +1,22 @@
+---
+title: "Post: Header Image with OpenGraph Override"
+header:
+  image: /assets/images/page-header-image.png
+  og_image: /assets/images/page-header-og-image.png
+categories:
+  - Layout
+  - Uncategorized
+tags:
+  - edge case
+  - image
+  - layout
+last_modified_at: 2017-10-26T15:12:19-04:00
+---
+
+This post has a header image with an OpenGraph override.
+
+```yaml
+header:
+  image: /assets/images/page-header-image.png
+  og_image: /assets/images/page-header-og-image.png
+```

docs/_posts/2010-08-05-post-header-overlay-image-og-override.md

@@ -0,0 +1,26 @@
+---
+title: "Post: Overlay Image with OpenGraph Override"
+header:
+  overlay_image: /assets/images/unsplash-image-1.jpg
+  og_image: /assets/images/page-header-og-image.png
+  caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
+  cta_url: "https://unsplash.com"
+categories:
+  - Layout
+  - Uncategorized
+tags:
+  - edge case
+  - image
+  - layout
+last_modified_at: 2017-10-26T15:12:19-04:00
+---
+
+This post has a header image with an OpenGraph override.
+
+```yaml
+header:
+  overlay_image: /assets/images/unsplash-image-1.jpg
+  og_image: /assets/images/page-header-og-image.png
+  caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
+  cta_url: "https://unsplash.com"
+```

docs/_posts/2010-08-05-post-teaser-image-og-override.md

@@ -0,0 +1,22 @@
+---
+title: "Post: Teaser Image with OpenGraph Override"
+header:
+  teaser: /assets/images/page-header-teaser.png
+  og_image: /assets/images/page-header-og-image.png
+categories:
+  - Layout
+  - Uncategorized
+tags:
+  - edge case
+  - image
+  - layout
+last_modified_at: 2017-10-26T15:12:19-04:00
+---
+
+This post has a teaser image with an OpenGraph override.
+
+```yaml
+header:
+  teaser: /assets/images/page-header-teaser.png
+  og_image: /assets/images/page-header-og-image.png
+```

test/_config.yml

@@ -63,7 +63,7 @@ facebook:
   username               :
   app_id                 :
   publisher              :
-og_image                 : # Open Graph/Twitter default site image
+og_image                 : "/assets/images/bio-photo.jpg"
 # For specifying social profiles
 # - https://developers.google.com/structured-data/customize/social-profiles
 social:

test/_posts/2010-08-05-post-header-image-og-override.md

@@ -0,0 +1,22 @@
+---
+title: "Post: Header Image with OpenGraph Override"
+header:
+  image: /assets/images/page-header-image.png
+  og_image: /assets/images/page-header-og-image.png
+categories:
+  - Layout
+  - Uncategorized
+tags:
+  - edge case
+  - image
+  - layout
+last_modified_at: 2017-10-26T15:12:19-04:00
+---
+
+This post has a header image with an OpenGraph override.
+
+```yaml
+header:
+  image: /assets/images/page-header-image.png
+  og_image: /assets/images/page-header-og-image.png
+```

test/_posts/2010-08-05-post-header-overlay-image-og-override.md

@@ -0,0 +1,26 @@
+---
+title: "Post: Overlay Image with OpenGraph Override"
+header:
+  overlay_image: /assets/images/unsplash-image-1.jpg
+  og_image: /assets/images/page-header-og-image.png
+  caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
+  cta_url: "https://unsplash.com"
+categories:
+  - Layout
+  - Uncategorized
+tags:
+  - edge case
+  - image
+  - layout
+last_modified_at: 2017-10-26T15:12:19-04:00
+---
+
+This post has a header image with an OpenGraph override.
+
+```yaml
+header:
+  overlay_image: /assets/images/unsplash-image-1.jpg
+  og_image: /assets/images/page-header-og-image.png
+  caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
+  cta_url: "https://unsplash.com"
+```

test/_posts/2010-08-05-post-teaser-image-og-override.md

@@ -0,0 +1,22 @@
+---
+title: "Post: Teaser Image with OpenGraph Override"
+header:
+  teaser: /assets/images/page-header-teaser.png
+  og_image: /assets/images/page-header-og-image.png
+categories:
+  - Layout
+  - Uncategorized
+tags:
+  - edge case
+  - image
+  - layout
+last_modified_at: 2017-10-26T15:12:19-04:00
+---
+
+This post has a teaser image with an OpenGraph override.
+
+```yaml
+header:
+  teaser: /assets/images/page-header-teaser.png
+  og_image: /assets/images/page-header-og-image.png
+```