Keep navigation menu in toctree order when mixing internal and external entries#1344
Open
CybotTM wants to merge 1 commit into
Open
Keep navigation menu in toctree order when mixing internal and external entries#1344CybotTM wants to merge 1 commit into
CybotTM wants to merge 1 commit into
Conversation
CybotTM
force-pushed
the
fix/menu-toctree-external-order
branch
from
80f7e7f to
6358e65
Compare
CybotTM
force-pushed
the
fix/menu-toctree-external-order
branch
from
6358e65 to
c45ea55
Compare
…al entries A toctree that mixes internal pages and external links built the navigation menu (the document entry's menu entries) with all external entries grouped first, even though the on-page toctree kept the authored order. The sidebar/navbar therefore disagreed with the page; this was visible for nested toctrees. Internal and external menu entries are attached to the document entry by two separate transformers (InternalMenuEntryNodeTransformer and ExternalMenuEntryNodeTransformer), and the compiler runs one full tree traversal per transformer, so every external entry is appended in one pass and every internal entry in another. The result is grouped by type instead of following the toctree. ToctreeSortingTransformer now realigns the document entry's menu entries with the authored toctree order, emitting each toctree's entries as a contiguous block at the position of its first entry. Applied per toctree in document order, this also yields the correct order when a document has several mixed toctrees. It already ran at the right point to handle the reversed option; globbed toctrees are skipped, since their order comes from the glob expansion rather than an authored sequence. Reported downstream at TYPO3-Documentation/render-guides#1175
CybotTM
force-pushed
the
fix/menu-toctree-external-order
branch
from
c45ea55 to
c4fba4f
Compare
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
1 participant
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.
Problem
A
toctreethat mixes internal pages and external links builds the navigation menu (the document entry's menu entries, used for the sidebar/navbar) with all external entries grouped first, even though the on-pagetoctreekeeps the authored order. The navigation therefore disagrees with the page. It shows up for nested toctrees.Root cause
Internal and external menu entries are attached to the document entry by two separate transformers —
InternalMenuEntryNodeTransformerandExternalMenuEntryNodeTransformer— and the compiler runs one full tree traversal per transformer at a given priority (both attach at 4500). So every external entry is appended toDocumentEntryNode::getMenuEntries()in one pass and every internal entry in another, and the list ends up grouped by type instead of following the toctree. The on-page toctree renders from theTocNodevalue (authored order) and stays correct.Fix
ToctreeSortingTransformer(priority 3200, after the attach passes) now realigns the document entry's menu entries with the authored toctree order, matching entries by file/URL. It emits each toctree's entries as one contiguous block at the position of its first entry, so a document with several mixed toctrees is ordered correctly too. It already ran at the right point to handle thereversedoption, and globbed toctrees are skipped — their order comes from the glob expansion, not an authored sequence.Before / after
Sidebar of a nested subpage whose toctree interleaves internal pages and external links (Bootstrap theme):
Before
After
Tests
Two integration fixtures:
tests-full/bootstrap/bootstrap-menu-nested-external-order(one nested mixed toctree) andtests-full/bootstrap/bootstrap-menu-multiple-toctrees-order(two mixed toctrees on one page). Each passes with the fix and fails without it.Verified locally: integration (229), unit (481) and functional (117) suites pass; PHPStan (level max + baseline), PHPCS (Doctrine standard) and deptrac all clean.
Context
Reported downstream at TYPO3-Documentation/render-guides#1175.