Improve meta tags and page title

This PR adds all the appropriate meta tags to pages. This makes will
improve SEO and improve previews in services like Slack, which uses
both Twitter and Facebook/OpenGraph data for its unfurling.

.rubocop.yml

@@ -3,3 +3,7 @@ Layout/IndentHeredoc:
 
 Naming/HeredocDelimiterNaming:
   Enabled: false
+
+# We use nested methods in GovukTechDocs
+Lint/NestedMethodDefinition:
+  Enabled: false

CHANGELOG.md

@@ -20,6 +20,10 @@ the page source on GitHub, so readers can easily contribute back to the document
 
 https://github.com/alphagov/tech-docs-gem/blob/master/docs/configuration.md#show_contribution_banner
 
+### Better meta tags
+
+Pages now include better meta tags for search engines, Twitter, Facebook and Slack to pick up.
+
 ## 1.1.0
 
 You can now specify `google_site_verification` in tech-docs.yml. You can use

example/config/tech-docs.yml

@@ -1,5 +1,5 @@
 # Host to use for canonical URL generation (without trailing slash)
-host:
+host: https://docs.example.com
 
 # Header-related options
 show_govuk_logo: true

lib/govuk_tech_docs.rb

@@ -11,6 +11,7 @@
 require 'govuk_tech_docs/redirects'
 require 'govuk_tech_docs/table_of_contents/helpers'
 require 'govuk_tech_docs/contribution_banner'
+require 'govuk_tech_docs/meta_tags'
 require 'govuk_tech_docs/tech_docs_html_renderer'
 require 'govuk_tech_docs/unique_identifier_extension'
 require 'govuk_tech_docs/unique_identifier_generator'
@@ -48,6 +49,10 @@ def self.configure(context)
     context.helpers do
       include GovukTechDocs::TableOfContents::Helpers
       include GovukTechDocs::ContributionBanner
+
+      def meta_tags
+        @meta_tags ||= GovukTechDocs::MetaTags.new(config, current_page)
+      end
     end
 
     context.page '/*.xml', layout: false

lib/govuk_tech_docs/meta_tags.rb

@@ -0,0 +1,67 @@
+module GovukTechDocs
+  class MetaTags
+    def initialize(config, current_page)
+      @config = config
+      @current_page = current_page
+    end
+
+    def tags
+      all_tags = {
+        'description' => page_description,
+        'og:description' => page_description,
+        'og:image' => page_image,
+        'og:site_name' => site_name,
+        'og:title' => page_title,
+        'og:type' => 'object',
+        'og:url' => canonical_url,
+        'twitter:card' => 'summary',
+        'twitter:domain' => URI.parse(host).host,
+        'twitter:image' => page_image,
+        'twitter:title' => browser_title,
+        'twitter:url' => canonical_url,
+      }
+
+      Hash[all_tags.select { |_k, v| v }]
+    end
+
+    def browser_title
+      "#{page_title} | #{site_name}"
+    end
+
+    def canonical_url
+      "#{host}#{current_page.url}"
+    end
+
+  private
+
+    attr_reader :config, :current_page
+
+    def page_image
+      "#{host}/images/govuk-large.png"
+    end
+
+    def site_name
+      config[:tech_docs][:service_name]
+    end
+
+    def page_description
+      locals[:description] || frontmatter.description
+    end
+
+    def page_title
+      locals[:title] || frontmatter.title
+    end
+
+    def host
+      config[:tech_docs][:host]
+    end
+
+    def locals
+      current_page.metadata[:locals]
+    end
+
+    def frontmatter
+      current_page.data
+    end
+  end
+end

lib/source/layouts/core.erb

@@ -8,20 +8,23 @@
       <meta name="robots" content="noindex">
     <% end %>
 
