add support for matching pages when the page title changes (#567)

content/contribute/contribute.md

@@ -12,8 +12,8 @@ Clone the documentation and use [Hugo](https://gohugo.io/) to
 build the Crossplane documentation site locally for development and testing. 
 
 ### Clone the docs repository
-Clone the [Crossplane docs
-repository](https://github.com/crossplane/docs) with
+Clone the 
+[Crossplane docs repository](https://github.com/crossplane/docs) with
 
 ```command
 git clone https://github.com/crossplane/docs.git
@@ -142,4 +142,19 @@ more.
 ### Hiding pages
 To hide a page from the left-hand navigation use `tocHidden: true` in the front
 matter of the page. The docs website skips pages with `tocHidden:true` when
-building the menu.
+building the menu.
+
+### Changing page titles
+
+The version dropdown list that links the same page in different versions 
+together looks for pages with a matching title.
+
+If a page title changes use the front matter value `matchTitle:` and a value of 
+the old page title.
+
+For example, if an older title was "Original Title" the new page would use:
+
+```yaml
+title: New Title
+matchTitle: Original Title
+```

themes/geekboot/layouts/partials/version-dropdown-menu.html

@@ -38,8 +38,12 @@
         {{ $master_url := replaceRE "v[0-9].[0-9]" "master" .Permalink }}
         {{/*  Iterate over the ordered list of available versions. */}}
         {{ range $sorted_list }}
+            {{ $matchingTitle := $.Title }}
+            {{ if $.Params.matchTitle }}
+                {{ $matchingTitle = $.Params.matchTitle }}
+            {{ end }}
             {{/*  For a version, see if there is a page with an identical title to the page we're on. If not use the page at /content/v<version>  */}}
-            {{ $versionPage :=  index (where (where $.Site.Pages "Title" $.Title) ".Page.Params.version" .) 0 | default ($.Site.GetPage (printf "v%s" .)) }}
+            {{ $versionPage :=  index (where (where $.Site.Pages "Title" $matchingTitle) ".Page.Params.version" .) 0 | default ($.Site.GetPage (printf "v%s" .)) }}
             {{/*  If the version is master get the master page since "vmaster" doesn't exist  */}}
             {{ if not $versionPage }}
                 {{ $versionPage = $.Site.GetPage "master" }}