Feature Request: TOC Stop Depth and Start Depth #5676
Comments
|
Why would you want to include heading levels 2-4 but not 1? |
|
I have a blog series where the H1 is the blog title and H2/H3 are the main headings. The menu at the top of the blog extracts the main heading levels 2 through 3 because the title isn't part of the "contents" per se. (It would be like putting the cover title for a book inside the table of contents.)
|
|
Pandoc really wants you to use the You could write a fairly simple lua filter to match on a level 1 header, populate the title in metadata with its contents, and remove it, while demoting other headers by 1 level. |
|
See also #5615, which I think is a cleaner solution than making TOC start depth configurable. |
That is a useful default. In this use case, I'm using fmpp (a FreeMarker template engine preprocessor) to convert a document template to a static HTML document, where the body of the template is created using pandoc, which converts Markdown to an HTML fragment that's included by fmpp: <#ftl encoding="UTF-8">
<#assign updated = .now>
<!doctype html>
<html lang="en">
<head>
<title>Markdown Typesetting with Pandoc and ConTeXt Blog Series</title>
<style>
<#include "includes/css/main.min.css">
<#if resource?starts_with( "blog" )>
<!-- ... -->
<#if>
</head>
<!-- ... body, main, and other elements ... -->
<#include "includes/html/body.html" parse=false encoding="UTF-8">
<!-- ... article, footer, and end of body/html ... -->And have a function, loops over "index.md" files, to convert Markdown into HTML: convert_markdown() {
local -r FILE_HTML="$INC_DIR/html/body.html"
local -r FILE_TOC="$INC_DIR/html/toc.html"
local -r XPATH="//html/body/nav/ul/*/ul"
if [[ "${PWD}" == *blog* ]]; then
echo "<nav class='toc'>" > "${FILE_TOC}"
pandoc -s --toc "$1" 2> /dev/null | \
xmllint --html --xpath "${XPATH}" - 2> /dev/null >> "${FILE_TOC}"
echo "</nav" >> "${FILE_TOC}"
fi
pandoc "$1" \
-f markdown-tex_math_dollars-raw_tex-auto_identifiers+auto_identifiers \
-o "$FILE_HTML"
}There's little functional difference between the echo statements above and the suggestion in #5675 to externalize the TOC to a file. In both cases users still must code convert_markdown() {
pandoc "$1" \
--toc --toc-depth-start=2 \
-f markdown-tex_math_dollars-raw_tex-auto_identifiers+auto_identifiers \
-o "$INC_DIR/html/body.html"
}This would also eliminate the warning that a page title is needed because standalone mode would no longer be necessary (to generate the TOC, external template notwithstanding). A lua filter is a great idea. I find they often take much more time to write than a couple post-processing calls with command-line tools and result in external files (that then need to be referenced correctly w.r.t. their location). These two lines, sandwiching a pandoc call, for example, strip out the first heading level: local -r XPATH="//html/body/nav/ul/*/ul"
xmllint --html --xpath "${XPATH}" - >> "${FILE_TOC}"It works, but a start and end depth would be cleaner. |
|
Using a custom template to generate the TOC (as I suggested in the other issue) would be cleaner than what you're doing. And using a lua filter as suggested above would be cleaner than using xmllint. This would also give you "no external dependencies", since you don't need to have a lua interpreter to use lua filters. Anyway, I don't like to multiply our already plentiful command-line options without strong reasons, and in this case I don't see a strong reason other than what might be handled by #5615. |
Pandoc supports
--toc-depth=NUMBERto limit the number of sections included in the table of contents. As a variation, consider:This would include heading levels 2 through 4 in the table of contents, inclusive, omitting heading levels 1 and 5 and up. This suggests that
--toc-depthcan be aliased to--toc-depth-stopand the default value for--toc-depth-startwould be 1.The text was updated successfully, but these errors were encountered: