Allow ignoring some version aliases when showing the version selector

[ilyagr]

Context

Firstly, thank you so much for implementing #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.

Related links

• Requesting a change
• Add mike alias name to version selector #6436

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

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

[squidfunk]

Thanks for suggesting. I'm pretty sure that this is a duplicate of #6904. Can you confirm?

[ilyagr]

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]

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]

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]

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]

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 (jimporter/mike#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.

[jimporter]

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.

Indeed, even if I wanted to change the format of versions.json, I can't: it would break version-selection when you're on an older version of the docs. It is what it is, for better or for worse.

More generally though, I'd recommend against the Material theme displaying aliases in any way in the version selector: while stored in versions.json as an array, aliases is in fact an unordered set, and mike makes no promises about what alias comes first in the list. See (for example) jimporter/mike#229. Mike also assumes that versions.json is consistent with the actual files in the gh-pages branch, so if you simply remove an alias from versions.json, that alias doesn't really exist from mike's PoV (it will still probably work, but you're voiding your warranty ;)).

Instead, I'd recommend using version properties for this. Users could add a string property like subtitle or description to their versions, which the Material theme could then consult and display as desired in the version selector. (Version properties are reserved for MkDocs themes to do with as they see fit, so you should be able to use them without fear of causing problems for mike.)

[ilyagr]

Thank you @jimporter for taking a look at this! I was thinking of asking your thoughts when this discussion started, but never got around to it; thanks to the author of jimporter/mike#229 for doing it.

I can't comment on what works or doesn't for the Material theme, but here's a question about mike. The most important alias to show (for me) is latest, as in #7229 (comment). If I was using version properties, is there an easy way to move the prop "latest" together with the alias "latest" with a mike command? Or how would you set it up?

---

Aside: the workaround for this issue I ended up sticking with was to grit my teeth and make it so that there is at most one alias per version in my docs. Not many people were using the aliases I had to remove to make it work, fortunately.

[jimporter]

If I was using version properties, is there an easy way to move the prop "latest" together with the alias "latest" with a mike command? Or how would you set it up?

This code snippet uses the version title instead of version properties, but should otherwise be about the same as your scenario: https://github.com/jimporter/bfg9000/blob/5c65b2362673b388a39f12bb63bea6bdb4f3e363/setup.py#L84-L105. In summary, it does this:

1. Figure out what alias we should use for the to-be-deployed version (this assumes you're deploying either a latest or dev version, but it shouldn't be hard to add logic for deploying to older versions too)
2. Get the currently-deployed version associated with that alias
3. If it's different from the to-be-deployed version, retitle the currently-deployed version so it doesn't have "latest" or "dev" in the string
4. Deploy the new version with the appropriate title

In general, I designed mike primarily to make it easy to add scripting on top of it to automatically manage the current version/aliases. In Git terms, mike is the plumbing, and users provide their own porcelain suited to their project's needs.

(As an aside, I think the aliases in versions.json are only actually necessary for selecting the right version when using alias_type: copy in the configuration. For the other alias_types, I think that field is actually superfluous.)