Wild experiment for better navigation

[gsmet]

This is definitely not final and will require some discussions with James and some iterations but it allows showing a bit what would be possible with this new category index.

I haven't adjusted the search at all and also the appearance of the guides is coming from search.quarkus.io and I haven't tweaked it. I would favor a layout that is a bit more compact, ideally, but that's something to tweak later.

All of this is visible if you go to: https://quarkus-website-pr-2749-preview.surge.sh/version/main/guides/ (main version).
Here are a couple of screenshots/pointers.

Guides sorted by categories and category index

The index page is now sorted properly, by category and with a proper order in each category.

There are subcategories in some categories and a category can have a description to have a proper introduction.

Menu to switch to other guides

When on a guide, you can easily switch to another guide in the same category, or use the menu to get to something else entirely.

For instance here: https://quarkus-website-pr-2749-preview.surge.sh/version/main/guides/writing-native-applications-tips

Switch easily to same category/topic

We display both the category(ies) and the topic(s) and you can easily switch to the other items in the category/topic.

For instance here: https://quarkus-website-pr-2749-preview.surge.sh/version/main/guides/writing-native-applications-tips

[github-actions]

🎊 PR Preview fca8f1e has been successfully built and deployed to https://quarkus-website-pr-2749-preview.surge.sh

• Images of blog posts older than 3 months are not available.
• Newsletters older than 3 months are not available.

[holly-cummins]

Can you screencap what it's supposed to look like? I couldn't see any difference on the /guides page in your preview. But I think surge is serving stale content (in general), so I don't know if that affected this PR, or if I was just looking wrong.

[gsmet]

Ah ah, yeah, I was going to do exactly that, that's why I visited the PR :).

[gsmet]

@holly-cummins done! Look and feel is so-so, we can definitely improve it with the help of @insectengine I just wanted to give an idea of what we could achieve.

[gsmet]

/cc @rolfedh FYI as we discussed a loooooong time ago. It's the companion PR of: quarkusio/quarkus#54877

[holly-cummins]

I think organising by categories rather than diataxis classification is definitely an improvement. Nice!

On the actual drilled-down pages, I really like showing both the position on the broader category taxonomy and the ToC for the current content (which is obviously needed). I'm less sure about having one on the left and one on the right. It's not immediately obvious which is which, and it means there's not much whitespace on the page. Maybe the ToC could be embedded in the bigger navigation, but with a grey background so it's clear it's different?

I'd also like to see us switch to cute cards with shadows and drop the 'type' icon, which is visual noise and impossible to decode (let's replace it with a lozenge saying 'tutorial' or 'reference' or whatever on the card). But that's orthogonal! I only mention it here because I was thinking of it when looking at the new pages.

[holly-cummins]

I haven't adjusted the search at all and also the appearance of the guides is coming from search.quarkus.io and I haven't tweaked it. I would favor a layout that is a bit more compact, ideally, but that's something to tweak later.

Orthogonal, but this is also something we should fix, IMO. Our styling shouldn't be spread between this repo and the search.quarkus.io repo. Search should either return data, which we can then render appropriately (but which would need some js), or it could return minimal divs with classes and we own the styling of those classes. I have a feeling the second might be what we actually currently have, in which case we'd be able to adjust the styling of what comes back from search, but I haven't looked.

[insectengine]

I like where this is going but I agree with Holly on combining the categories and the TOC on the left. This would allow users to not only jump between guides but to also drill down into a guide from the left subnav.

A few problems I see off hand:

1. Why have a different styling between the guides main and guides detail pages? A singular representation would work best here. The lozenges/buttons on the guides index are very problematic visually. The feel like tags more than anything else. This could be fixed by using a common left subnav that's used in the guides detail.

2. The lozenge on guide detail pages isn't necessary and is distracting. It duplicates navigation on the left subnav and just adds to the clutter. I'd say it gets removed.

