diff --git a/docs/src/man/guide.md b/docs/src/man/guide.md index 1c87119825..4437573f84 100644 --- a/docs/src/man/guide.md +++ b/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 ``` ```` diff --git a/docs/src/man/syntax.md b/docs/src/man/syntax.md index c3d864d162..c4f66f0db7 100644 --- a/docs/src/man/syntax.md +++ b/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 diff --git a/src/Documents.jl b/src/Documents.jl index 02fb86e27e..29d78a1484 100644 --- a/src/Documents.jl +++ b/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 diff --git a/src/Expanders.jl b/src/Expanders.jl index c1b83a6a48..3a79c24591 100644 --- a/src/Expanders.jl +++ b/src/Expanders.jl @@ -158,7 +158,7 @@ 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 @@ -166,7 +166,7 @@ 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 diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index 85b465aeaf..d0b56daabc 100644 --- a/src/Writers/HTMLWriter.jl +++ b/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) diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl index f543ea62d4..46943b9289 100644 --- a/src/Writers/LaTeXWriter.jl +++ b/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) diff --git a/src/Writers/MarkdownWriter.jl b/src/Writers/MarkdownWriter.jl index ddc930cc6f..16ae468c61 100644 --- a/src/Writers/MarkdownWriter.jl +++ b/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) diff --git a/test/examples/src/index.md b/test/examples/src/index.md index 0bb619e572..1f1cae81c7 100644 --- a/test/examples/src/index.md +++ b/test/examples/src/index.md @@ -4,7 +4,7 @@ ```@contents Pages = ["index.md"] -Depth = 5 +Depth = 2:5 ``` ## Functions Contents