Docusaurus: "These docs are out of date!" banner support for older docs pages

[rachelnabors]

🚀 Feature

A configurable banner that shows at the top of all versioned docs, directing people to the most recent page.

Have you read the Contributing Guidelines on issues?

Sure have :)

Motivation

On ReactNative.dev, 3.5% of traffic is to versioned docs. Sometimes search engines mess up (don't we all?) and show old pages to users looking for the most up-to-date information. Sometimes they don't even realize that they're looking at old information! Wouldn't be nice to let those 3.5% users know where they are and give them a link to the latest docs.

This is a technique other documentation sites take when they still want their older docs to be indexable and searchable, but they don't want users to be mislead!

Pitch

When a user visits a versioned doc, across the top of the page, show them a sticky banner that tells them:

• they are viewing outdated information from VERSION
• what the CURRENT_VERSION is
• and links to the most recent page (if it exists)

[anshulrgoyal]

Instead of a banner, we can do this:-

Rust docs do the same.

[teikjun]

@anshulrgoyal In the context of a docusaurus site, this is one possible layout:

[slorber]

Having this in the docs layout could be a problem in some cases. For example a doc in v1 might be deleted/renamed in v2, so it's not possible to go to the same doc in v2.

This makes more sense to me if this is a global warning.
Sometimes a new version is a full rewrite of the whole code/doc.

[anshulrgoyal]

Yeah it will be a global warning

[teikjun]

@anshulrgoyal Alternatively, we can use a banner so it is clearer that it is a global warning

[anshulrgoyal]

Banner

When the user clicks on banner it will take to /
Pros:

• More predominantly visible on the page
• Conveys a global warning
  Cons:
• Maybe overwritten by the user setting
• Duplication of version related information

Breadcrumbs

When the user clicks on breadcrumbs it will take to /
Pros:

• looks cleaner
• didn't hinder any other feature
  Cons:
• May convey that the warning is not global

[yangshun]

Prefer not to use a global warning because there's already the announcement bar. We don't want to have so many "announcements". Adding global UI items has already been a cause of layout pain because the navbar can be fixed (you can look at how much code @lex111 added to support the announcement bar) and I don't think we should contribute to it even further.

[anshulrgoyal]

We will be moving forward with breadcrumbs option.