3. Let's kill the _blank on the index page. We shouldn't span a new page every time a person selects a guide to view... it just fills their browser window with a ton of tabs.

I think we're at the stage of perhaps just mocking up in photoshop this page for styling to finalize the layout before just doing code changes in order to save time.

[insectengine]

Guides Detail page

1. Combine the left sub nav with the guide TOC to make a unified navigation. Use the Chevron for category indicator then consistent indents to show sub pages. The selected guide is giving a selected color to show it's active. The TOC can also have simple lines above and below to visually group the contents. This simple approach avoids extra background colors/greys so light/dark versions would be super simple. This guide example uses numbers (preferred) but other guides don't. I can imagine fixing this inconsistency would be a larger task.

2. I fixed the width to match the width of the main header for consistency.

3. I moved the "edit this page" to the right since the old TOC is no longer in the page. This gives access but clears it out of the important visual zone.

4. This solution is for desktop views but for mobile we could just turn it off off (like we do now)..

[insectengine]

Guides Main Page mockup

1. I've applied a variation of the Left Subnav to the main page
2. I followed our current pattern for the layout of the guides but I removed the icons as requested (since we're not using the diataxis)
3. I put the section descriptor with the section title (above the line) and removed the lines below the individual guide descriptions. Basically, I followed our current layout except I added the subcategories inline in order to keep it visually cleaner and simple.
4. I didn't mock all of the content as it would be overkill. This mock shows how all the elements would work and the general spacing of the content.

[gsmet]

Thanks for your feedback.

On what you raised:

• The simple one: yes, we should reduce the space we waste when displaying the list of guides, and yes I agree that having the search UI handled on search.quarkus.io is not ideal
• for the left/right TOC, I'm not sure it's a good idea to merge both, the inner TOC can be quite long, mixing it with the categories, I don't know. ALSO, VERY IMPORTANT: my plan was to have the left TOC with the categories to not be displayed by default, and have a nice vertical Navigation button on the left to slide the left TOC as an overlay. I asked Claude nicely and the result was not working very well so I gave up on this. But I think we should go this way rather than trying to mix two things that are not really related and end up with a gigantic TOC on the left.
• as for the UI being different between the Guides page and the Guide page. There is a reason. I agree they could be made more consistent but on the Guides page, I want people to easily have an overview of what we offer as content categories, thus why it's not a full tree because the full tree takes far too much space and is less readable when you want to explore. On the Guide page, I want to also display the guides, which made it a bit impractical to use a similar UI. Given my plan was to not display the navigation tree by default on the Guide page, I wasn't too worried about consistency. FWIW, the mockups of @rolfedh perfectly illustrates the problem with the TOC as a full tree on the Guides page: it's far too long and only works if you have a gigantic vertical screen. I want people to be able to explore easily, it's important.

I'm not saying we should go with this particular UI, I totally agree it can be improved but there are reasons behind what is presented here, it wasn't just random mockups :).

Now we can discuss things and I'm open to suggestions for sure but we probably need to agree on what we want to do before generating new mockups.

Maybe we could think about it for a couple of days and then have a live discussion about it? What do you all think?

[insectengine]

Thanks for the clarification on the intent since the working prototype didn't fully function as intended. I now have a better understanding of what's being done.

OK... for clarity, lets call the main index list page "Index" and the individual guides pages "Detail page".

Index page
For Categories, we're currently using a pulldown in the blue bar with the version and keyword search. This could be moved to the left and full time visible/discoverable for users. Moving it and making it a multi select check box list would allow users to see all the options and then narrow down the guides list to just those which they are interested. Clear all would bring back the full guide list.

This pattern is already in use on the Extensions catalog on the site so it's a consistent experience: https://quarkus.io/extensions/?categories=scheduler%2Cbinding%2Cpostgres

For clarification... there currently are two levels to the categories on some. Does the current design account for all of the sub categories or are some not being used?

