Warn when the search index size is too big (#2753)

Author: Rahban1

CHANGELOG.md

@@ -3,6 +3,12 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Changed
+
+* Created a warning for when the search index size is too big (500Kib). ([#2423], [#2753])
+
 ## Version [v1.14.1] - 2025-07-09
 
 ### Fixed
@@ -2051,6 +2057,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2410]: https://github.com/JuliaDocs/Documenter.jl/issues/2410
 [#2414]: https://github.com/JuliaDocs/Documenter.jl/issues/2414
 [#2415]: https://github.com/JuliaDocs/Documenter.jl/issues/2415
+[#2423]: https://github.com/JuliaDocs/Documenter.jl/issues/2423
 [#2424]: https://github.com/JuliaDocs/Documenter.jl/issues/2424
 [#2430]: https://github.com/JuliaDocs/Documenter.jl/issues/2430
 [#2434]: https://github.com/JuliaDocs/Documenter.jl/issues/2434
@@ -2131,6 +2138,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2737]: https://github.com/JuliaDocs/Documenter.jl/issues/2737
 [#2748]: https://github.com/JuliaDocs/Documenter.jl/issues/2748
 [#2750]: https://github.com/JuliaDocs/Documenter.jl/issues/2750
+[#2753]: https://github.com/JuliaDocs/Documenter.jl/issues/2753
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054
 [JuliaLang/julia#39841]: https://github.com/JuliaLang/julia/issues/39841

src/html/HTMLWriter.jl

@@ -501,6 +501,7 @@ struct HTML <: Documenter.Writer
     size_threshold_warn::Int
     size_threshold_ignore::Vector{String}
     example_size_threshold::Int
+    search_size_threshold_warn::Int
     inventory_version::Union{String, Nothing}
 
     function HTML(;
@@ -530,6 +531,7 @@ struct HTML <: Documenter.Writer
             # seems reasonable, and that would lead to ~80 KiB, which is still fine
             # and leaves a buffer before hitting `size_threshold_warn`.
             example_size_threshold::Union{Integer, Nothing} = 8 * 2^10, # 8 KiB
+            search_size_threshold_warn::Union{Integer, Nothing} = 500 * 2^10, # 500 KiB
             inventory_version = nothing,
 
             # deprecated keywords
@@ -581,6 +583,11 @@ struct HTML <: Documenter.Writer
         elseif example_size_threshold < 0
             throw(ArgumentError("example_size_threshold must be non-negative, got $(example_size_threshold)"))
         end
+        if isnothing(search_size_threshold_warn)
+            search_size_threshold_warn = typemax(Int)
+        elseif search_size_threshold_warn <= 0
+            throw(ArgumentError("search_size_threshold_warn must be non-negative, got $(search_size_threshold_warn)"))
+        end
         isa(edit_link, Default) && (edit_link = edit_link[])
         # We use normpath() when we construct the .page value for NavNodes, so we also need to normpath()
         # these values. This also ensures cross-platform compatibility of the values.
@@ -590,6 +597,7 @@ struct HTML <: Documenter.Writer
             collapselevel, sidebar_sitename, highlights, mathengine, description, footer,
             ansicolor, lang, warn_outdated, prerender, node, highlightjs,
             size_threshold, size_threshold_warn, size_threshold_ignore, example_size_threshold,
+            search_size_threshold_warn,
             (isnothing(inventory_version) ? nothing : string(inventory_version))
         )
     end
@@ -861,11 +869,25 @@ function render(doc::Documenter.Document, settings::HTML = HTML())
     # Check that all HTML files are smaller or equal to size_threshold option
     all(size_limit_successes) || throw(HTMLSizeThresholdError())
 
-    open(joinpath(doc.user.build, ctx.search_index_js), "w") do io
+    # Check the size of the search index
+    search_index_path = joinpath(doc.user.build, ctx.search_index_js)
+    open(search_index_path, "w") do io
         println(io, "var documenterSearchIndex = {\"docs\":")
         # convert Vector{SearchRecord} to a JSON string + do additional JS escaping
         println(io, JSDependencies.json_jsescape(ctx.search_index), "\n}")
     end
+    let file_size = filesize(search_index_path)
+        if file_size > settings.search_size_threshold_warn
+            file_size_format_results = format_units(file_size)
+            size_threshold_warn_format_results = format_units(settings.search_size_threshold_warn)
+            @warn """
+            Generated search index over size_threshold_warn limit:
+                Generated file size: $(file_size_format_results)
+                search_size_threshold_warn: $(size_threshold_warn_format_results)
+                Search index file:   $(search_index_path)
+            """
+        end
+    end
 
     write_inventory(doc, ctx)