Throw an error early in HTMLWriter when there are no pages (#1491)

CHANGELOG.md

@@ -12,6 +12,8 @@
 
 * ![Enhancement][badge-enhancement] The HTML front end now respects the user's OS-level dark theme preference (determined via the `prefers-color-scheme: dark` media query). ([#1320][github-1320], [#1456][github-1456])
 
+* ![Enhancement][badge-enhancement] HTML output now bails early if there are no pages, instead of throwing an `UndefRefError`. In addition, it will also warn if `index.md` is missing and it is not able to generate the main landing page (`index.html`). ([#1201][github-1201], [#1491][github-1491])
+
 ## Version `v0.25.5`
 
 * ![Bugfix][badge-bugfix] In the HTML output, display equations that are wider than the page now get a scrollbar instead of overflowing. ([#1470][github-1470], [#1476][github-1476])
@@ -644,6 +646,7 @@
 [github-1194]: https://github.com/JuliaDocs/Documenter.jl/pull/1194
 [github-1195]: https://github.com/JuliaDocs/Documenter.jl/pull/1195
 [github-1200]: https://github.com/JuliaDocs/Documenter.jl/issues/1200
+[github-1201]: https://github.com/JuliaDocs/Documenter.jl/issues/1201
 [github-1212]: https://github.com/JuliaDocs/Documenter.jl/issues/1212
 [github-1216]: https://github.com/JuliaDocs/Documenter.jl/pull/1216
 [github-1222]: https://github.com/JuliaDocs/Documenter.jl/pull/1222
@@ -709,6 +712,7 @@
 [github-1472]: https://github.com/JuliaDocs/Documenter.jl/pull/1472
 [github-1474]: https://github.com/JuliaDocs/Documenter.jl/pull/1474
 [github-1476]: https://github.com/JuliaDocs/Documenter.jl/pull/1476
+[github-1491]: https://github.com/JuliaDocs/Documenter.jl/pull/1491
 [github-1493]: https://github.com/JuliaDocs/Documenter.jl/pull/1493
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079

src/Writers/HTMLWriter.jl

@@ -627,6 +627,11 @@ getpage(ctx, navnode::Documents.NavNode) = getpage(ctx, navnode.page)
 function render(doc::Documents.Document, settings::HTML=HTML())
     @info "HTMLWriter: rendering HTML pages."
     !isempty(doc.user.sitename) || error("HTML output requires `sitename`.")
+    if isempty(doc.blueprint.pages)
+        error("Aborting HTML build: no pages under src/")
+    elseif !haskey(doc.blueprint.pages, "index.md")
+        @warn "Can't generate landing page (index.html): src/index.md missing" keys(doc.blueprint.pages)
+    end
 
     ctx = HTMLContext(doc, settings)
     ctx.search_index_js = "search_index.js"
@@ -955,7 +960,7 @@ function render_sidebar(ctx, navnode)
     )
 
     # The menu itself
-    menu = navitem(NavMenuContext(ctx, navnode, ))
+    menu = navitem(NavMenuContext(ctx, navnode))
     push!(menu.attributes, :class => "docs-menu")
     push!(navmenu.nodes, menu)
 

test/doctests/doctests.jl

@@ -29,6 +29,9 @@ function run_makedocs(f, mdfiles, modules=Module[]; kwargs...)
     for mdfile in mdfiles
         cp(joinpath(@__DIR__, "src", mdfile), joinpath(srcdir, mdfile))
     end
+    # Create a dummy index.md file so that we wouldn't generate the "can't generated landing
+    # page" warning.
+    touch(joinpath(srcdir, "index.md"))
 
     c = IOCapture.iocapture(throwerrors = :interrupt) do
         makedocs(