Merge pull request #78 from jekyll/image-property-overload

Ability to support Facebook and Twitter specific images, set image height and width

README.md

@@ -81,9 +81,13 @@ The SEO tag will respect the following YAML front matter if included in a post,
 * `image` - Relative URL to an image associated with the post, page, or document (e.g., `/assets/page-pic.jpg`)
 * `author` - Page-, post-, or document-specific author information (see below)
 
+## Advanced usage
+
+Jekyll SEO Tag is designed to implement SEO best practices by default and to be the right fit for most sites right out of the box. If for some reason, you need more control over the output, read on:
+
 ### Disabling `<title>` output
 
-Jekyll SEO Tag is designed to implement SEO best practices by default. If for some reason, you don't want the plugin to output `<title>` tags on each page, simply invoke the plugin within your template like so:
+If for some reason, you don't want the plugin to output `<title>` tags on each page, simply invoke the plugin within your template like so:
 
 ```
 {% seo title=false %}
@@ -153,3 +157,23 @@ The following options can be set for any particular page. While the default opti
   * `name` - If the name of the thing that the page represents is different from the page title. (i.e.: "Frank's Café" vs "Welcome to Frank's Café")
   * `type` - The type of things that the page represents. This must be a [Schema.org type](http://schema.org/docs/schemas.html), and will probably usually be something like [`BlogPosting`](http://schema.org/BlogPosting), [`NewsArticle`](http://schema.org/NewsArticle), [`Person`](http://schema.org/Person), [`Organization`](http://schema.org/Organization), etc.
   * `links` - An array of other URLs that represent the same thing that this page represents. For instance, Jane's bio page might include links to Jane's GitHub and Twitter profiles.
+
+### Customizing image output
+
+For most users, setting `image: [path-to-image]` on a per-page basis should be enough. If you need more control over how images are represented, the `image` property can also be an object, with the following options:
+
+* `path` - The relative path to the image. Same as `image: [path-to-image]`
+* `twitter` - The relative path to a Twitter-specific image.
+* `facebook` - The relative path to a Facebook-specific image.
+* `height` - The height of the Facebook (`og:image`) image
+* `width` - The width of the Facebook (`og:image`) image
+
+You can use any of the above, optional properties, like so:
+
+```yml
+image:
+  twitter: /img/twitter.png
+  facebook: /img/facebook.png
+  height: 100
+  width: 100
+```

lib/template.html

@@ -89,7 +89,7 @@
 {% endif %}
 
 {% if page.image %}
-    {% assign seo_page_image = page.image | prepend: seo_url | escape %}
+    {% assign seo_page_image = page.image.path | default: page.image.facebook | default: page.image | prepend: seo_url | escape %}
 {% endif %}
 
 {% if seo_tag.title and seo_title %}
@@ -115,7 +115,17 @@
 {% endif %}
 
 {% if seo_page_image %}
-  <meta property="og:image" content="{{ seo_page_image }}" />
+<meta property="og:image" content="{{ seo_page_image }}" />
+  {% if page.image.height %}
+    <meta property="og:image:height" content="{{ page.image.height }}" />
+  {% endif %}
+  {% if page.image.width %}
+    <meta property="og:image:width" content="{{ page.image.width }}" />
+  {% endif %}
+{% endif %}
+
+{% if page.image.twitter %}
+  <meta name="twitter:image" content="{{ page.image.twitter | prepend: seo_url | escape }}" />
 {% endif %}
 
 {% if page.date %}
@@ -132,7 +142,7 @@
 {% endif %}
 
 {% if site.twitter %}
-  {% if seo_page_image %}
+  {% if seo_page_image or page.image.twitter %}
     <meta name="twitter:card" content="summary_large_image" />
   {% else %}
     <meta name="twitter:card" content="summary" />

spec/jekyll_seo_tag_spec.rb

@@ -110,7 +110,7 @@ describe Jekyll::SeoTag do
       end
     end
 
-    context 'with page.image' do
+    context 'with page.image as a string' do
       let(:page) { make_page('image' => '/img/foo.png') }
 
       it 'outputs the image' do
@@ -119,6 +119,47 @@ describe Jekyll::SeoTag do
       end
     end
 
+    context 'with page.image as an object' do
+      context 'when given a path' do
+        let(:page) { make_page('image' => { 'path' => '/img/foo.png' }) }
+
+        it 'outputs the image' do
+          expected = %r{<meta property="og:image" content="http://example.invalid/img/foo.png" />}
+          expect(output).to match(expected)
+        end
+      end
+
+      context 'when given a facebook image' do
+        let(:page) { make_page('image' => { 'facebook' => '/img/facebook.png' }) }
+
+        it 'outputs the image' do
+          expected = %r{<meta property="og:image" content="http://example.invalid/img/facebook.png" />}
+          expect(output).to match(expected)
+        end
+      end
+
+      context 'when given a twitter image' do
+        let(:page) { make_page('image' => { 'twitter' => '/img/twitter.png' }) }
+
+        it 'outputs the image' do
+          expected = %r{<meta name="twitter:image" content="http://example.invalid/img/twitter.png" />}
+          expect(output).to match(expected)
+        end
+      end
+
+      context 'when given the image height and width' do
+        let(:image) { { 'facebook' => '/img/foo.png', 'height' => 1, 'width' => 2 } }
+        let(:page) { make_page('image' => image) }
+
+        it 'outputs the image' do
+          expected = %r{<meta property="og:image:height" content="1" />}
+          expect(output).to match(expected)
+          expected = %r{<meta property="og:image:width" content="2" />}
+          expect(output).to match(expected)
+        end
+      end
+    end
+
     context 'with site.logo' do
       let(:site) { make_site('logo' => '/logo.png', 'url' => 'http://example.invalid') }