Detail page
I can see having a guides navigation tray on the left side that's closed by default. This would allow the user to access other guys easily from the current page (not having to go back to the Index). This could be very helpful. We could move the existing TOC to the left column. The Categories Tray would overall the TOC when selected. In this case, the user is doing two separate tasks, either looking at the list of other guides with the category tray or looking to jump to another section of the current guide via the TOC.

I'd also remove the button/tag thing that short cuts to other sections in the same category. It's just visual clutter and it duplicates the Category tray function.

Caveat: All of this should only be visible on the deskop view and turned off for mobile. The vast majority of our traffic comes through desktop. Not sure there is value in spending time (or tokens) trying to adapt a more complex navigation structure to the mobile views.

I don't mind spending time to mock these up in photoshop for further discussion.

I'm also good with doing a live discussion too.

[insectengine]

I decided to mock up the Index and Detail pages to visualize what I was proposing.

Index Page with multi select filtering for discovery

Detail Page with Category Tray closed by default

Detail Page with Category Tray opened after click on bar

[gsmet]

I very much like what you did with the menu on the Guide page, that's very much what I had in mind!

I'm less enthusiastic about the index page for multiple reasons:

• For now this page is not loaded by the search engine when you're not actively searching for something (we might do it in the future but for now it's not the case). I'm also not convinced searching multiple categories makes sense but that's a discussion for the future if we end up connecting this to the search engine.
• So atm it's just anchors and I'd very much prefer this first version to be just that - but I agree we should think about the search engine filtering for later as I think it's going to be something we want. I kinda like my compact version better. My main issue with yours and @rolfedh 's is that it looks fine when you post a gigantic screenshot but on an actual screen, you have to scroll a lot to see all the categories available. Which is not the case with my version. Discoverability of the categories/subcategories is important.

[insectengine]

I have two issues with yours.

1. All of the functionality of the page is filtering. Between the version pull down, the current category pulldown, and keyword search. This works the same for the extensions page. We're now talking about adding a different navigation method on top of it. I feel it would create confuse for the user.

If the end goal is filtering, lets do filtering. We're currently filtering by category from the blue bar at the top of the page so the mechanism is in place correct?

2. By adding all of the sub-categories as visual tags but making them function as anchors, just adds to the confusion of point one. This is a searchable index page. Do we have any data to suggest that users are having issues finding the content because it's not discoverable from the index? The traffic data I've seen says the vast majority of our traffic enter the site through search engines on specific searches anyway.

3. Yes, there are a bunch of filtering options that can create a scroll verses a site our primary competitor that has something like 16 categories. Do we need that fine grained level of exposed subcategories? Just because we can put this level of detail in, doesn't mean we should for the user. Do we have a dataset that generates this list (most searched terms for guides or something that) that shows that users are looking for this level of detail in the categories? If we took out the subcategories, we're still looking at 21 categories. A quick glance through the sub categories and the most guides associated to any one seems to be ~14 guides. Several on have very few (FrontEnd only has ONE). This seems too fined grained in many cases. An option could still be to maintain the subcategories main index display but remove them on the filter list.

I'm still good to have a live discussion. ;)

[gsmet]

All of the functionality of the page is filtering. Between the version pull down, the current category pulldown, and keyword search. This works the same for the extensions page. We're now talking about adding a different navigation method on top of it. I feel it would create confuse for the user.

The end goal might be filtering. I really don't know. For now, I want people to be able to explore and go quickly to a category.

The work on categories/subcategories has been done with a LOOOOOOT of care and I iterated a lot to provide a good idea of the topics we cover, not have a category with 15 unordered guides...
It's actually what took me the most time.
So please don't throw it in the trash, it actually has value :).

And yes, let's discuss this live, it's going to be easier.

[insectengine]

Compressed the subcategories so the list is shorter and they don't look like tags.

Closed category tray navigation. The related extensions are added below the TOC in the block. Note the new close icon.

Opened tray navigation (note the new list Icon).

[gsmet]

1 and 3 look very good, I think we could start implementing them.

