Allow at-contents to take Depth as a UnitRange

docs/src/man/guide.md

@@ -330,7 +330,7 @@ document, but this can be adjusted using `Pages` and `Depth` settings as in the
 ````markdown
 ```@contents
 Pages = ["foo.md", "bar.md"]
-Depth = 3
+Depth = 1:3
 ```
 ````
 

docs/src/man/syntax.md

@@ -291,16 +291,18 @@ expected by the user. Try to stick to array literals as much as possible.
 ## `@contents` block
 
 Generates a nested list of links to document sections. Valid settings are `Pages` and `Depth`.
+Note that `Depth` can be either an `Int` (parsed as `1:Depth`) or a `UnitRange{Int}`,
+specifying the starting and ending depth to include in the generated contents.
 
 ````markdown
 ```@contents
 Pages = ["foo.md"]
-Depth = 5
+Depth = 1:5
 ```
 ````
 
 As with `@index` if `Pages` is not provided then all pages are included. The default
-`Depth` value is `2`.
+`Depth` value is `1:2`.
 
 ## `@example` block
 

src/Documents.jl

@@ -113,22 +113,27 @@ end
 
 struct ContentsNode
     pages       :: Vector{String} # Which pages should be included in contents? Set by user.
-    depth       :: Int            # Down to which level should headers be displayed? Set by user.
+    depthrange  :: UnitRange{Int} # Down to which level should headers be displayed? Set by user.
     build       :: String         # Same as for `IndexNode`s.
     source      :: String         # Same as for `IndexNode`s.
     elements    :: Vector         # (order, page, anchor)-tuple for constructing links.
 
     function ContentsNode(;
             Pages  = [],
-            Depth  = 2,
+            Depth  = 1:2,
             build  = error("missing value for `build` in `ContentsNode`."),
             source = error("missing value for `source` in `ContentsNode`."),
             others...
         )
+        if Depth isa Int
+            Depth = 1:Depth
+        end
         new(Pages, Depth, build, source, [])
     end
 end
 
+contents_header_level_offset(contents) = first(contents.depthrange) - 1
+
 ## Other nodes
 
 struct MetaNode
@@ -422,7 +427,7 @@ function populate!(contents::ContentsNode, document::Document)
         for (file, anchors) in filedict
             for anchor in anchors
                 page = relpath(anchor.file, dirname(contents.build))
-                if _isvalid(page, contents.pages) && Utilities.header_level(anchor.object) ≤ contents.depth
+                if _isvalid(page, contents.pages) && Utilities.header_level(anchor.object) in contents.depthrange
                     push!(contents.elements, (anchor.order, page, anchor))
                 end
             end

src/Expanders.jl

@@ -158,15 +158,15 @@ abstract type IndexBlocks <: ExpanderPipeline end
 """
 Parses each code block where the language is `@contents` and replaces it with a nested list
 of all `Header` nodes in the generated document. The pages and depth of the list can be set
-using `Pages = [...]` and `Depth = N` where `N` is and integer.
+using `Pages = [...]` and `Depth = N` where `N` is either an Int or a `UnitRange{Int}`.
 
 ````markdown
 ```@contents
 Pages = ["foo.md", "bar.md"]
 Depth = 1
 ```
 ````
-The default `Depth` value is `2`.
+The default `Depth` value is `1:2`.
 """
 abstract type ContentsBlocks <: ExpanderPipeline end
 

src/Writers/HTMLWriter.jl

@@ -1238,7 +1238,7 @@ function domify(ctx, navnode, contents::Documents.ContentsNode)
         header = anchor.object
         url = string(path, '#', anchor.id, '-', anchor.nth)
         node = a[:href=>url](mdconvert(header.text; droplinks=true))
-        level = Utilities.header_level(header)
+        level = Utilities.header_level(header) - contents_header_level_offset(contents)
         push!(lb, level, node)
     end
     domify(lb)

src/Writers/LaTeXWriter.jl

@@ -315,7 +315,7 @@ function latex(io::IO, contents::Documents.ContentsNode, page, doc)
     _println(io, "\\begin{itemize}")
     for (count, path, anchor) in contents.elements
         header = anchor.object
-        level = Utilities.header_level(header)
+        level = Utilities.header_level(header) - contents_header_level_offset(contents)
         id = string(hash(string(anchor.id, "-", anchor.nth)))
         level < depth && (_println(io, "\\end{itemize}"); needs_end = false)
         level > depth && (_println(io, "\\begin{itemize}"); needs_end = true)

src/Writers/MarkdownWriter.jl

@@ -127,7 +127,7 @@ function render(io::IO, ::MIME"text/plain", contents::Documents.ContentsNode, pa
         header = anchor.object
         url    = string(path, '#', anchor.id, '-', anchor.nth)
         link   = MarkdownStdlib.Link(header.text, url)
-        level  = Utilities.header_level(header)
+        level = Utilities.header_level(header) - contents_header_level_offset(contents)
         print(io, "    "^(level - 1), "- ")
         MarkdownStdlib.plaininline(io, link)
         println(io)

test/examples/src/index.md

@@ -4,7 +4,7 @@
 
 ```@contents
 Pages = ["index.md"]
-Depth = 5
+Depth = 2:5
 ```
 
 ## Functions Contents