Add an option to show aliases in the version drop-down list

[leandro-lucarella-frequenz]

I'm not sure if this is the right repository to request this feature in particular, or maybe the right place is material for mkdocs (I'm using that template)?

I would like to have, for example, the latest alias listed in the drop-down list of versions, so users can know better which is the latest version.

[jimporter]

You can set the title to use for the version with the --title option. Just set it to 1.2.3 (latest) or whatever you think would look best.

[leandro-lucarella-frequenz]

But if I do that I need to update titles from previous versions each time latest changes, which is not ideal. Although automatically adding aliases to the drop-down entry could also be a good solution.

[jimporter]

Yeah, you'll have to add some tooling on top of mike to manage that, if that's what you want to do. Since the users of the tool know best how to list their versions, mike has subcommands to let you manage this how you like. mike list -j latest would get you the version info of the version currently tagged with latest, and then you can use mike retitle to change the it how you like. It's straightforward to do this in a simple script in your project's tooling (in fact, it's what I do myself).

[leandro-lucarella-frequenz]

OK, I understand you want to keep mike simple and I do see the value in that, but it is a shame that the information is already there in the json, it would be a matter of just showing it in the versions drop-down, but maybe that's a theme thing?

Anyway, thanks for the great tool and for taking the time to follow up on this!

[jimporter]

If you wanted to do this through the theme, you could also do that. However, since not all aliases should necessarily be shown in the dropdown, there's not an easy way to automate this in general. For example, there are two main ways I'd recommend to handle patch versions:

1. Put docs in a [major].[minor]/ directory and set the title to [major].[minor].[patch] ([alias]), e.g. 1.0/ with a title of 1.0.1 (latest). In this case, you'd have to override the title anyway, so you'd need to manually manage adding the alias as well. (It would be strange to require the alias to be in the title even if the user specifically overrode it.)
2. Put docs in a [major].[minor].[patch]/ directory and add aliases for [major].[minor] and latest (or similar). In this case, you'd only want to display the latest alias in the title, but not [major].[minor], since it's redundant. In that case, you'd need to override the title to choose exactly which alias to show, since mike can't (and shouldn't, in my opinion) automatically distinguish between aliases that belong in the title and aliases that don't.

Since neither of those work well with automatically showing aliases in the title, it's a manual process. Or rather, mike doesn't do it manually; I'd definitely recommend automating it in user-level scripting. Here's an example of what I do: https://github.com/jimporter/bfg9000/blob/2dcdcd33f8575c2241d7c02b125af1b9755044c8/setup.py#L84-L105

[leandro-lucarella-frequenz]

For me just showing all the aliases (as an on/off option) looks like a reasonable default for people that doesn't want to get into customization too much, for me at least it works good enough. But I understand your point.

Thanks for the suggestions!

[eddiebergman]

Sorry, I realised this is closed but I stumbled across the same issue while automating deployment of docs with mike. Here's a fairly simple script which retitles everything back to its default, after which I retitle the version I want to have as (latest)

# Remove anything that has a title that is not the same as it's version
# Also strip the `"` with `tf -d '"'` from the versions as `retitle` won't accept them
retitled_versions=$(mike list -j | jq ".[] | select(.title != .version) | .version" | tr -d '"')
for version in $retitled_version; do
  mike retitle "${version}" "${version}"
done

# Deploy a new version where the version I want to deploy is already tagged
# I've already tagged the latest version using commitizen
latest_version=$(git tag | sort --version-sort | tail -n 1)
mike deploy \
  --push \
  --title "${latest_version} (latest)" \
  --update-aliases \
  "${latest_version}" \
  "latest"

Many thanks for the -j output, it made automating this through bash very easy (once I grokked jq)!