Rebuild Aliki's searching mechanism (#1504)

Rebuild Aliki's search mechanism with a custom search index and improved
ranking algorithm.

Key changes:
- Aliki now generates its own search index (`js/search_data.js`) instead
of using the shared JsonIndex generator (can be removed along with
Darkfish in the future)
- New search ranking algorithm with better prioritization:
- Lowercase queries prioritize methods; uppercase queries prioritize
classes/modules/constants
  - Exact matches rank higher; shorter names preferred
- Class methods rank above instance methods (I don't have strong opinion
on this one)
- Search results now display type badges (class, module, const, method)
- Constants are now included in search results

Closes #1497 

<img width="50%" alt="Screenshot 2025-12-16 at 17 57 50"
src="https://github.com/user-attachments/assets/689cd862-3669-43f7-93e1-218923f3cd0e"
/>

Author: st0012

lib/rdoc/code_object/class_module.rb

@@ -689,6 +689,9 @@ def remove_things(my_things, other_files) # :nodoc:
 
   ##
   # Search record used by RDoc::Generator::JsonIndex
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     [
@@ -702,6 +705,16 @@ def search_record
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the first comment for search results.
+
+  def search_snippet
+    first_comment = @comment_location.first&.first
+    return '' unless first_comment && !first_comment.empty?
+
+    snippet(first_comment)
+  end
+
   ##
   # Sets the store for this class or module and its contained code objects.
 

lib/rdoc/code_object/constant.rb

@@ -154,6 +154,15 @@ def path
     "#{@parent.path}##{@name}"
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if comment.empty?
+
+    snippet(comment)
+  end
+
   def pretty_print(q) # :nodoc:
     q.group 2, "[#{self.class.name} #{full_name}", "]" do
       unless comment.empty? then

lib/rdoc/code_object/method_attr.rb

@@ -375,6 +375,9 @@ def pretty_print(q) # :nodoc:
   ##
   # Used by RDoc::Generator::JsonIndex to create a record for the search
   # engine.
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     [
@@ -384,10 +387,19 @@ def search_record
       @parent.full_name,
       path,
       params,
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   def to_s # :nodoc:
     if @is_alias_for
       "#{self.class.name}: #{full_name} -> #{is_alias_for}"

lib/rdoc/code_object/top_level.rb

@@ -237,6 +237,9 @@ def pretty_print(q) # :nodoc:
 
   ##
   # Search record used by RDoc::Generator::JsonIndex
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     return unless @parser < RDoc::Parser::Text
@@ -248,10 +251,19 @@ def search_record
       '',
       path,
       '',
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   ##
   # Is this TopLevel from a text file instead of a source code file?
 

lib/rdoc/generator/aliki.rb

@@ -15,6 +15,30 @@ def initialize(store, options)
     @template_dir = Pathname.new(aliki_template_dir)
   end
 
+  ##
+  # Generate documentation. Overrides Darkfish to use Aliki's own search index
+  # instead of the JsonIndex generator.
+
+  def generate
+    setup
+
+    write_style_sheet
+    generate_index
+    generate_class_files
+    generate_file_files
+    generate_table_of_contents
+    write_search_index
+
+    copy_static
+
+  rescue => e
+    debug_msg "%s: %s\n  %s" % [
+      e.class.name, e.message, e.backtrace.join("\n  ")
+    ]
+
+    raise
+  end
+
   ##
   # Copy only the static assets required by the Aliki theme. Unlike Darkfish we
   # don't ship embedded fonts or image sprites, so limit the asset list to keep
@@ -39,4 +63,104 @@ def write_style_sheet
       install_rdoc_static_file @template_dir + path, dst, options
     end
   end
+
+  ##
+  # Build a search index array for Aliki's searcher.
+
+  def build_search_index
+    setup
+
+    index = []
+
+    @classes.each do |klass|
+      next unless klass.display?
+
+      index << build_class_module_entry(klass)
+
+      klass.constants.each do |const|
+        next unless const.display?
+
+        index << build_constant_entry(const, klass)
+      end
+    end
+
+    @methods.each do |method|
+      next unless method.display?
+
+      index << build_method_entry(method)
+    end
+
+    index
+  end
+
+  ##
+  # Write the search index as a JavaScript file
+  # Format: var search_data = { index: [...] }
+  #
+  # We still write to a .js instead of a .json because loading a JSON file triggers CORS check in browsers.
+  # And if we simply inspect the generated pages using file://, which is often the case due to lack of the server mode,
+  # the JSON file will be blocked by the browser.
+
+  def write_search_index
+    debug_msg "Writing Aliki search index"
+
+    index = build_search_index
+
+    FileUtils.mkdir_p 'js' unless @dry_run
+
+    search_index_path = 'js/search_data.js'
+    return if @dry_run
+
+    data = { index: index }
+    File.write search_index_path, "var search_data = #{JSON.generate(data)};"
+  end
+
+  private
+
+  def build_class_module_entry(klass)
+    type = case klass
+           when RDoc::NormalClass then 'class'
+           when RDoc::NormalModule then 'module'
+           else 'class'
+           end
+
+    entry = {
+      name: klass.name,
+      full_name: klass.full_name,
+      type: type,
+      path: klass.path
+    }
+
+    snippet = klass.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_method_entry(method)
+    type = method.singleton ? 'class_method' : 'instance_method'
+
+    entry = {
+      name: method.name,
+      full_name: method.full_name,
+      type: type,
+      path: method.path
+    }
+
+    snippet = method.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_constant_entry(const, parent)
+    entry = {
+      name: const.name,
+      full_name: "#{parent.full_name}::#{const.name}",
+      type: 'constant',
+      path: parent.path
+    }
+
+    snippet = const.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
 end

lib/rdoc/generator/template/aliki/_head.rhtml

@@ -116,22 +116,22 @@
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/navigation.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_navigation.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/search.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_data.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/search_index.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_ranker.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/searcher.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_controller.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 

lib/rdoc/generator/template/aliki/css/rdoc.css

@@ -85,6 +85,16 @@
   --color-th-background: var(--color-neutral-100);
   --color-td-background: var(--color-neutral-50);
 
+  /* Search Type Badge Colors */
+  --color-search-type-class-bg: #e6f0ff;
+  --color-search-type-class-text: #0050a0;
+  --color-search-type-module-bg: #e6ffe6;
+  --color-search-type-module-text: #060;
+  --color-search-type-constant-bg: #fff0e6;
+  --color-search-type-constant-text: #995200;
+  --color-search-type-method-bg: #f0e6ff;
+  --color-search-type-method-text: #5200a0;
+
   /* RGBA Colors (theme-agnostic) */
   --color-overlay: rgb(0 0 0 / 50%);
   --color-emphasis-bg: rgb(255 111 97 / 10%);
@@ -218,6 +228,16 @@
   --color-th-background: var(--color-background-tertiary);
   --color-td-background: var(--color-background-secondary);
 
+  /* Search Type Badge Colors - Dark Theme */
+  --color-search-type-class-bg: #1e3a5f;
+  --color-search-type-class-text: #93c5fd;
+  --color-search-type-module-bg: #14532d;
+  --color-search-type-module-text: #86efac;
+  --color-search-type-constant-bg: #451a03;
+  --color-search-type-constant-text: #fcd34d;
+  --color-search-type-method-bg: #3b0764;
+  --color-search-type-method-text: #d8b4fe;
+
   /* Dark theme shadows (slightly more subtle) */
   --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 40%), 0 1px 2px -1px rgb(0 0 0 / 40%);
   --shadow-md: 0 2px 8px rgb(0 0 0 / 40%);
@@ -1834,6 +1854,39 @@ footer.site-footer .footer-bottom:first-child {
   font-weight: bold;
 }
 
+#search-results .search-type {
+  display: inline-block;
+  margin-left: var(--space-2);
+  padding: 0 var(--space-2);
+  font-size: var(--font-size-xs);
+  font-weight: 500;
+  border-radius: var(--radius-sm);
+  vertical-align: middle;
+  background: var(--color-background-tertiary);
+  color: var(--color-text-secondary);
+}
+
+#search-results .search-type-class {
+  background: var(--color-search-type-class-bg);
+  color: var(--color-search-type-class-text);
+}
+
+#search-results .search-type-module {
+  background: var(--color-search-type-module-bg);
+  color: var(--color-search-type-module-text);
+}
+
+#search-results .search-type-constant {
+  background: var(--color-search-type-constant-bg);
+  color: var(--color-search-type-constant-text);
+}
+
+#search-results .search-type-instance-method,
+#search-results .search-type-class-method {
+  background: var(--color-search-type-method-bg);
+  color: var(--color-search-type-method-text);
+}
+
 #search-results li em {
   background-color: var(--color-search-highlight-bg);
   font-style: normal;

