Skip to content

feat(render): book-style page-numbered [TOC] via BookTocRenderer#41

Merged
DemchaAV merged 2 commits into
developfrom
feat/book-toc
Jul 1, 2026
Merged

feat(render): book-style page-numbered [TOC] via BookTocRenderer#41
DemchaAV merged 2 commits into
developfrom
feat/book-toc

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Jul 1, 2026

Copy link
Copy Markdown
Owner

Stacked on #40#39 — merge order: #39 (split) → #40 (footnote fix) → this.

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.9 addTableOfContents/TocBuilder resolves 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")) — zero
    new 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
    GoTo jumps; empty/no-heading documents degrade exactly like the default TocRenderer, which
    remains the default.
  • Runnable BookTocExample (paired with the page-number footer — the classic report look);
    README snippet + CHANGELOG.

Verification

./mvnw clean verify javadoc:javadocBUILD 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.

@DemchaAV

DemchaAV commented Jul 1, 2026

Copy link
Copy Markdown
Owner Author

Blind cold review verdict: approve with follow-ups — both landed in 7daa835: (1) the nesting-indent path is now covered (h2 indent asserted positionally — PDFBox extracts the NBSP indent as leading blanks — plus h2-only minLevel normalization and the page number tied to its own entry's line); (2) class Javadoc says non-breaking spaces. The label re-parse edge (engine markdown=true re-parses TocBuilder plain-text labels; # Rating \*hot\* would italicize in the book TOC) is recorded as a tracked audit in the private roadmap — a session-wide markdown(false) decision is deliberately its own PR since several p.text(...) sites share the latent surface. Suite green: 171 on this branch, 175 at the top of the stack (#42 rebased).

@DemchaAV DemchaAV force-pushed the fix/footnote-table-backanchor branch from f2def42 to 1b8048b Compare July 1, 2026 22:40
@DemchaAV DemchaAV changed the base branch from fix/footnote-table-backanchor to develop July 1, 2026 22:42
DemchaAV added 2 commits July 1, 2026 23:44
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).
@DemchaAV DemchaAV merged commit 6d54ebb into develop Jul 1, 2026
4 checks passed
@DemchaAV DemchaAV deleted the feat/book-toc branch July 2, 2026 05:26
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