Skip to content

feat: --toc-depth takes a level range like 2-6 - #12

Merged
ralsina merged 1 commit into
mainfrom
feat/toc-depth-range
Sep 8, 2026
Merged

ralsina merged 1 commit into
mainfrom
feat/toc-depth-range

Conversation

@ralsina

@ralsina ralsina commented Sep 8, 2026

Copy link
Copy Markdown
Owner

What

--toc-depth now also accepts a range: N keeps its meaning (levels 1..N), while N-M lists only levels N through M, inclusive.

  • --toc --toc-depth 2-6 — everything except a level-1 document title: the usual markdown book (H1 = title, H2 = chapters) gets a real TOC by default shape instead of a single self-referential entry
  • --toc --toc-depth 2-2 — chapter titles alone
  • --toc --toc-depth 2-3 — chapters and their sections, title skipped

Validation is strict: integers 1..6, N ≤ M, and only the forms N or N-M (3-2, 2-7, 0-2, 2-, soon, 2-2-2 all abort with a usage message on stderr). No silent clamping.

Semantics

  • The window filters the TOC listing only — PDF bookmarks/outline keep every heading (a top-level title bookmark is conventional and useful), and the mtoc-N anchor numbering stays aligned because the filter lives in toc_html, not in the heading map.
  • The two-pass settle loop is untouched: it already rebuilds the TOC block each pass, and a smaller listing just settles like a smaller document.
  • warn_missing_toc learned the range vocabulary: "--toc found no headings at depth 2-6" (lone N still reads "at depth N").

Library

Additive kwarg toc_min_level : Int32 = 1 on Markd::Pdf.render and render_to_memory; settled_pages takes it as a defaulted parameter before the block, so existing callers compile unchanged.

Docs

Help text and the README docopt block were updated together and verified byte-identical to the actual --help output; the README TOC section documents the range form with the title-skip idiom.

Verification

  • 4 new specs in spec/pdf_toc_spec.cr: window filtering (including the "only level 2" case), nil when everything falls outside the window, a real two-pass render of a title+chapters+sections book at toc_depth: 3, toc_min_level: 2 asserting the title stays out while every listed number matches the heading's true page, and a CLI spec covering 2-6 plus six rejected malformed values
  • Full suite: 257 examples, 0 failures (1 pre-existing pending); ameba 0 failures; all four binaries build (fresh worktree: submodules + shim + shards build)
  • Smoke-tested: 2-6 and 2-2 renders, --print-config dumping toc_depth: 2-3, config-file roundtrip (toc-depth: 2-4 read back), kdp + range with recto numbering, both warning paths, and the usage errors above

A lone N still means levels 1..N. A range N-M lists only levels N
through M, inclusive — so 2-6 keeps everything except a level-1
document title, and 2-2 is level 2 alone. The window filters the
TOC listing only; bookmarks keep every heading, and the settle loop
needs no changes because the filter lives in toc_html.

The library grows an additive toc_min_level kwarg on render and
render_to_memory.
@ralsina
ralsina merged commit 21cd3d1 into main Sep 8, 2026
2 checks passed
@ralsina
ralsina deleted the feat/toc-depth-range branch September 8, 2026 14:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant