From 2efcd23dfcc5f261d2181b1b885c9137059105ea Mon Sep 17 00:00:00 2001
From: odow <o.dowson@gmail.com>
Date: Thu, 2 Nov 2023 10:22:23 +1300
Subject: [PATCH 1/3] Warn on unsupported arguments in contents, index,
 autodocs, and meta blocks

---
 src/documents.jl         | 14 ++++++++++++++
 src/expander_pipeline.jl | 18 +++++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/src/documents.jl b/src/documents.jl
index cccd3d6be2..33e72ce035 100644
--- a/src/documents.jl
+++ b/src/documents.jl
@@ -96,6 +96,13 @@ struct IndexNode <: AbstractDocumenterBlock
             source  = error("missing value for `source` in `IndexNode`."),
             others...
         )
+        if !isempty(others)
+            @warn(
+                "In file $source: the following unsupported keyword " *
+                "arguments have been set in the `@index` node:\n" *
+                join([string(k, " = ", v) for (k, v) in others], "\n"),
+            )
+        end
         new(Pages, Modules, Order, build, source, [], codeblock)
     end
 end
@@ -121,6 +128,13 @@ struct ContentsNode <: AbstractDocumenterBlock
         if Depth isa Integer
             Depth = 1:Depth
         end
+        if !isempty(others)
+            @warn(
+                "In file $source: the following unsupported keyword " *
+                "arguments have been set in the `@contents` node:\n" *
+                join([string(k, " = ", v) for (k, v) in others], "\n"),
+            )
+        end
         new(Pages, first(Depth), last(Depth), build, source, [], codeblock)
     end
 end
diff --git a/src/expander_pipeline.jl b/src/expander_pipeline.jl
index 64adc5639a..ef4aca9ff5 100644
--- a/src/expander_pipeline.jl
+++ b/src/expander_pipeline.jl
@@ -289,7 +289,17 @@ function Selectors.runner(::Type{Expanders.MetaBlocks}, node, page, doc)
     lines = Documenter.find_block_in_file(x.code, page.source)
     @debug "Evaluating @meta block:\n$(x.code)"
     for (ex, str) in Documenter.parseblock(x.code, doc, page)
+        # If not `isassign`, this might be a comment, or any code that the user
+        # wants to hide. We should probably warn, but it is common enough that
+        # we will silently skip for now.
         if Documenter.isassign(ex)
+            if !(ex.args[1] in (:Currentmodule, :DocTestSetup, :DocTestFilters, :EditURL, :Description, :Draft))
+                source = Documenter.locrepr(page.source, lines)
+                @warn(
+                    "In $source: `@meta` block has an unsupported " *
+                    "keyword argument: $(ex.args[1])",
+                )
+            end
             try
                 meta[ex.args[1]] = Core.eval(Main, ex.args[2])
             catch err
@@ -460,8 +470,14 @@ function Selectors.runner(::Type{Expanders.AutoDocsBlocks}, node, page, doc)
             try
                 if ex.args[1] == :Filter
                     fields[ex.args[1]] = Core.eval(Main, ex.args[2])
-                else
+                elseif ex.args[1] in (:Modules, :Order, :Pages, :Public, :Private)
                     fields[ex.args[1]] = Core.eval(curmod, ex.args[2])
+                else
+                    source = Documenter.locrepr(page.source, lines)
+                    @warn(
+                        "In $source: `@autodocs` block has an unsupported " *
+                        "keyword argument: $(ex.args[1])",
+                    )
                 end
             catch err
                 @docerror(doc, :autodocs_block,

From 3c46a24d86f5cd742b93d2904ef89bc9e51fd5f6 Mon Sep 17 00:00:00 2001
From: Oscar Dowson <odow@users.noreply.github.com>
Date: Thu, 2 Nov 2023 15:09:51 +1300
Subject: [PATCH 2/3] Update index.md

---
 test/errors/src/index.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/test/errors/src/index.md b/test/errors/src/index.md
index 6ae6637458..65ab1642e2 100644
--- a/test/errors/src/index.md
+++ b/test/errors/src/index.md
@@ -9,10 +9,12 @@ parse error
 
 ```@meta
 CurrentModule = NonExistentModule
+draft = true  # invalid keyword
 ```
 
 ```@autodocs
 Modules = [NonExistentModule]
+pages = []  # invalid keyword
 ```
 
 ```@eval
@@ -23,6 +25,14 @@ NonExistentModule
 # comment in a @docs block
 ```
 
+```@index
+foo = 1
+```
+
+```@contents
+foo = 1
+```
+
 [`foo(x::Foo)`](@ref) creates an [`UndefVarError`](@ref) when `eval`d
 for the type signature, since `Foo` is not defined.
 

From bb68e7cf76de5a2359be04988db843875fccbc95 Mon Sep 17 00:00:00 2001
From: Morten Piibeleht <morten.piibeleht@gmail.com>
Date: Wed, 8 Nov 2023 13:48:16 +1300
Subject: [PATCH 3/3] Update CHANGELOG.md

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6703507eaf..b3e74912fd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 * `id` anchors may now start with a numeric digit. ([#744]), ([#2325])
+* Documenter now warns when it encounters invalid keys in the various key-value at-blocks. ([#2306], [#2324])
 
 ### Fixed