[BUGFIX] Keep navigation menu in toctree order with external links#1291
Open
CybotTM wants to merge 1 commit into
Open
[BUGFIX] Keep navigation menu in toctree order with external links#1291CybotTM wants to merge 1 commit into
CybotTM wants to merge 1 commit into
Conversation
CybotTM
force-pushed
the
fix/issue-1175-menu-toctree-order
branch
2 times, most recently
from
80a6384 to
64824a6
Compare
Contributor
Author
|
looking into failing CI ... |
CybotTM
force-pushed
the
fix/issue-1175-menu-toctree-order
branch
3 times, most recently
from
a025887 to
9a35cc8
Compare
A toctree that mixes internal pages and external links rendered the navigation menu (sidebar) with all external links grouped at the top, while the on-page toctree kept the authored order. The guides compiler attaches a document's menu entries via separate transformers for internal and external entries, each running in its own full tree traversal, so the document entry's menu entries end up grouped by type instead of following the toctree. The sidebar, built from those menu entries, then disagreed with the page. Add a compiler pass that realigns the menu entries of each (non-glob) toctree with the authored order, emitting each toctree's entries as a contiguous block at the position of its first entry so a document with several mixed toctrees is also handled. This is a downstream workaround that can be dropped once the fix lands upstream in phpdocumentor/guides. Resolves: TYPO3-Documentation#1175 Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
CybotTM
force-pushed
the
fix/issue-1175-menu-toctree-order
branch
from
9a35cc8 to
b253a66
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.
Fixes #1175
Problem
When a
toctreemixes internal pages and external links (e.g. interlinks to other manuals), the sidebar navigation renders all external entries grouped at the top, even though the on-pagetoctreekeeps the authored order. On the reported page (reference-coreapi→ Fluid) the sidebar showsFluid SyntaxandViewHelper reference(both external) above the internal pages.Root cause
The guides compiler attaches a document's menu entries via separate transformers for internal and external entries (
InternalMenuEntryNodeTransformer/ExternalMenuEntryNodeTransformer), and the compiler runs one full tree traversal per transformer at each priority. So every external entry is attached to the document's menu-entry list in one pass and every internal entry in another — the list ends up grouped by type instead of following the authored toctree. The on-page toctree renders from theTocNode(authored order) and stays correct; the sidebar renders fromDocumentEntryNode::getMenuEntries()and does not.This is an engine-level issue in
phpdocumentor/guides. The proper fix belongs upstream (phpDocumentor/guides#1344); this PR adds a downstream compiler pass so docs.typo3.org is fixed now, and it can be removed after a futureguidesbump.Fix
SortMenuEntriesByToctreeTransformerrealigns each document's menu entries with the authored order of itstoctrees, 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. Globbed toctrees are skipped (their order comes from the glob expansion, which the sitemap relies on).Before / after
Sidebar of a subpage whose toctree mixes internal pages with two external links:
Before
After
Verification
tests-full/menu-external-order(one nested mixed toctree) andtests-full/menu-multiple-toctrees-order(two mixed toctrees on one page). Each passes with the fix and fails without it.external-menu,two-toctrees,menu-subpages,sitemap(glob) andmain-menu-jsonare unaffected.