Add support for api_reference_noindex config (#2252)

Author: robertoaloi

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+  * Enhancements
+    * Add `:api_reference_noindex` option to keep search engines from indexing `api-reference.html`
+
 ## v0.40.3 (2026-05-21)
 
   * Enhancements

lib/ex_doc.ex

@@ -14,6 +14,10 @@ defmodule ExDoc do
     * `:api_reference` - Whether to generate `api-reference.html`; default: `true`.
       If this is set to false, `:main` must also be set.
 
+    * `:api_reference_noindex` - Whether to add a `<meta name="robots" content="noindex">`
+      tag to `api-reference.html`, asking search engines not to index it; default: `false`.
+      Useful when the page is large and its individual entries are already indexed.
+
     * `:assets` - A map of source => target directories that will be copied as is to
       the output path. It defaults to an empty map.
 

lib/ex_doc/formatter/config.ex

@@ -22,6 +22,7 @@ defmodule ExDoc.Formatter.Config do
             version: nil,
             main: "api-reference",
             api_reference: true,
+            api_reference_noindex: false,
             canonical: nil,
             redirects: %{},
             assets: %{},
@@ -57,6 +58,7 @@ defmodule ExDoc.Formatter.Config do
           version: nil | String.t(),
           main: nil | String.t(),
           api_reference: boolean(),
+          api_reference_noindex: boolean(),
           canonical: nil | String.t(),
           redirects: %{optional(String.t()) => String.t()} | [{String.t(), String.t()}],
           assets: %{binary() => binary()},
@@ -131,6 +133,7 @@ defmodule ExDoc.Formatter.Config do
       Keyword.take(options, [
         :main,
         :api_reference,
+        :api_reference_noindex,
         :canonical,
         :redirects,
         :assets,

lib/ex_doc/formatter/html/templates/api_reference_template.eex

@@ -1,4 +1,4 @@
-<%= head_template(config, "API Reference", false) %>
+<%= head_template(config, "API Reference", config.api_reference_noindex) %>
 <%= sidebar_template(config, :extra) %>
 
 <div id="top-content">

test/ex_doc/formatter/html_test.exs

@@ -138,6 +138,21 @@ defmodule ExDoc.Formatter.HTMLTest do
     refute content =~ ~r{"id":"api-reference","title":"API Reference"}
   end
 
+  test "does not add noindex to api-reference by default", %{tmp_dir: tmp_dir} = context do
+    generate(config(context))
+
+    content = File.read!(tmp_dir <> "/html/api-reference.html")
+    refute content =~ ~r{<meta name="robots" content="noindex">}
+  end
+
+  test "adds noindex to api-reference when :api_reference_noindex is true",
+       %{tmp_dir: tmp_dir} = context do
+    generate(config(context, api_reference_noindex: true))
+
+    content = File.read!(tmp_dir <> "/html/api-reference.html")
+    assert content =~ ~r{<meta name="robots" content="noindex">}
+  end
+
   test "generates markdown links when markdown formatter is included",
        %{tmp_dir: tmp_dir} = context do
     generate(