chore: fallback to empty custom list when building and searching

README.md

@@ -492,9 +492,46 @@ For this example, we've changed the module `:my_module` to `:my_module2`, and th
   {"get-started", "quickstart"}
 ]}.
 ```
-
 <!-- tabs-close -->
 
+## Customizing Autocomplete
+
+In ExDoc, there are two kinds of searches. There is the "autocomplete", which is what shows up when you type in the top search bar,
+and "search" which is the separate page with results that you arrive at if you submit the search bar without selecting an autocompleted
+item. Currently, only the autocompletions are customizable.
+
+You can add to the available autocompletions by specifying the `custom_autocompletions` option in your documentation. This must be a list of
+maps or keyword lists with the following shape:
+
+### Elixir
+
+```elixir
+custom_autocompletions: [
+  %{
+    link: "a-page.html#anchor",
+    title: "custom-text",
+    description: "Some Custom Text",
+    labels: ["Text"]
+  }
+]
+```
+
+### Erlang
+
+```erlang
+{custom_autocompletions, [
+  {link, "a-page.html#anchor"},
+  {title, "custom-text"},
+  {description, "Some Custom Text"},
+  {labels, ["Text"]}
+]}
+```
+
+The `link` is expected to be a relative link to a page in your documentation. You may user anchor links.
+The `title` is the term that will be searched, and what will be shown as the primary text in the search result.
+The `description` is text that will be shown below the search result, and `labels` will be shown as badges
+next to that content.
+
 ## Contributing
 
 The easiest way to test changes to ExDoc is to locally rebuild the app and its own documentation:

assets/js/autocomplete/suggestions.js

@@ -44,7 +44,7 @@ export function getSuggestions (query, limit = 8) {
     ...findSuggestionsInSectionsOfNodes(nodes.modules, query, SUGGESTION_CATEGORY.section, 'module'),
     ...findSuggestionsInSectionsOfNodes(nodes.tasks, query, SUGGESTION_CATEGORY.section, 'mix task'),
     ...findSuggestionsInSectionsOfNodes(nodes.extras, query, SUGGESTION_CATEGORY.section, 'page'),
-    ...findSuggestionsInCustomSidebarNodes(nodes.custom, query, SUGGESTION_CATEGORY.custom, 'custom')
+    ...findSuggestionsInCustomSidebarNodes(nodes.custom || [], query, SUGGESTION_CATEGORY.custom, 'custom')
   ].filter(suggestion => suggestion !== null)
 
   return sort(suggestions).slice(0, limit)

lib/ex_doc/config.ex

@@ -12,7 +12,7 @@ defmodule ExDoc.Config do
   def skip_undefined_reference_warnings_on(_string), do: false
   def skip_code_autolink_to(_string), do: false
 
-  @type custom_auto_completion :: %{
+  @type custom_autocompletion :: %{
           required(:link) => String.t(),
           required(:title) => String.t(),
           required(:description) => String.t(),
@@ -71,7 +71,7 @@ defmodule ExDoc.Config do
           before_closing_body_tag: (atom() -> String.t()) | mfa() | map(),
           before_closing_footer_tag: (atom() -> String.t()) | mfa() | map(),
           before_closing_head_tag: (atom() -> String.t()) | mfa() | map(),
-          custom_autocompletions: [custom_auto_completion],
+          custom_autocompletions: [custom_autocompletion],
           canonical: nil | String.t(),
           cover: nil | Path.t(),
           default_group_for_doc: (keyword() -> String.t() | nil),
@@ -123,6 +123,7 @@ defmodule ExDoc.Config do
     {groups_for_docs, options} = Keyword.pop(options, :groups_for_docs, [])
     {groups_for_extras, options} = Keyword.pop(options, :groups_for_extras, [])
     {groups_for_modules, options} = Keyword.pop(options, :groups_for_modules, [])
+    {custom_autocompletions, options} = Keyword.pop(options, :custom_autocompletions, [])
 
     {skip_undefined_reference_warnings_on, options} =
       Keyword.pop(
@@ -140,6 +141,7 @@ defmodule ExDoc.Config do
       end)
 
     preconfig = %__MODULE__{
+      custom_autocompletions: normalize_custom_autocompletions(custom_autocompletions),
       filter_modules: normalize_filter_modules(filter_modules),
       groups_for_docs: normalize_groups(groups_for_docs),
       groups_for_extras: normalize_groups(groups_for_extras),
@@ -164,6 +166,12 @@ defmodule ExDoc.Config do
     struct(preconfig, options)
   end
 
+  defp normalize_custom_autocompletions(custom_autocompletions) do
+    Enum.map(custom_autocompletions, fn autocompletion ->
+      Map.new(autocompletion)
+    end)
+  end
+
   defp normalize_output(output) do
     String.trim_trailing(output, "/")
   end

lib/ex_doc/formatter/html.ex

@@ -183,7 +183,9 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   defp generate_sidebar_items(nodes_map, extras, config) do
-    content = Templates.create_sidebar_items(nodes_map, extras, config.custom_autocompletions)
+    content =
+      Templates.create_sidebar_items(nodes_map, extras, config.custom_autocompletions || [])
+
     path = "dist/sidebar_items-#{digest(content)}.js"
     File.write!(Path.join(config.output, path), content)
     [path]