-    <!-- Use title if it's in the page YAML frontmatter -->
-    <title><%= current_page.data.title || "GOV.UK Documentation" %></title>
+    <title><%= meta_tags.browser_title %></title>
 
     <!--[if gt IE 8]><!--><%= stylesheet_link_tag :screen, media: 'screen' %><!--<![endif]-->
     <!--[if lte IE 8]><%= stylesheet_link_tag 'screen-old-ie', media: 'screen' %><![endif]-->
 
-    <link rel="canonical" href="<%= config[:tech_docs][:host] %><%= current_page.url %>">
+    <link rel="canonical" href="<%= meta_tags.canonical_url %>">
 
     <% if config[:tech_docs][:google_site_verification] %>
       <meta name="google-site-verification" content="<%= config[:tech_docs][:google_site_verification] %>" />
     <% end %>
 
     <%= stylesheet_link_tag :print, media: 'print' %>
     <%= javascript_include_tag :application %>
+
+    <% meta_tags.tags.each do |property, content| %>
+      <%= tag :meta, property: property, content: content %>
+    <% end %>
   </head>
 
   <body>

spec/features/integration_spec.rb

@@ -12,6 +12,7 @@
     then_there_is_a_heading
     then_there_is_a_source_footer
 
+    and_there_are_proper_meta_tags
     and_redirects_are_working
     and_frontmatter_redirects_are_working
 
@@ -31,6 +32,11 @@ def then_there_is_a_heading
     expect(page).to have_css 'h1', text: 'Hello, World!'
   end
 
+  def and_there_are_proper_meta_tags
+    expect(page).to have_title 'GOV.UK Documentation Example | My First Service'
+    expect(page).to have_css 'meta[property="og:site_name"]', visible: false
+  end
+
   def then_there_is_a_source_footer
     %w[
       https://github.com/alphagov/example-repo/blob/master/source/index.html.md.erb

spec/govuk_tech_docs/meta_tags_spec.rb

@@ -0,0 +1,61 @@
+RSpec.describe GovukTechDocs::MetaTags do
+  describe '#tags' do
+    it 'returns all the extra meta tags' do
+      config = generate_config(
+        host: "https://www.example.org",
+        service_name: "Test Site",
+      )
+
+      current_page = double("current_page",
+        data: double("page_frontmatter", description: "The description.", title: "The Title"),
+        url: "/foo.html",
+        metadata: { locals: {} })
+
+      tags = GovukTechDocs::MetaTags.new(config, current_page).tags
+
+      expect(tags).to eql("description" => "The description.",
+        "og:description" => "The description.",
+        "og:image" => "https://www.example.org/images/govuk-large.png",
+        "og:site_name" => "Test Site",
+        "og:title" => "The Title",
+        "og:type" => "object",
+        "og:url" => "https://www.example.org/foo.html",
+        "twitter:card" => "summary",
+        "twitter:domain" => "www.example.org",
+        "twitter:image" => "https://www.example.org/images/govuk-large.png",
+        "twitter:title" => "The Title | Test Site",
+        "twitter:url" => "https://www.example.org/foo.html")
+    end
+
+    it 'uses the local variable as page description for proxied pages' do
+      current_page = double("current_page",
+        data: double("page_frontmatter", description: "The description.", title: "The Title"),
+        url: "/foo.html",
+        metadata: { locals: { description: "The local variable description." } })
+
+      tags = GovukTechDocs::MetaTags.new(generate_config, current_page).tags
+
+      expect(tags["description"]).to eql("The local variable description.")
+    end
+
+    it 'uses the local variable as page title for proxied pages' do
+      current_page = double("current_page",
+        data: double("page_frontmatter", description: "The description.", title: "The Title"),
+        url: "/foo.html",
+        metadata: { locals: { title: "The local variable title." } })
+
+      tags = GovukTechDocs::MetaTags.new(generate_config, current_page).tags
+
+      expect(tags["og:title"]).to eql("The local variable title.")
+    end
+
+    def generate_config(config = {})
+      {
+        tech_docs: {
+          host: "https://www.example.org",
+          service_name: "Test Site",
+        }.merge(config)
+      }
+    end
+  end
+end