NEW Add ability to handle canonical URLs

code/controllers/DocumentationViewer.php

@@ -568,6 +568,19 @@ class DocumentationViewer extends Controller implements PermissionProvider
         return $link;
     }
 
+    /**
+     * Return the canonical URL from the page
+     *
+     * @return string
+     */
+    public function getCanonicalUrl()
+    {
+        if (!$this->getPage()) {
+            return '';
+        }
+        return $this->getPage()->getCanonicalUrl();
+    }
+
     /**
      * Generate a list of all the pages in the documentation grouped by the
      * first letter of the page.

code/models/DocumentationPage.php

@@ -38,6 +38,11 @@ class DocumentationPage extends ViewableData
 
     protected $read = false;
 
+     /**
+     * @var string
+     */
+    protected $canonicalUrl;
+
     /**
      * @param DocumentationEntity $entity
      * @param string              $filename
@@ -260,10 +265,25 @@ class DocumentationPage extends ViewableData
             Controller::join_links(
                 $this->entity->Link($short),
                 $this->getRelativeLink()
-            ), '/'
+            ),
+            '/'
         );
     }
 
+    /**
+     * Determine and set the canonical URL for the given record, for example: dev/docs/en/Path/To/Document
+     */
+    public function populateCanonicalUrl()
+    {
+        $url = Director::absoluteURL(Controller::join_links(
+            Config::inst()->get('DocumentationViewer', 'link_base'),
+            $this->getEntity()->getLanguage(),
+            $this->getRelativeLink()
+        ));
+
+        $this->setCanonicalUrl($url);
+    }
+
     /**
      * Return metadata from the first html block in the page, then remove the
      * block on request
@@ -349,5 +369,30 @@ class DocumentationPage extends ViewableData
     {
         return sprintf(get_class($this) .': %s)', $this->getPath());
     }
+
+    /**
+     * Set the canonical URL to use for this page
+     *
+     * @param string $canonicalUrl
+     * @return $this
+     */
+    public function setCanonicalUrl($canonicalUrl)
+    {
+        $this->canonicalUrl = $canonicalUrl;
+        return $this;
     }
 
+    /**
+     * Get the canonical URL to use for this page. Will trigger discovery
+     * via {@link DocumentationPage::populateCanonicalUrl()} if none is already set.
+     *
+     * @return string
+     */
+    public function getCanonicalUrl()
+    {
+        if (!$this->canonicalUrl) {
+            $this->populateCanonicalUrl();
+        }
+        return $this->canonicalUrl;
+    }
+}

templates/Includes/DocumentationHead.ss

@@ -2,6 +2,9 @@
 	<% base_tag %>
 	<meta charset="utf-8" />
 	<meta name="viewport" content="width=device-width, initial-scale=1">
+    <% if $CanonicalUrl %>
+        <link rel="canonical" href="$CanonicalUrl" />
+    <% end_if %>
 	<title><% if Title %>$Title &#8211; <% end_if %>$DocumentationTitle</title>
 </head>
 

tests/DocumentationPageTest.php

@@ -20,9 +20,7 @@ class DocumentationPageTest extends SapphireTest
         Config::nest();
 
         // explicitly use dev/docs. Custom paths should be tested separately
-        Config::inst()->update(
+        Config::inst()->update('DocumentationViewer', 'link_base', 'dev/docs/');
-            'DocumentationViewer', 'link_base', 'dev/docs/'
-        );
 
         $manifest = new DocumentationManifest(true);
     }
@@ -91,4 +89,22 @@ class DocumentationPageTest extends SapphireTest
 
         $this->assertEquals('Sort - Doctest', $page->getBreadcrumbTitle());
     }
+
+    public function testGetCanonicalUrl()
+    {
+        $page = new DocumentationPage(
+            $this->entity,
+            'file.md',
+            DOCSVIEWER_PATH . '/tests/docs/en/test/file.md'
+        );
+
+        $this->assertContains(
+            'dev/docs/en/test/file/',
+            $page->getCanonicalUrl(),
+            'Canonical URL is determined, set and returned'
+        );
+
+        $page->setCanonicalUrl('some-other-url');
+        $this->assertSame('some-other-url', $page->getCanonicalUrl(), 'Canonical URL can be adjusted via public API');
+    }
 }

tests/DocumentationViewerTest.php

@@ -230,4 +230,20 @@ class DocumentationViewerTest extends FunctionalTest
         // redirect should have been to the absolute url minus the .md extension
         $this->assertEquals(Director::absoluteURL('dev/docs/en/doc_test/3.0/tutorials/'), $response->getHeader('Location'));
     }
+
+    public function testCanonicalUrlIsIncludedInLayout()
+    {
+        $response = $this->get('dev/docs/en/doc_test/2.3/subfolder/subsubfolder/subsubpage');
+
+        $this->assertEquals(200, $response->getStatusCode());
+
+        $expectedUrl = Director::absoluteURL('dev/docs/en/subfolder/subsubfolder/subsubpage/');
+        $this->assertContains('<link rel="canonical" href="' . $expectedUrl . '" />', (string) $response->getBody());
+    }
+
+    public function testCanonicalUrlIsEmptyWhenNoPageExists()
+    {
+        $viewer = new DocumentationViewer;
+        $this->assertSame('', $viewer->getCanonicalUrl());
+    }
 }