Make section index page links more visible

[ekoleda-codaio]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

When using both the feature navigation.sections and navigation.indexes you can get into situations where the section header is itself a link to an index page. For example, on this page the headers "Migration" and "Contributing" appear like other section headings, but are in fact clickable links to index pages.

On hover the color of the text changes to indicate there is a link, but prior to that there is no visual indication to the user that more content lives there.

I'm not sure what the best UI treatment should be, but it would be great if the clickable section headers were visually distinguished from the non-clickable ones.

Use Cases

It would make it easier for users to discover content, or at least less likely to miss content that they are looking for.

Screenshots / Mockups

No response

[ekoleda-codaio]

I should note that I think the issue exists to a lesser degree when using navigation.indexes on its own. Visually there is no difference between a grouping node with a page and one without. That said, I think people are more likely to click on the unbolded non-section grouping nodes than they are on the bolded section headers.

[squidfunk]

Thanks for suggesting. So off the top of my head, the simplest thing we could probably do is make non-clickable sections greyish, while keeping clickable links black. Off course, it's trivial to apply further styling, but I think this might be a good default. It could look something like this:

[ekoleda-codaio]

Another approach, maybe a bit more involved, would be to have navigation.indexes not apply to section headers (or make that an option). I enabled navigation.indexes to help with deeper levels of nesting, but for section headers maybe it makes sense to ignore that and keep the index pages as separate entries in the nav.

[squidfunk]

I'm not sure I would agree – I think it's very useful that it applies to section headers. However, in the end it might be a matter of taste. As always, we try to strike a good balance here. If you have navigation.indexes enabled, and don't want to apply it to a section, you can always rename the file into something other than index.md.

[squidfunk]

fc352ee is an attempt to improve discernability of section index pages in navigation. If that's not to the taste of the author, it can be easily changed with a little CSS, overriding the selectors that apply the styles.

[ekoleda-codaio]

Thanks for the quick attention. I'll give it a try.

[squidfunk]

Released as part of 9.0.3.

[marc2k3]

I really dislike this change in 9.0.3 on the left. 9.0.2 on the right is far more pleasant.

I need some CSS please. 😬

[squidfunk]

Well, the points the author brought up are very relevant – it's unclear whether a section index is clickable or not. Do you have a better idea how we could distinguish both cases with alternate styling?

[marc2k3]

In my particular use case, none of the section headers are clickable and with that lack of contrast, it just looks like a huge list with no grouping at all. I have no idea what any solution could look like. It's very much "not my thing" (tm)

Since I'm utterly clueless, I'll pin my github action to 9.0.2.

[squidfunk]

It's trivial to override. Use the following CSS to revert to the previous behavior:

.md-nav__link[for] {
  color: var(--md-default-fg-color)
}

Please keep in mind that with a project of this size, it's impossible to please everybody. This is why this theme is extensible, hackable and easy to customize. We're putting a huge effort on keeping overriding as simple as possible. In this case, accessibility is clearly the priority, which is why we made links discernible.

[marc2k3]

That's great, thanks.

[dr-br]

Sorry for bumping in again (I opened #4841)
In this conversation here it is mentioned, that the gray color should denote, that a section is not clickable. However, the most basic case results in a gray but clickable section index (not sure if i interprete "section index" correctly):

site_name: My Docs
theme:
  name: material

nav:
  - Topic 1:
    - index0.md
    - index1.md
  - Topic 2:
    - index2.md
    - index3.md

results to this ("Topic 1" and "Topic 2" are clickable):

I'm aware, that 3 lines of css can remedy this, however the statement gray == not clickable does not hold here.

[squidfunk]

The behavior is correct – clickable in that case meant there's an actual page behind that section index. We might consider limiting the grey color to navigation section without index pages behind them, but that would make it less consistent.

However, I'll reopen it so we can re-evaluate.

[dr-br]

Thanks for being that patient ;)

This minimal example

site_name: My Docs
theme:
  name: material
  features:
    - navigation.indexes
nav:
  - Topic 1:
    - folder0/index.md
    - folder0/index0.md
    - folder0/index1.md
  - Topic 2:
    - index2.md
    - index3.md

Results to this:

I'll try to figure out, how to make this more consistent.

[dr-br]

Using navigation.sections makes the minimal example consistent, black == clickable. Without navigation.sections, "Topic 1" and "Topic 2" should remain black.

site_name: My Docs
theme:
  name: material
  features:
    - navigation.indexes
    - navigation.sections
nav:
  - Topic 1:
    - folder0/index.md
    - folder0/index0.md
    - folder0/index1.md
  - Topic 2:
    - index2.md
    - index3.md

[squidfunk]

@dr-br Could I please ask you to provide reproductions for both cases? It makes the life of us maintainers much easier.

[dr-br]

It is my pleasure to do so:
example_withoutNavigationSections.zip
example_withNavigationSections.zip

The sample withNavigationSections is logically consistent.

[squidfunk]

Thanks for the reproduction, made it trivial to inspect the situation! Fixed in 02637ef. Only sections should now receive the grey color, regardless of navigation.indexes. I've also checked with navigation.sections.

Your example:

Your example without navigation.indexes:

Your example with navigation.sections and some deeper navigation added:

[squidfunk]

There was one additional case that needed to be handled, which is the titles of sections when navigation.tabs is enabled. This is fixed in ce5e353, so titles which do not lead to pages are now rendered grey again. Navigation with its thousand possibilities of combination can be a hellscape at times 😅

[dr-br]

Excellent work. Thanks for reopening/fixing. I guess, the initial consideration of @ekoleda-codaio as well as the concerns of @marc2k3 have been met.
Grüße

[marc2k3]

There was one additional case that needed to be handled, which is the titles of sections when navigation.tabs is enabled. This is fixed in ce5e353, so titles which do not lead to pages are now rendered grey again. Navigation with its thousand possibilities of combination can be a hellscape at times 😅

So this breaks my ability to style it using the CSS you gave me the other day. I tested the latest with

pip install https://github.com/squidfunk/mkdocs-material/archive/refs/heads/master.zip

and this no longer works...

.md-nav__link[for] { color: var(--md-default-fg-color) }

After poking around a bit, I managed to "fix" it by adding !important.

[squidfunk]

I think using !important is your safest bet in order to guard against further changes in the CSS. As I mentioned, the navigation CSS is necessarily complex due to the thousand different ways navigation can be defined.

[squidfunk]

The latest changes were released as part of 9.0.4.

[krahets]

Well, the points the author brought up are very relevant – it's unclear whether a section index is clickable or not. Do you have a better idea how we could distinguish both cases with alternate styling?

Thanks for the great changes!

I agree with @marc2k3 that the gray color is too weak to show the title clearly. The title with gray color can not make me realize it is unclickable.

I evenly don't think it is necessary to distinguish them because the answer reveals when we hover the cursor on the title.

If it is necessary, could we add different default icons or symbols before the title to distinguish them instead of using different colors?

[squidfunk]

You can achieve all of that with customization. Please understand that Material for MkDocs is heavily opinionated and tries to provide sensible and great defaults. If that doesn't match your taste, the theme is very extensible and hackable. We can't please everyone, so we need to keep a common ground.