Allow ignoring some version aliases when showing the version selector

ilyagr commented 1 month ago

Context

Firstly, thank you so much for implementing https://github.com/squidfunk/mkdocs-material/issues/6436!

Please let me know whether you agree with this being a useful feature and this design. If so, I can probably implement it, or we can discus a better design. (Of course, if it's easier for you to do it yourself and you are interested, feel free!)

Description

I would like an additional config, e.g. ignored-in-version-selector:

extra:
  version:
    provider: mike
    alias: true
    ignored-in-version-selector:
       - alias1
       - alias2

This would cause these aliases to not be shown in the version selector. If, say, alias1 is the only alias for a version, no alias would be shown. If it is the first of several aliases for a version, the next one in the list would be tried.

Use Cases

I have some aliases that are confusing to show in the version selector (in addition to aliases which are extremely useful to show in the version selector). I cannot remove them without breaking some links.

Visuals

No response

Before submitting

[X] I have read and followed the change request guidelines.
[X] I have verified that my idea is a change request and not a bug report.
[X] I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
[X] I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

squidfunk commented 1 month ago

Thanks for suggesting. I'm pretty sure that this is a duplicate of https://github.com/squidfunk/mkdocs-material/issues/6904. Can you confirm?

ilyagr commented 1 month ago

No, this is a bit different. https://martinvonz.github.io/jj/prerelease/ has an alias https://martinvonz.github.io/jj/main/ (for "main branch"). The version switcher currently looks like this:

I think showing "main" in there is a bit confusing. However, I'd like the "prerelease" version to still show and the "latest" alias for "v0.17.1" to also still show (thanks again for making that possible!).

I believe that Mike supports hidden versions, but not hidden aliases.

I could delete the alias "main", but this would break old links. I could create another alias instead of "main" and put it first, but it's hard to come up with a good name and, well, we don't need another alias. I was thinking about using 🚀 for a while, but having Unicode in filenames seems ill advised (apparently such files cannot be synced with Dropbox, Git (intentionally) displays them differently in command output, and I'm not sure whether Windows can deal with UTF-8 encoded filenames).

It's a good point, though, that my "ignored-in-version-selector" suggestion would make people want to use it for versions, not just aliases. It could do both.

Is it possible to use CSS to not show an element if its contents is "main"?

ilyagr commented 1 month ago

Another possible design would be:

extra:
  version:
    provider: mike
    alias: true
    alias-overrides:
       prerelease: ""
       # or
       prerelease: 🚀

to show either nothing or a rocket in place of an alias.

We could also allow overriding main: "" (where main is an alias as opposed to a version). That's not needed for me, but others might find it useful.

squidfunk commented 1 month ago

Thanks for providing further information. Honestly, it doesn't make sense for us to add more and more configuration options for something that is essentially out of our control. If mike changes the format, we need to adapt, thus we'd prefer keeping the API surface as small as possible. I think you can fix this pretty easily by writing a custom hook, and post-processing versions.json, removing any aliases that you don't want to be present.

If you need help with that, don't hesitate to ask on our discussion board ☺️

ilyagr commented 1 month ago

I'm not sure I quite follow your idea and whether it relates to my situation. I'll list some concerns, but I'm not really sure whether we're talking about the same thing.

I am not very familiar with MkDocs hooks, but I'm guessing that a custom hook would run at the time of MkDocs building the docs, whereas versions.json is created or edited by Mike after that point, likely overwriting whatever the hook did.

I'm also worried that mangling versions.json might confuse future invocations of Mike, since it likely assumes that versions.json was produced by a previous invocation of Mike. If the hook mangles versions.json before Mike even runs, it might confuse the current invocation as well.

If a hook is the preferred solution (I'm in no way insisting on my proposed designs above), my mind goes to the idea of a Javascript hook that's run by the version switcher Javascript at runtime. For example, there could be a hook that's called after versions.json is fetched and transforms the JSON object.

Finally, I'm not sure what you mean by "if mike changes the format"; I think the idea that it has versions that have aliases is pretty stable, and MkDocs material is already using versions.json to read the version names and its aliases (well, the first alias). All I want is to ignore or transform some of the information already available to the theme.

I'm asking here as opposed to the discussion board since all the context is here and I'm not sure how to ask about your plan in a self-contained question. I appreciate the offer of help!

squidfunk commented 1 month ago

I am not very familiar with MkDocs hooks, but I'm guessing that a custom hook would run at the time of MkDocs building the docs, whereas versions.json is created or edited by Mike after that point, likely overwriting whatever the hook did.

You're right. You can just use the tool of your choosing to mutate versions.json after the build and before mike pushes the artifacts to GitHub Pages. How? I think it's best to ask the maintainer of mike. Also note that there's an open issue proposing a plugin architecture in mike, which might be something to consider (https://github.com/jimporter/mike/issues/161).

I'm also worried that mangling versions.json might confuse future invocations of Mike, since it likely assumes that versions.json was produced by a previous invocation of Mike. If the hook mangles versions.json before Mike even runs, it might confuse the current invocation as well.

AFAIK versions.json is just a built artifact and not considered storage, but best ask the maintainer.

If a hook is the preferred solution (I'm in no way insisting on my proposed designs above), my mind goes to the idea of a Javascript hook that's run by the version switcher Javascript at runtime. For example, there could be a hook that's called after versions.json is fetched and transforms the JSON object.

We currently have no plans adding hooks in the frontend. This might change in the future, and we consider your use case for evaluation when we think about adding this functionality ☺️

Finally, I'm not sure what you mean by "if mike changes the format"; I think the idea that it has versions that have aliases is pretty stable, and MkDocs material is already using versions.json to read the version names and its aliases (well, the first alias). All I want is to ignore or transform some of the information already available to the theme.

We're integrating with an external tool, so it means we have a dependency that we need to track and adjust to. Again, I think it is best to discuss this with the maintainer of mike.

squidfunk / mkdocs-material