feat(render): book-style page-numbered [TOC] via BookTocRenderer#41
Merged
Conversation
Owner
Author
|
Blind cold review verdict: approve with follow-ups — both landed in |
f2def42 to
1b8048b
Compare
An opt-in alternative to the default [TOC] link list: swapping the TocNode renderer (MarkdownTheme.builder(base).renderer(TocNode.class, new BookTocRenderer("Contents"))) renders the marker as dot-leader contents rows with page numbers resolved automatically from the laid-out document — the engine's addTableOfContents/TocBuilder does the second layout pass; the library only feeds label+anchor pairs from the planned heading slugs. Labels indent by heading level with non-breaking spaces (the code-block idiom — plain leading spaces are collapsed by text layout and base-14 fonts carry no em-space glyph); optional title row; entries stay clickable GoTo jumps; empty/no-heading documents degrade exactly like the default renderer. Tests: resolved page number printed on the digit-free contents page + clickable entries; no-heading no-op. Runnable BookTocExample (paired with the page-number footer). Suite green (169).
From the blind cold review of BookTocRenderer: (1) the nesting-indent path had zero coverage — new tests assert an h2 entry carries a leading indent while h1 entries start at the line start (PDFBox extracts the NBSP indent as plain leading blanks), an h2-only document is not indented (minLevel normalization), and the resolved page number sits on its own entry's line; (2) class Javadoc now says non-breaking spaces. The label re-parse edge (engine markdown=true re-parses TocBuilder plain-text labels) is recorded as a tracked audit in the private roadmap — a session-wide markdown(false) decision is its own PR. Suite green (171).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Tier 2 flagship of the post-0.2.0 roadmap: the
[TOC]link list is right for screen, but a print deliverable wants a real contents page — dot leaders and page numbers. The engine's 1.9addTableOfContents/TocBuilderresolves page numbers automatically (second layout pass); the library only had to feed it label+anchor pairs it already plans.What changed
BookTocRenderer(new public renderer): opt in via the theme's own extension seam —MarkdownTheme.builder(base).renderer(TocNode.class, new BookTocRenderer("Contents"))— zeronew tokens/flags. Dot leaders + muted page numbers + optional title row; labels indent by
heading level using non-breaking spaces (the code-block idiom; plain leading spaces are
collapsed by text layout and base-14 fonts have no em-space glyph). Entries stay clickable
GoTojumps; empty/no-heading documents degrade exactly like the defaultTocRenderer, whichremains the default.
BookTocExample(paired with the page-number footer — the classic report look);README snippet + CHANGELOG.
Verification
./mvnw clean verify javadoc:javadoc→ BUILD SUCCESS, 169 tests, 0 failures.BookTocTest:a digit-free multi-page document proves the resolved page number is printed on the contents
page and entries emit
GoTo; a no-heading[TOC]renders nothing. Visually confirmed:"Contents" + Introduction/Getting started/Configuration (indented)/Appendix with dot leaders and
live page numbers 1/2/2/3.