Merge branch '1130-algolia-custom-ranking' into 'main'

Add page ranking capabilities for Algolia search

Closes #1130

See merge request https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/2976

Merged-by: Suzanne Selhorn <sselhorn@gitlab.com>
Approved-by: Suzanne Selhorn <sselhorn@gitlab.com>
Approved-by: David O'Regan <doregan@gitlab.com>
Co-authored-by: Sarah German <sgerman@gitlab.com>

5 files changed, 89 insertions, 1 deletions

diff --git a/content/assets/stylesheets/stylesheet.scss b/content/assets/stylesheets/stylesheet.scss
index 59e1afa3..02a28ec4 100644
--- a/content/assets/stylesheets/stylesheet.scss
+++ b/content/assets/stylesheets/stylesheet.scss
@@ -519,7 +519,7 @@ h6[id]::before {
 // external link and footer social links
 [href^='http://'],
 [href^='https://'] {
-  &:not([href*='gitlab.com']):not(.gitlab-social):not(.no-attachment-icon) {
+  &:not([href*='gitlab.com']):not([href*='nip.io']):not(.gitlab-social):not(.no-attachment-icon) {
     &::after {
       content: '\f08e';
       font-family: FontAwesome, sans-serif;
diff --git a/layouts/head.html b/layouts/head.html
index d1b264d4..9708a231 100644
--- a/layouts/head.html
+++ b/layouts/head.html
@@ -24,6 +24,8 @@
 <% else %>
 <meta name="docsearch:version" content="<%= ENV['CI_DEFAULT_BRANCH'] %>" />
 <% end %>
+<meta name="docsearch:pageRank" content="<%= algolia_rank(@item).to_s %>" />
+<meta name="docsearch:level" content="<%= algolia_level(@item).to_s %>" />
 <link crossorigin href="https://3PNCFOU757-dsn.algolia.net" rel="preconnect" />
 <!-- Algolia Searching from the URL bar https://www.algolia.com/doc/tutorials/search-ui/ux-patterns/search-from-the-url-bar/ -->
 <link href='/opensearch.xml' rel='search' title='Search through GitLab Docs' type='application/opensearchdescription+xml'>
diff --git a/lib/helpers/algolia_rank.rb b/lib/helpers/algolia_rank.rb
new file mode 100644
index 00000000..3e14f0d7
--- /dev/null
+++ b/lib/helpers/algolia_rank.rb
@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Nanoc::Helpers
+    module AlgoliaRank
+        ###
+        # Add a URL pattern and weight to CUSTOM_PAGERANKS to modify Algolia search results.
+        #
+        # Weights greater than DEFAULT_PAGERANK will boost a page in search results,
+        # and weights below DEFAULT_PAGERANK will lower its ranking.
+        #
+        # The weight value appears in the "docsearch:pageRank" metatag
+        # on each page that contains the URL pattern.
+        #
+        # For example, the "/runner/development/reviewing-gitlab-runner.html" page
+        # will match "/runner/development" in CUSTOM_PAGERANKS and receive a weight of "20".
+        # 
+        # @see https://docsearch.algolia.com/docs/record-extractor/#boost-search-results-with-pagerank
+        ## 
+        DEFAULT_PAGERANK = 100
+        CUSTOM_PAGERANKS = {
+            "/ee/api"               => 50,
+            "/ee/development"       => 20,
+            "/omnibus/development"  => 20,
+            "/runner/development"   => 20,
+            "/charts/development"   => 20,
+        }
+
+        def algolia_rank(item)
+            if result = CUSTOM_PAGERANKS.keys.find {|k| item.identifier.to_s.include? k}
+                return CUSTOM_PAGERANKS[result]
+            else
+                return DEFAULT_PAGERANK
+            end
+        end
+
+        ###
+        # Calculate the navigation level of a given page.
+        # We use this on Algolia to increase relevance of higher-level pages.
+        ###
+        def algolia_level(item)
+            path = item.identifier.to_s
+            level = path.scan("/").count
+            if path.include? "index.md"
+                level -= 1
+            end
+            return level
+        end
+
+    end
+end
diff --git a/lib/helpers_.rb b/lib/helpers_.rb
index 6037d04c..ed7eaeda 100644
--- a/lib/helpers_.rb
+++ b/lib/helpers_.rb
@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+use_helper Nanoc::Helpers::AlgoliaRank
 use_helper Nanoc::Helpers::EditOnGitLab
 use_helper Nanoc::Helpers::Generic
 use_helper Nanoc::Helpers::GitLabKramdown
diff --git a/spec/lib/helpers/algolia_rank_spec.rb b/spec/lib/helpers/algolia_rank_spec.rb
new file mode 100644
index 00000000..7156446d
--- /dev/null
+++ b/spec/lib/helpers/algolia_rank_spec.rb
@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'nanoc'
+require 'helpers/algolia_rank'
+
+RSpec.describe Nanoc::Helpers::AlgoliaRank do
+    let(:mock_class) { Class.new { extend Nanoc::Helpers::AlgoliaRank } }
+    let(:identifier) { "/runner/development/reviewing-gitlab-runner.html" }
+
+    let(:mock_item) do
+      item = Struct.new(:identifier)
+      item.new(identifier)
+    end
+
+    subject { mock_class.algolia_rank(mock_item) }
+
+    describe '#algolia_rank' do
+      using RSpec::Parameterized::TableSyntax
+
+      where(:url_pattern, :identifier, :weight) do
+        "/ee/api"             | "/ee/api/openapi/openapi_interactive.html"              | 50
+        "/runner/development" | "/runner/development/reviewing-gitlab-runner.html"      | 20
+        "/ee/development"     | "/ee/development/documentation/graphql_styleguide.html" | 20
+        ""                    | "/ee/install/installation.html"                         | 100
+      end
+
+      with_them do
+        it 'returns correct weight for matched identifier' do
+          expect(subject).to eq(weight)
+        end
+      end
+
+    end
+end