lib/rdoc/generator/template/aliki/js/aliki.js

@@ -28,7 +28,7 @@ function createSearchInstance(input, result) {
 
   result.classList.remove("initially-hidden");
 
-  const search = new Search(search_data, input, result);
+  const search = new SearchController(search_data, input, result);
 
   search.renderItem = function(result) {
     const li = document.createElement('li');
@@ -40,8 +40,12 @@ function createSearchInstance(input, result) {
       html += `<span class="params">${result.params}</span>`;
     html += '</a>';
 
-    if (result.namespace)
-      html += `<p class="search-namespace">${this.hlt(result.namespace)}`;
+    // Add type indicator
+    if (result.type) {
+      const typeLabel = this.formatType(result.type);
+      const typeClass = result.type.replace(/_/g, '-');
+      html += `<span class="search-type search-type-${this.escapeHTML(typeClass)}">${typeLabel}</span>`;
+    }
 
     if (result.snippet)
       html += `<div class="search-snippet">${result.snippet}</div>`;
@@ -51,6 +55,17 @@ function createSearchInstance(input, result) {
     return li;
   }
 
+  search.formatType = function(type) {
+    const typeLabels = {
+      'class': 'class',
+      'module': 'module',
+      'constant': 'const',
+      'instance_method': 'method',
+      'class_method': 'method'
+    };
+    return typeLabels[type] || type;
+  }
+
   search.select = function(result) {
     let href = result.firstChild.firstChild.href;
     const query = this.input.value;