diff --git a/CHANGELOG.md b/CHANGELOG.md index a46da0baf..8f09be10d 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex index 11641e6ea..82d8a37b6 100644 --- a/lib/ex_doc.ex +++ b/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 `` + 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. diff --git a/lib/ex_doc/formatter/config.ex b/lib/ex_doc/formatter/config.ex index 284ad1c7c..dd624dbd4 100644 --- a/lib/ex_doc/formatter/config.ex +++ b/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, diff --git a/lib/ex_doc/formatter/html/templates/api_reference_template.eex b/lib/ex_doc/formatter/html/templates/api_reference_template.eex index 4b164a267..afb2f9699 100644 --- a/lib/ex_doc/formatter/html/templates/api_reference_template.eex +++ b/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) %>
diff --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs index 0771c9123..a49d15f68 100644 --- a/test/ex_doc/formatter/html_test.exs +++ b/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{} + 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{} + end + test "generates markdown links when markdown formatter is included", %{tmp_dir: tmp_dir} = context do generate(