Add warning banner for outdated docs versions

thibaudcolas commented 5 years ago

🚀 Feature

A feature I miss from other tech docs builders that support versioning is the ability to show a banner on older versions, to redirect people to newer docs.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

For versioned documentation, it’s quite common for links pointing at docs to reference a specific version, or for a specific version to get indexed in search engines. This can be problematic once a version isn't supported anymore / once a newer version is available, because users of the docs might not realise they are looking at outdated information.

Pitch

This feature should be implemented to reduce the likelihood of docs users wasting their time looking at an old version of the docs, where they arrive to the docs from a link pointing at a specific version. Here are examples of docs that use a similar pattern:

Django's "security risk + upgrade nudge" top banner, https://docs.djangoproject.com/en/1.10/

Wagtail's gentler warning, https://docs.wagtail.io/en/v2.3/advanced_topics/customisation/extending_draftail.html

Finally, this is a different feature but Django also has a similar banner for the development / latest docs, https://docs.djangoproject.com/en/dev/:

tusharf5 commented 5 years ago

@endiliey I would like to take this up. Please assign it to me if no one is already working on it. I've already made a rough implementation and it is working.

Few things I want to ask regarding this

I am thinking of putting an info/alert box above the title of a doc page if it's not recent. Let me know if you think putting it somewhere else would make more sense.
Do we create a new component for the Info/Alert Box? Or do we already have one already?

endiliey commented 5 years ago

@tusharf5 let's talk about the API first.

How do user set if certain version is outdated ? Can they decide if certain link is outdated ?

The announcement bar feature can be somewhat general feature too,, not just for outdated docs. Sometimes you want to announce something in your website. For example: “We are looking to revamp our docs, please fill this survey”. Even better if the announcement bar is dismissable and render above the nav bar.

any opinion @yangshun @JoelMarcey ?

tusharf5 commented 5 years ago

How do user set if certain version is outdated ? Can they decide if certain link is outdated ?

At first, I was just thinking of showing an announcement bar if the current version is not the latest. But if we want the user to set if a certain version is outdated or beta or something else. I think versions.json could be a good place. Something like

[
  "1.10.0",
  "1.9.0",
  "1.8.1",
  { 
     version: "1.7.x", 
     deprecated: true, 
     message: "This version has a security bug",  
     ...other attributes 
  },
  "1.6.x"
]

The announcement bar feature can be somewhat general feature too, not just for outdated docs.

Yes (something like a global modal component), and depending upon the announcement type (info, alert, notice) we could change the appearance a little.

I have a very little idea of the project structure and internals so I don't know how complex this would be or if it would make any sense at all.

yangshun commented 5 years ago

I don't really like the idea of bloating versions.json with more fields. Mixing types in an array is usually not a good idea also (we'll take in strings and objects)

I don't think we should pursue this currently for the following reasons:

Versioning in v2 is not yet ready, much less done
- If we're going for a snapshotting approach in v2, past versions are immutable and it'll be hard to inject this announcement in
- If the vulnerability was found in the current version, users can add it to their website, publish a version, then remove it in their new version, without it being a core feature of Docusaurus
Not worth working on this in v1 as it'll be more work to port this to v2

facebook / docusaurus