Draft
Conversation
Implements a new `top_menu` keyword argument for `makedocs` that enables upper-level organization of documentation with a horizontal navigation bar at the top of the page. ## New Features - **`top_menu` keyword**: Accepts a vector of section pairs, where each section has a title and a nested page structure identical to the `pages` argument format - **Section-based navigation**: Each section maintains its own navigation tree in the sidebar, switching automatically when clicking between sections - **Theme-aware styling**: Top menu bar uses sidebar theme variables for consistent appearance across all themes (light, dark, catppuccin variants) ## Implementation Details - Added `TopMenuSection` struct in documents.jl to hold section metadata - Extended `walk_navpages` to support section-specific navlist population - Added `render_top_menu` and helper functions in HTMLWriter.jl - Created new SCSS styles in _topmenu.scss with responsive mobile support - Active section highlighted with bottom border indicator ## Documentation & Tests - Added comprehensive documentation in makedocs.jl keyword docs - Added user guide section in docs/src/man/guide.md - Added unit tests for TopMenuSection and walk_navpages - Added example build in test/examples with multi-section structure ## Behavior Notes - First section in top_menu determines the landing page - Pages should be unique across sections (warns on duplicates) - Fully backward compatible - existing docs without top_menu unchanged
- Verify top_menu_sections are created correctly - Verify section titles and navlists - Verify first_page is set for each section - Verify HTML files are generated in correct locations - Verify redirect index.html is generated at root - Verify top menu elements appear in generated HTML - Verify has-top-menu class is applied
Use joinpath for cross-platform path comparison in first_page assertions
Author
|
INFO: I generates this page correctly (local test here), with and without the https://m3g.github.io/ComplexMixtures.jl/stable/ And the PDF output is generated equally with both options. |
Author
|
This is another page using the feature: https://m3g.github.io/PDBTools.jl/dev/ Where the configuration was just adding a line to |
6 tasks
mortenpi
reviewed
Apr 17, 2026
Member
mortenpi
left a comment
mortenpi
left a comment
There was a problem hiding this comment.
First, sorry for not getting back to this earlier. But I think this would need a bit of iteration. Right now, I couldn't actually get it to work. But I'd be happy to help shepherd this through.
I do also have few concerns around the high-level choices, so I left some comments for those. I did not dig into the front-end part yet, since I'd like to see it build first.
mortenpi
added
Format: HTML
Done — top_menu is now a keyword argument of HTML (e.g. format = HTML(top_menu = true)) and has been removed from makedocs. The documentation and the example in test/examples/make.jl have been updated accordingly. 2. Removing top_menu logic from the builder pipeline Done — the builder pipeline now always follows the original code path, with no awareness of top_menu. TopMenuSection was moved to HTMLWriter.jl, and a build_top_menu_sections function derives the per-section navtrees and navlists directly from the already-built global doc.internal.navtree at render time. The navlist keyword argument that had been added to walk_navpages was also removed. 3. Removing the redirect index.html Done — the redirect generation has been removed entirely. The file structure is now unchanged when top_menu is enabled; the top bar is purely a per-page HTML addition. The landing page warning was also restored to its original unconditional form, and the redirect-related test assertions were dropped. 4. Accessing top_menu via ctx in render_html Done — the top_menu keyword argument has been removed from render_html. The function now takes navnode as a positional argument and calls render_top_menu(ctx, navnode) internally, so the top menu is derived from ctx rather than passed in from the call site.
Author
|
Incorporated the changes suggested above. I'm still testing and fixing bugs. |
github-actions
bot
added
Status: Waiting for Review
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
3 participants
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.
This is a variation of #2866 where instead of adding a
top_menuvector that replaces thepagesvector, atop_menu=trueoption is added to
makedocs, which will interpret the first layer of the documentation menu as the top menu.if
top_menu=falsethe common (current - no top-menu) behavior is preserved.This is a nice alternative for the interface, indeed.
@mortenpi