Major section divider in section menu

[snunez1]

Is there a way to insert a major section header, similar to the one that says Documentation, with a line under it?

The use case is a site that's grown larger, and has several independent modules that are typically used together, but are independently useful. I've got a section under Documentation that talks about using the collection as a unit, and would like another section, Manuals, where the user documentation for each individual system would reside. I know I can do this now, but the menu navigation tends to run too far to the right, and it's aesthetically a bit nicer to see a big "Manuals" so people know this bit of the section menu is different.

Any way to accomplish this?

[LisaFC]

It's not built in to the template but should be doable in your site (I hope!) with a bit of tweaking given that the style is already there.

So just to be clear, you'd like essentially two (or more) menus in the same left nav, each with their own "top level" (like Documentation) heading?

[snunez1]

@LisaFC, yes that is correct, multiple top-levels.

[snunez1]

I suppose I should also ask about the use case. This is my solution to a set of projects that has grown enough to require better organisation, and I wonder if perhaps the technical documentation experts here have any better suggestions.

The situation is 4 projects, all useful independently, but normally working together that have gotten larger and better documented. I've generally followed the docsy recommendations, with an overview, getting started and 'core tasks', with a section under core tasks for each system.

As we now have more of the system built, there are user facing APIs and developer facing APIs, currently all mixed together under those core task sections, and it's hard to understand. My thinking is to move the developer focused stuff into a different top level section, 'Manuals', 'API Guides', or something like that.

Any advice on docs organisation in a situation from the experts?

[fekete-robert]

@snunez1 You might want to check the Istio documentation (https://istio.io/latest/docs/concepts/traffic-management/), I think that's the style you are looking for. They are using Hugo, but I haven't had the time yet to dig into their layout to see how it's getting done. Here is their repo: https://github.com/istio/istio.io/

[snunez1]

Thanks. That's a very nice side bar / TOC indeed, and something like what I had in mind. If Docsy had a side bar like that, I imagine just about every use case could be catered for. I especially like the Istio font & spacing; they fit quite a bit of navigation information into that sidebar.

[LisaFC]

The Istio docs are lovely but a lot of the presentation/navigation was hand-written specifically for that site by one of the SWEs and I don't think the sidebar is fully autogenerated (I used to work on Istio and in fact wrote most of the original version of the article Robert linked to :) ) - let me dig into a bit.

You can easily change the font and other text styling (size etc.) on your Docsy site to whatever you like by overriding the various Bootstrap variables as described here: https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files

You can find the font variables we use and their current defaults in the Fonts section of this file: https://github.com/google/docsy/blob/main/assets/scss/_variables.scss

[LisaFC]

Ok, had a look and the Istio sidebar menu is autogenerated and it's basically just multiple generated submenus, each in their own div with a header. I don't think you'd need to completely refactor your left nav code to get a similar effect with the existing Docsy code but I'm going to play around with styles a bit to see what you could do. @chalin or @narrenfrei might have ideas too.

For your information architecture question, I think you're on track with your idea of separating your content for your developer audience from the content aimed at your more end-user audience, users like being able to easily find the content that's relevant for them and mixing very separate audiences in the same guide/doc can be confusing.

Not familiar with your topic but how about something like:

• Overview (describes [blargle] and its use cases/how it can help users)
• Get started (is this aimed at end-users or developer users too? do developers need an entire separate get started?)
• Use [blargle]
  • tasks go here
• Develop (with?) [blargle]
  • tasks go here

I'm assuming here that the developer APIs are for people developing with your product or possibly developing your product, you might want a slightly different title depending on your use case - I think just calling it "APIs" or "Manual" doesn't make it entirely clear who the audience is if both end-users and developers have APIs they can use, choosing a title related to the user's use case/intent makes it more obvious.

I'm also assuming the docset is small enough and the overview is relevant enough to all users that it should all be in one nav - the alternative is to create an entire separate section for the "Develop with [blargle]" navigable from the top menu, though you'd need to make sure that it was findable from the other user guide section/the other section is titled "Use [blargle]"

Good to get input from some of the other community members too - @emckean @RichieEscarez any ideas?

[raum51]

In a specific case, the desired appearance should be easily implemented using CSS (or SCSS). For such a case I introduced the CSS classes ul-0, ul-1, ul-2, ... - which count the nesting depth of the menu (70bf4bc580ce984c042dcfd9eeb0637cfe63cc59 by my old handler @narrenfrei).

For a general solution - in other words: activating such an appearance using a parameter, it unfortunately looks a bit more complicated, since there are already many different variants of the sidebar menu: normal menu, collapsible and expandable menu, cached menu (with JS) - so there could be many side effects.

[snunez1]

That sounds like some of the features in our systems. We glommed on a bunch of functionality in the interests of time, and now we're paying the price and fixing them 'properly' because it's not going to get easier in the future.

[chalin]

If I understand what you're asking, @snunez1, I agree with @raum51 that you can achieve this using styling. Can you share a link to your website so that we can have a better idea of what it currently looks like?

[snunez1]

https://lisp-stat.dev/

That's on an early version of Docsy; I've since upgraded locally to 0.3. I'm hoping to push a new version as soon as I work out navigation.

[snunez1]

Just want to bump this, as we're focusing on docs again whilst there's a bit of time to do so. Has the situation change wrt getting istio style menu and navigation? IMO, this is an overlooked area in docsy, both because first impressions are important (the default lacks the professional appearance of the istio site) and because good navigation is an important part of the user experience.