use custom logic to resolve latest page URL and canonical URL

- delegate to helper to compute latest page URL (latest-page-url)
- delegate to helper to compute canonical URL (canonical-url)
- update latest page URL resolution to consider aliases
- update canonical URL resolution to consider aliases
- don't show prerelease banner if all versions are prereleases
- document the logic for computing the latest page URL and canonical URL
- hide View Latest button if page is not available in latest version

Author: mojavelinux

README.adoc

@@ -360,6 +360,61 @@ You can test the feedback widget directly from the preview site by setting the `
 
 The configuration for the widget is currently hardcoded into the partial template.
 
+== View Latest and Canonical URL
+
+This section documents the logic used to compute the URL for the View Latest button and the canonical URL.
+
+=== View Latest
+
+If the version of the current page does not match the latest version of the component (i.e., product), a banner is displayed to the visitor.
+If the version is a prerelease, the banner states that you're viewing a prerelease version.
+If the version is an older stable release, the banner states that a newer version is available.
+On the banner offers a button named "View Latest" that directs the visitor to the latest version.
+
+The "View Latest" button tries to preserve the current page when switching versions.
+If the page is no longer available, then the button directs the user to the start page for the component.
+
+The URL for the "View Latest" button is computed by the latest-page-url helper.
+Here's the logic that the helper uses:
+
+* If the current page is found in the latest version, the latest page URL resolves to the URL of that page.
+For example, the latest page URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/6.5/introduction/intro.html (assuming 6.5 is the latest version)
+ ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word "current".
+For example, the latest page URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/current/introduction/intro.html
+* If the current page is not found in the latest version, but the page is claimed by an alias, the latest page URL resolves to the URL of the page to which the alias points.
+For example, the latest page URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/6.5/manage/management-overview.html (assuming 6.5 is the latest version)
+ ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word "current".
+For example, the latest page URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/current/manage/management-overview.html
+* If neither the current page or an alias is found in the latest version, the latest page URL resolves to the component start page.
+ ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word "current".
+
+If the current page is in the archive site and the latest version is in the production site, then the latest page URL will point to the production site.
+In this case, the version segment will only be replaced with "current" if the PRIMARY_SITE_SUPPORTS_CURRENT_URL=true environment variable is set.
+
+=== Canonical URL
+
+The canonical URL differs slightly from the URL for the "View Latest" button in that if the page cannot be found in the latest version, it instead resolves to the newest version of the page.
+The canonical URL can resolve to the current URL (if the current URL is the canonical URL).
+
+The canonical URL is computed by the canonical-url helper.
+Here's the logic that the helper uses:
+
+* If the site.url is not set to an absolute path, no value is returned.
+* If the current page is found in the latest version, the canonical URL resolves to the URL of that page.
+For example, the canonical URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/6.5/introduction/intro.html (assuming 6.5 is the latest version)
+ ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word "current".
+For example, the canonical URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/current/introduction/intro.html
+* If the current page is not found in the latest version, but the page is claimed by an alias, the canonical URL resolves to the URL of the page to which the alias points.
+For example, the canonical URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/6.5/manage/management-overview.html (assuming 6.5 is the latest version)
+ ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word "current".
+For example, the canonical URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/current/manage/management-overview.html
+* If neither the current page or an alias is found in the latest version, the current URL resolves to the newest version of the page (which could be the current page).
+For example, the canonical URL for https://docs.couchbase.com/server/4.0/architecture/cluster-ram-quotas.html resolves to https://docs.couchbase.com/server/4.1/architecture/cluster-ram-quotas.html
+ ** If the SUPPORTS_CURRENT_URL=true environment variable is set, it has no affect on this case.
+
+If the current page is in the archive site and the latest version is in the production site, then the canonical URL will point to the production site.
+In this case, the version segment will only be replaced with "current" if the PRIMARY_SITE_SUPPORTS_CURRENT_URL=true environment variable is set and the newest version of the page is the latest version of the component.
+
 == Release the UI Bundle
 
 Once you're satisfied with the changes you've made to the UI and would like to make those changes available to Antora, you'll need to publish the UI as a bundle by making a release.

src/helpers/canonical-url.js

@@ -0,0 +1,40 @@
+'use strict'
+
+const VERSIONED_ROOT_RELATIVE_URL_RX = /^(\/[^/]+)\/[^/]+(?=\/)/
+
+module.exports = ({ data: { root } }) => {
+  const { contentCatalog, env, page, site } = root
+  const siteUrl = site.url
+  if (!siteUrl || siteUrl.charAt() === '/') return
+  let { url, version, missing } = page.versions ? page.latest || { url: page.url } : page
+  const latestVersion = version
+  if (missing) {
+    const family = 'alias'
+    const baseAliasId = { component: page.component.name, module: page.module, family, relative: page.relativeSrcPath }
+    let latestReached
+    for (const it of page.versions) {
+      if (!(latestReached || (latestReached = it.latest))) continue
+      if (it.missing) {
+        const alias = contentCatalog.getById({ ...baseAliasId, version: it.version })
+        if (alias) {
+          url = alias.rel.pub.url
+          version = it.version
+          break
+        }
+      } else {
+        ;({ url, version } = it)
+        break
+      }
+    }
+  }
+  const targetSiteUrl = url.charAt() === '/' ? siteUrl : page.componentVersion.asciidoc.attributes['primary-site-url']
+  if (version === 'master' || version !== latestVersion) {
+    return targetSiteUrl + url
+  } else if (siteUrl === targetSiteUrl) {
+    if (env.SUPPORTS_CURRENT_URL === 'true') return siteUrl + url.replace(VERSIONED_ROOT_RELATIVE_URL_RX, '$1/current')
+    return siteUrl + url
+  } else if (env.PRIMARY_SITE_SUPPORTS_CURRENT_URL === 'true') {
+    return targetSiteUrl + url.substr(targetSiteUrl.length).replace(VERSIONED_ROOT_RELATIVE_URL_RX, '$1/current')
+  }
+  return targetSiteUrl + url
+}

src/helpers/concat.js

@@ -0,0 +1,26 @@
+'use strict'
+
+const VERSIONED_ROOT_RELATIVE_URL_RX = /^(\/[^/]+)\/[^/]+(?=\/)/
+
+module.exports = ({ data: { root } }) => {
+  const { contentCatalog, env, page } = root
+  let { url, version, missing } = page.latest || { url: page.url }
+  if (missing) {
+    const latestAlias = contentCatalog.getById({
+      component: page.component.name,
+      version,
+      module: page.module,
+      family: 'alias',
+      relative: page.relativeSrcPath,
+    })
+    if (!latestAlias) return
+    url = latestAlias.rel.pub.url
+  }
+  if (url.charAt() === '/') {
+    return env.SUPPORTS_CURRENT_URL === 'true' ? url.replace(VERSIONED_ROOT_RELATIVE_URL_RX, '$1/current') : url
+  } else if (env.PRIMARY_SITE_SUPPORTS_CURRENT_URL === 'true') {
+    const primarySiteUrl = page.componentVersion.asciidoc.attributes['primary-site-url']
+    return primarySiteUrl + url.substr(primarySiteUrl.length).replace(VERSIONED_ROOT_RELATIVE_URL_RX, '$1/current')
+  }
+  return url
+}

src/helpers/current-url.js

@@ -3,9 +3,9 @@
   <head>
 {{> head-first}}
     <title>{{{detag (or page.title 'Untitled')}}}{{#with site.title}} | {{this}}{{/with}}</title>
-    {{#if page.canonicalUrl}}
-    <link rel="canonical" href="{{#if (and (eq env.SUPPORTS_CURRENT_URL 'true') (ne page.version 'master'))}}{{concat site.url (current-url page.url)}}{{else}}{{page.canonicalUrl}}{{/if}}">
-    {{/if}}
+    {{#with (canonical-url)}}
+    <link rel="canonical" href="{{this}}">
+    {{/with}}
 {{> head-last}}
   </head>
   <body class="article">

src/helpers/latest-page-url.js

@@ -3,9 +3,9 @@
   <head>
 {{> head-first}}
     <title>Tutorials{{#with site.title}} | {{this}}{{/with}}</title>
-    {{#if page.canonicalUrl}}
-    <link rel="canonical" href="{{#if (and (eq env.SUPPORTS_CURRENT_URL 'true') (ne page.version 'master'))}}{{concat site.url (current-url page.url)}}{{else}}{{page.canonicalUrl}}{{/if}}">
-    {{/if}}
+    {{#with (canonical-url)}}
+    <link rel="canonical" href="{{this}}">
+    {{/with}}
 {{> head-last}}
   </head>
   <body class="tutorials body tiles">

src/layouts/default.hbs

@@ -1,18 +1,23 @@
 <main class="article" data-ceiling="topbar">
-  {{#unless (or page.attributes.hide-view-latest (eq page.componentVersion page.component.latest))}}
+  {{#unless (or (ne page.attributes.hide-view-latest undefined) (eq page.componentVersion page.component.latest))}}
+  {{#with (latest-page-url)}}
   <div class="article-banner">
-    {{#if page.componentVersion.prerelease}}
+    {{#if (and @root.page.componentVersion.prerelease (not @root.page.latest.prerelease))}}
     <p>You are viewing the documentation for a prerelease version.</p>
     {{else}}
-    <p> <i class="fab fa-asymmetrik"></i> A newer version of this documentation is available.</p>
+    <p><i class="fab fa-asymmetrik"></i> A newer version of this documentation is available.</p>
     {{/if}}
-    <a class="btn" href="{{#if (eq env.SUPPORTS_CURRENT_URL 'true')}}{{relativize (current-url page.url)}}{{else}}{{relativize page.latest.url}}{{/if}}">View Latest</a>
+    <a class="btn" href="{{relativize this}}">View Latest</a>
   </div>
+  {{else if (and page.componentVersion.prerelease (not page.latest.prerelease))}}
+  <div class="article-banner">
+    <p>You are viewing the documentation for a prerelease version.</p>
+  </div>
+  {{/with}}
   {{/unless}}
   <div class="article-header">
 {{> nav-control}}
 {{> crumbs}}
-{{!-- {{> toolbar}} --}}
   </div>
 {{> article}}
 </main>