Docusaurus: 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: https://github.com/facebook/docusaurus/issues/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: https://github.com/facebook/docusaurus/pull/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 [e-mail] 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
https://github.com/facebook/docusaurus/issues/3013#issuecomment-663786220,
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: https://github.com/facebook/docusaurus/issues/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