For 2, I would prefer not having a big bag of "with the same extensions" but rather a list per extension. But we could start with that and refine later.

[insectengine]

1 and 3 look very good, I think we could start implementing them.

Sounds good!

For 2, I would prefer not having a big bag of "with the same extensions" but rather a list per extension. But we could start with that and refine later.

Sure, I was only concerned about the width of the TOC block and the tendency of people to make really long extension names often as one word.

[rolfedh]

The latest mockups look very good — organizing by category is a clear improvement for readers. Two offers as implementation starts:

1. An editorial pass on the text the index displays (category titles, descriptions, guide summaries). They were written separately over the years and vary in style — "OIDC & OpenID Connect", for example, repeats itself. I can normalize them on the quarkus side.

2. Keeping the prototype's accessibility when building the tray: the <details>/<summary> tree already works with the keyboard. The closed-by-default tray needs aria-expanded/aria-controls, Escape to close, and focus return; the active guide link needs aria-current="page"; and an aria-label on the index nav can replace the <h3> that breaks the heading order for screen readers.

Happy to help with either.

[gsmet]

"OIDC & OpenID Connect"

Yeah I noticed this one too in the latest screenshot before I went for PTO but didn't have the time to fix it, will fix it in my PR on the other side. And I will ping you there so that you can review the rest.

I think we should iterate on the PR on the Quarkus side and get it merged so that @insectengine has proper data to work with.

Also James, I don't think we will implement this for older versions for now so we need to fallback to the previous layout if the data is not available.

That being said, it might not be too hard to "backport" this work to older branches with the help of AI so maybe we could do that at some point.

[rolfedh]

Heads-up on the Roq-migration side, two small things I found while running Holly's haq-it converter against this branch:

1. This branch is based on main from before Remove $baseurl template preprocessing from SCSS #2744 (merged June 22), so assets/css/main.scss still has the old $baseurl: "{{ site.baseurl }}"; line. The converter treats Liquid left in SCSS as a hard error, so it stops on that line before it even reaches your new nav code. A rebase onto current main clears it.

2. Your two new includes open with {% unless cat_data %}{% break %}{% endunless %}, and {% break %} outside a loop has no Qute equivalent, so the converter can't translate it. I opened Wrap guides-nav includes in {% if cat_data %} instead of a {% break %} guard gsmet/quarkusio.github.io#3 against this branch, which wraps the include body in {% if cat_data %}...{% endif %} instead (behavior-identical in Jekyll, converts cleanly). I also sent a converter-side fix to Holly (Convert the pre-loop {% break %} guard idiom to a Qute early-return holly-cummins/quarkus-roq#1) so haq-it handles the guard directly for future authors.

Everything else in your includes and layouts converts cleanly. Nice work on the redesign!

[holly-cummins]

Thank you for checking that, @rolfedh! (Well, and even more thank-you for diagnosing and fixing the problems.)

[rolfedh]

Sounds good, @gsmet. Ping me on quarkusio/quarkus#54877 and I'll do the editorial normalization pass on the category titles and descriptions there, since that is where the source text lives.

One thing to keep on this (website) side: my second offer was about accessibility for the new navigation tray, and that work belongs here in #2749, where the <details>/<summary> tray is actually built. It won't be covered by the Quarkus-side data PR. When tray implementation starts, I'm happy to help wire up aria-expanded/aria-controls, Escape-to-close with focus return, aria-current="page" on the active guide link, and an aria-label on the index nav. Just flagging it here so it doesn't fall between the two PRs.

[gsmet]

@insectengine I have some good news :). I merged the pull request so the data is now available in the doc for the main branch.

categories.yaml is as it was in my prototype. There is a slight change with the categories in the guide attributes: we kept categories as is and there is now a categories-path attribute with the paths.

[gsmet]

@insectengine FYI, @marko-bekhta is iterating on the search engine for now so maybe it's better to wait for his work before starting anything.