Allow disabling or customizing the next version banner

[omry]

🚀 Feature

v58 adds this banner:

I would like to either disable it or customize it to something like:

This is the documentation for the next version of Hydra.
It is not yet released, please report any issues.

The documentation for the stable version is [here](/foo/bar).

[slorber]

Hi again :)

There are multiple things that we plan to do for versioning (see feedbacks here: #2302).

One of them is to be able to use the next version as the "current version", ie for example the /docs/myDoc would lead to the root /docs/myDoc.md instead of versioned_docs/latestversion/myDoc.md. This way, you wouldn't get such banner on the next version. Can this solve your problem?

---

We could support customizing these banners, from the messages to the admonition type/color.

For this message:

This wouldn't be so straightforward because we need to "inject" the link in the user message template here, it has been requested that this link is "dynamic", ie this link on /docs/next/myDoc would link to /docs/myDoc, not just the root doc

Is there a way we could improve this 2nd message in a generic way so that it fits your usecase, and would be a decent message for all usecases?

One solution we could also use is to make a dedicated component for showing this banner, allowing you to swizzle it and customize easily.

[omry]

Hi @slorber!

One of them is to be able to use the next version as the "current version", ie for example the /docs/myDoc would lead to the root /docs/myDoc.md instead of versioned_docs/latestversion/myDoc.md. This way, you wouldn't get such banner on the next version. Can this solve your problem?

In this specific case, no:
I am in a pre-release stage and I am not ready to change the default documentation to the new version.
I want people using the pre-release to have easy access to the documentation, but until the rc matures enough I am not pushing it aggressively.

This wouldn't be so straightforward because we need to "inject" the link in the user message template here, it has been requested that this link is "dynamic", ie this link on /docs/next/myDoc would link to /docs/myDoc, not just the root doc

Yeah, I figured it could be involved.
I am assuming that by dynamic you mean build-time dynamic. not really dynamic.
you could introduce use useBaseUrl() support into a micro templating language, but yeah - it's a bit much.

I am not familiar with the Swizzle approach (I saw it mentioned but never used it with D2 yet). a dedicated component sounds like a promising direction.

Is there a way we could improve this 2nd message in a generic way so that it fits your usecase, and would be a decent message for all usecases?

It really depends on what we want to tell the user. The current banner is telling the user:
"You should not be here, go there."

What I want to tell the user is more like:
"There is some danger here, but feel free to stick around".

Not sure there is a single message that conveys both messages at the same time.

[slorber]

This PR has some versioning related refactorings also relative to the banner: #2971

I'll extract this part as a dedicated component so that it can be more easily swizzled in isolation

[slorber]

Hey all, this is feature is now released!
If you like it, don't forget to retweet 😄
https://twitter.com/docusaurus/status/1286715187983048704

(there's a new dedicated theme comp)

[omry]

https://twitter.com/Hydra_Framework/status/1286746227808165888

[slorber]

🤗 Facebook has nice open-source mascots 😉 Le sam. 25 juil. 2020 à 02:52, Omry Yadan <[email protected]> a écrit :

…

https://twitter.com/Hydra_Framework/status/1286746227808165888 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3013 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFW6PRGQVNUAUR22YPIL4LR5IUGDANCNFSM4OLPCOMA> .

[omry]

Hydra and Slash are quiet unique. I don't think you will find any other projects with similar logos.

[slorber]

Check this versioning related RFC: #3285

[LoicPoullain]

Would it be also possible to allow disabling or customizing the banner of past versions?

The current message hints that past versions are not maintained anymore which can be wrong. In the case of FoalTS, past versions have a lifetime during which bugs and security holes are fixed even if no new features are added.

I currently use this (hacky) workaround:

.alert.alert--warning.margin-bottom--md {
  display: none;
}

[slorber]

for now the best is to swizzle the component and implement the UI you prefer

In any case I'm not sure we'll be able to find a theme API surface that will satisfy all our users use-cases, so the solution we may find is likely a best effort to solve most common usecases

[LoicPoullain]

Thank you for the tip. I was able to override the content with the following command (v2.0.0-alpha.69):

npm run swizzle @docusaurus/theme-classic DocVersionSuggestions --  --danger

[Yorkemartin]

I've been trying to figure out how to remove the "next" version entirely - seems like maybe it was implemented but I cant find and docs mentioning it. Any tips on how to achieve this? @slorber

[slorber]

This will be fixed in #5052 and beta.2

For now, we just introduce an API that permits to customize this banner on a per-version basis:

const docsOptions = {
  versions: {
    current: {
      banner: "none"
    }
    "1.0.0": {
      banner: "none"
    }
  }
};

This may not be the simplest API in case you want to disable ALL the versions at once but should be good enough to not requiring swizzling anymore.

We may add new APIs in the future, also may provide a way to define a custom banner/message. Let me know if the current API is still preventing you from doing what you want.

Note: even if you can't provide labels directly through config, the hardcoded predefined labels for "unreleased" and "unmaintained" are configurable thanks to the i18n support (example translation key theme.docs.versions.unmaintainedVersionLabel)

Note: there's a breaking change, as the existing DocVersionSuggestions component has been renamed/refactored. Make sure to upgrade your code after upgrading.

[slorber]

@Yorkemartin

I've been trying to figure out how to remove the "next" version entirely - seems like maybe it was implemented but I cant find and docs mentioning it. Any tips on how to achieve this? @slorber

There is an includeCurrentVersion: false option so that the website/docs folder is not included in your site (only the versioned folder will be displayed)

(previously called: excludeNextVersionDocs: true but has been renamed)

[GPMueller]

This may not be the simplest API in case you want to disable ALL the versions at once but should be good enough to not requiring swizzling anymore.

@slorber is there by any chance a follow-up issue or some plan to implement setting the default for all versions or deactivating the banner overall? I couldn't find one and it doesn't seem to be part of #3285.
Seems to me that it would help with configuration of CI-maintained docs.

[slorber]

@GPMueller yes we have configuration options to customize the banner for each versions independently

(not a global docs config, but it's probably good enough).

https://docusaurus.io/docs/versioning#configuring-versioning-behavior

Also for more advanced use-cases we have extracted all this feature in DocVersionBanner that you can swizzle and render null if you want.

[filipermit]

I'm trying to change the text of the banner, I attempted Swizzling it, but I don't get many customisation options. Any help?

[slorber]

It's my plan to allow more flexibility options in Docusaurus on various axis: navbar items, footer items, sidebar (docs+blog) items... and also docs version banner items. See also temp workaround for custom navbar items here: #7227

For now we only provide a limited set of hardcoded banner item types, but we'd like to provide custom version banner items that you can register and implement yourself.

It's not clear to me how to help you considering you don't say what you want to achieve, but in any case, swizzling DocVersionBanner is the only solution atm and gives you 100 flexibility, at the cost of having to maintain the code. I have no idea what you mean by "customization options" that you couldn't achieve by modifying our code.

[Sadhvik-Modak]

adding this includeCurrentVersion: false solved...