Better documentation navigation with a new sidebar

[hugh (Hugh Lashbrooke)]

This week, we published a significant improvement to Discourse documentation - a new sidebar! This feature is designed to make navigating and accessing our documentation easier and more intuitive than ever before.

What’s new?

The new sidebar shows up on all documentation categories and topics, making it easier to navigate their content. Here’s what you can expect:

1. Improved navigation: With a clear, hierarchical structure, moving between different topics is now faster and more straightforward.

2. Context awareness: The sidebar highlights the current topics you’re viewing, making it easy to understand where you are in the documentation.

3. Collapsible sections: Each section within the sidebar can be collapsed and expanded as needed, making it easier to find the topics you need.

4. Live filter: Quickly find specific topics in the sidebar by typing in relevant keywords - if nothing is found, you’ll be invited to perform a deeper search with the same prompt.

5. Mobile friendly: The new sidebar works seamlessly on mobile, with all the same features as the desktop view.

Let’s take a look

You can see the new documentation sidebar in action today!

Here are some screenshots to give you a better idea of what to expect:

As you can see, the sidebar provides a clear overview of all documentation sections, making navigation a breeze.

Each category shows the topics within it, divided into defined sections.

The topic you are currently viewing is highlighted in the sidebar for easy reference.

Each section can be collapsed, allowing you to find the content you need more easily.

Individual sections can be expanded to show their content more clearly.

Building on recent improvements

This new sidebar is part of our ongoing efforts to improve the Discourse documentation experience. It builds upon the recent work to restructure documentation for improved clarity. The new sidebar complements these structural improvements by providing an intuitive interface for navigating the recategorised documentation.

This is coupled with the ongoing overhaul of the content of all of our documentation topics to align with the recently published style guide. This is a work-in-progress, and you may notice gradual improvements as we go about this.

We want your feedback!

Have you had a chance to use the new documentation sidebar? We’d love to hear your thoughts! Please post your experiences, suggestions, or any questions you might have on this topic.

If you have questions or feedback on our overall documentation efforts, please let us know on this topic.

Thank you for being part of the Discourse community. We’re excited to see how this new feature enhances your Discourse experience.

[Arkshine]

Congrats on the new changes; they are really cool.

• Live filter across all categories
  I know the way it currently works may be difficult; I would have loved to be able to filter regardless of what (sub)categories I am. That’s the first thing I naturally tried:

Of course, there are links to help, that’s great. Instead, I would have expected:

• Content scrolling up when using ctrl + /
  When using the shortcut to focus the search input, it scrolls up both the sidebar and content. I don’t expect the content to scroll up here.
  

• Losing context awareness
  If you use the filter, click on a topic, and then clear the filter, you may not see the highlighted topic. EDIT: Also, if you navigate to a topic from a post.
  

• Collapsed section is not highlighted when viewing a topic
  If you’re viewing a topic and collapsing the sections, I think it would be useful context-wise to highlight the section somehow or simply emphasis it.

[ondrej]

Nice addition/improvement!

Its so much simpler to navigate as its wayyyy more obvious where to look

One slight thing is the order of the categories vs the order on the navigation sidebar.

In Documentation the last 3 categories are:

Migrating to Discourse
Contributing
Developer Guides

However on the nav sidebar Developer Guides and Contributing are switched.

Great work!

[JammyDodger]

They should be in matching order?

Where are you seeing the alternate order?

[ondrej]

I’m on mobile.

[JammyDodger]

How odd. I do not know why yours is a bit different.

Here’s what I see:

You also don’t look like you have a developer guide category description in the box. Have you muted the category or something?

[nolo (Manuel)]

Can I enable such a category sidebar on other instances?

[Moin]

It’s a theme-component GitHub - discourse/discourse-docs-sidebar.

[ondrej]

@JammyDodger

Have you muted the category or something

Ahh that was it, problem solved!

[mcwumbly (Dave McClure)]

@nolo

Can I enable such a category sidebar on other instances?

@Moin

It’s a theme-component GitHub - discourse/discourse-docs-sidebar .

You’re welcome to tinker, but there’s plenty more to do to make this really be something that we are prepared to fully support.

There’s a fair bit of overhead involved in maintaining the index topics, which is what is driving the UI for the sidebar, and no built-in system for ensuring that they remain consistent with the topics in the category.

We’re accepting that overhead for maintaining the docs here for now, with a focus on gathering feedback from people about the experience of reading and browsing documentation here. We’re looking for that kind of feedback right now moreso than feedback about what it’s like to maintain documentation using this component.

[Heliosurge (Dan DeMontmorency)]

This is very nice indeed. Looking forward to a full release.

[Jagster (Jakke Lehtonen)]

It is much easier to use than old one. More… clearer. But I can bet more technically oriented ones may see it limiting.

I don’t use docs, even I have need, because my users scared filterings. This system would be more user friendly.

But if it needs constant love and care from admin-side…

[hugh (Hugh Lashbrooke)]

@Arkshine

Content scrolling up when using ctrl + /
…
Losing context awareness
…
Collapsed section is not highlighted when viewing a topic

Thanks for noting these, @Arkshine! These should all be fixable, so we’ll see what we can do here.

[Moin]

Somehow the docs sidebar changes how the search works. On my tablet, I cannot use the enter key to get the search results when the docs sidebar is visible. I noticed it says ‘next’ instead of ‘go’ but I don’t know why.

[saquetim (Sérgio Saquetim)]

I can’t repro the issue.

Just tried on my Ipad.

Can you check if it’s still happening?

[Moin]

It is still happening. I can reproduce it in Chrome and Edge, but not using the Firefox app.

[saquetim (Sérgio Saquetim)]

Still, can’t repro. I don’t see how the docs sidebar could be causing this.

It doesn’t alter any search code.

It may be something else.

Can you provide more details about the setup you’re using? Browser version, OS, etc.

[Moin]

Galaxy Tab S9 FE
Android 14; SM-X510 Build/UP1A.231005.007
Chrome 126.0.6478.123

I tried the external keyboard. This helped me to determine that the enter key apparently has to be pressed a second time.

[saquetim (Sérgio Saquetim)]

Ok, I can repro on Android.

It’s not only the docs sidebar, the same happens with the admin sidebar as well.

We’ll have to investigate the issue.

I already know what’s happening.

We’ll discuss the best fix internally.

[saquetim (Sérgio Saquetim)]

The issue should be resolved by:

DEV: Added enter hints for the quick search and sidebar filter

It’s already live on Meta