Add LinkCollection#structured_data (#26)

Fixes #25

README.md

@@ -219,6 +219,23 @@ You can use the `breadcrumbs` method directly as an array. It will return an arr
 <% end %>
 ```
 
+If you use this approach, you lose the built-in semantic breadcrumb functionality. One way to
+add them back is to use JSON-LD structured data:
+
+```erb
+<script type="application/ld+json">
+  <%= breadcrumbs.structured_data(url_base: "https://example.com")) %>
+</script>
+```
+
+Or, you can infer `url_base` from `request`:
+
+```erb
+<script type="application/ld+json">
+  <%= breadcrumbs.structured_data(url_base: "#{request.protocol}#{request.host_with_port}")) %>
+</script>
+```
+
 ## Getting the parent breadcrumb
 
 If you want to add a link to the parent breadcrumb, you can use the `parent_breadcrumb` view helper.

lib/gretel/renderer.rb

@@ -159,6 +159,27 @@ def initialize(context, links, options = {})
         concat links
       end
 
+      # Returns a hash matching the JSON-LD Structured Data schema
+      # https://developers.google.com/search/docs/data-types/breadcrumb#json-ld
+      def structured_data(url_base:)
+        url_base = url_base.chomp("/") # Remove trailing `/`, if present
+
+        items = @links.each_with_index.map do |link, i|
+          {
+            "@type": "ListItem",
+            "position": i + 1,
+            "name": link.text,
+            "item": "#{url_base}#{link.url}"
+          }
+        end
+
+        {
+          "@context": "https://schema.org",
+          "@type": "BreadcrumbList",
+          "itemListElement": items
+        }
+      end
+
       # Helper for returning all link keys to allow for simple testing.
       def keys
         map(&:key)
@@ -192,7 +213,7 @@ def render
         end
 
         html = html_fragments.join(" ").html_safe
-        
+
         if options[:semantic]
           content_tag(options[:container_tag], html, id: options[:id], class: options[:class], itemscope: "", itemtype: "https://schema.org/BreadcrumbList")
         else

spec/lib/gretel/view_helpers_spec.rb

@@ -489,6 +489,42 @@
     end
   end
 
+  describe 'Structured data' do
+    # https://developers.google.com/search/docs/data-types/breadcrumb#year-genre%20example
+    it "returns an object with the correct structure" do
+      breadcrumb :with_parent
+
+      expected_result = {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        "itemListElement": [
+          {
+            "@type": "ListItem",
+            "position": 1,
+            "name": "Home",
+            "item": "https://example.com/"
+          },
+           {
+            "@type": "ListItem",
+            "position": 2,
+            "name": "About",
+            "item": "https://example.com/about"
+          },
+           {
+            "@type": "ListItem",
+            "position": 3,
+            "name": "Contact",
+            "item": "https://example.com/about/contact"
+          }
+        ]
+      }
+
+      expect(breadcrumbs.structured_data(url_base: "https://example.com")).to eq(expected_result)
+      # Ensure there's no extra trailing slashes
+      expect(breadcrumbs.structured_data(url_base: "https://example.com/")).to eq(expected_result)
+    end
+  end
+
   private
 
   def setup_loading_from_tmp_folder