feat(v2): add a banner that links to latest version of documentation #2916

teikjun · 2020-06-10T10:32:52Z

Motivation

Add a badge that links older versions of documentation to the latest version of the documentation. This PR closes #2432.

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

After visiting the netlify preview site, go to any older version of the documentation . Check that there is a badge that links to the latest version
Click on the link to the latest version. There should be no badge next to the version number, since we are now at the latest version

The automated tests has been updated accordingly.

docusaurus-bot · 2020-06-10T10:36:34Z

Deploy preview for docusaurus-2 ready!

Built with commit 12ef010

https://deploy-preview-2916--docusaurus-2.netlify.app

slorber

Hi and thanks for your PR.

isOld and link to /docs is likely not reliable enough. It will work on basic D2 sites but will not work on sites that configure routeBasePath or have no homePageId

slorber · 2020-06-10T10:42:05Z

packages/docusaurus-theme-classic/src/theme/DocItem/index.js

@@ -115,6 +117,11 @@ function DocItem(props) {
 <span className="badge badge--secondary">
 Version: {version}
 </span>
+ {isOld ? (
+ <span className="badge badge--secondary margin-horiz--xs">
+ <Link to="/docs"> Go to latest version </Link>


The /docs url is configurable, so it's not a good idea to hardcode the link to /docs here, + there's no guarantee that the user used the docs "homePageId" feature.

See https://v2.docusaurus.io/docs/docs-introduction/#docs-only-mode

slorber · 2020-06-10T10:43:38Z

packages/docusaurus-plugin-content-docs/src/metadata.ts

@@ -145,6 +150,7 @@ export default async function processMetadata({
 lastUpdatedBy,
 lastUpdatedAt,
 sidebar_label,
+ isOld,


I think we should rather try to compute, for each doc, what's the permalink to the latest version of the same doc.

maybe we need a property like latestPermalink

some docs may get deleted in newer version of doc

In such case latestPermalink would be undefined, and you wouldn't add the link?

Ah that's right, you want to link to the docs root, not necessarily the same doc in another version, so this is probably overkill.

slorber · 2020-06-10T10:47:16Z

Hey @teikjun

I have this other PR with some changes to metadata.ts, just wanted to mention that so that we can avoid too much conflicts :)
#2905

slorber · 2020-06-10T11:06:59Z

Docs plugin: createDocsBaseMetadata(version) allows to pass data to the DocPage component, which is the layout component for a whole doc version.

I think we should add data here with a permalink to the latest docs homepage (not necessarily /docs, see routeBasePath)

But this is likely to conflict with my existing PR. You can make a POC, but can you wait before merging this?

lex111

Honestly, this current solution does not bear any benefit. As I understand it, we need to clearly inform the docs user that they is looking at outdated information, and also encourage they to use the latest version.

The link in "breadcrumbs" is almost invisible (and especially in dark mode looks ugly, IMO).

I think we should add something like that alert:

This way we inform the user clearly enough:

that they is viewing docs for an outdated version
we "urge" they to switch to the latest version of docs, thus prompting they to upgrade their website to the newest version of Docusaurus

Source code of snippet

<div class="alert alert--danger margin-bottom--md" role="alert">
  This is archived documentation for Docusaurus <strong>v2.0.0-alpha.50</strong>, which is no longer actively maintained.
  <br><br>For up-to-date documentation, see the <a href="#">latest version</a>.
</div>

teikjun · 2020-06-10T11:53:46Z

Thanks a lot for the reviews! We'll make a POC following @lex111's solution, and wait for #2905 before merging.

teikjun · 2020-06-11T10:18:41Z

Summary of Changes

Changed the small badge to a banner.
Replaced isOld with latestPermalink. latestPermalink will always link to the latest docs homepage.

Considerations
Regarding point 2, we considered linking older docs to the same doc in the latest version. But we couldn't find a good way to handle pages that have been renamed/deleted.
From our understanding, this requires looking up the list of currently available docs (so that we can link to latest homepage if the same doc does not exist). This would be less efficient compared to directly linking to homepage.

slorber

That almost looks good to me, but the /docs path does not always exist on all sites.

If there's no "docs home", maybe we should link to the first doc of the sidebar instead?

Subjective: I'd personally prefer a warning/orange than an error/red for the banner color.

slorber · 2020-06-11T10:29:01Z

packages/docusaurus-plugin-content-docs/src/metadata.ts

+ const latestPermalink =
+ version && version !== versioning.latestVersion
+ ? normalizeUrl([baseUrl, routeBasePath])
+ : undefined;


This is almost what we want :)

on D2 website, we have a docs homePageId, so the root is /docs

docs: { homePageId: 'introduction', path: 'docs',

But there are sites that do not have any docs home, it's the case for Watchman:

https://facebook.github.io/watchman/docs => 404

https://facebook.github.io/watchman/docs/install => this is the watchman home

For sites like Watchman without a doc at the root, we'd rather make sure that we don't link to a path that does not exist

teikjun · 2020-06-11T16:49:06Z

Summary of changes:

Link on the banner goes to first doc of sidebar instead of doc homepage
Changed banner color to warning orange

slorber

The algo should be more:

if there's a home doc id, the link should target that home doc id
else, link to the first document of the sidebar

slorber · 2020-06-12T15:31:49Z

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -461,6 +472,16 @@ Available document ids=
 Object.values(content.docsMetadata),
 'version',
 );
+ const rootUrl = getHrefFromSideBar(
+ content.docsSidebars[`version-${versioning.latestVersion}/docs`],
+ );


Unfortunately the root url is not necessarily the first doc of the sidebar. If the user used a homeDocumentId, we must use it in priority, even if it's not the first doc in the sidebar (even if users usually use the first doc of the sidebar as home documentId).

slorber · 2020-06-12T15:41:06Z

Hey,

I'd be fine if you fix the homeDocId problem to merge this PR.

Note, in the future it's probably needed we'll actually need to link to the same doc of the latest version, with a fallback to homeDocId, then firstDoc (of latest version)

This kind of behavior keeps being asked (yesterday here: #2923)

I think we'd need to provide some algo like

function getAllLinks(sidebarItems: DocsSidebarItem[]): SidebarItemLink[] {
 return flatten(sidebarItems.map(item => {
   if (sidebarItem.type === 'category') {
     return getAllLinks(sidebarItem.items);
   } else {
     return [sidebarItem.href];
   }
 }));
}

function getLatestDocsPermalink(links: SidebarItemLink[],preferedPaths: string[]): string | undefined {
 const existingPreferedPath = preferedPaths.find(preferedPath => {
   return links.some(link => link.href === preferedPath);
 })
 if ( existingPreferedPath ) {
   return existingPreferedPath;
 }
 else {
      return links[0]?.href;
 }
}

const docsLatestPermalink = getLatestDocsPermalink(latestSidebarData, [
  currentDocPath,
  homeDocIdPath
]);

This is really pseudo code, maybe you'll find it useful

slorber · 2020-06-12T15:55:29Z

Didn't try, but this could work fine:

      const latestHomeDoc = options.homePageId ? content.docsMetadata[options.homePageId] : undefined;
      let latestDocPermalink: string
      if ( latestHomeDoc ) {
        latestDocPermalink = latestHomeDoc.permalink;
      }
      else {
        latestDocPermalink = getHrefFromSideBar(
          content.docsSidebars[`version-${versioning.latestVersion}/docs`],
        );
      }

try to test with homePageId: 'notTheFirstDoc', and see if it works :)

slorber

That looks good to me

Just, what about renaming rootUrl/latestPermalink to something more explicit? like latestVersionMainDocPermalink

Also not fan of getHrefFromSideBar what about getFirstDocLinkOfSidebar?

slorber

Actually, there's a case where this fails, if the homeDocId selected does not exist in latest docs version.

As the "home" concept is currently not versioned, it is possible that the user selects a home that exists in next (ie /docs/next path will be created), but does not exist in current docs version (ie /docs will not be created)

Test with:

          homePageId: 'doesNotExist',

anshulrgoyal · 2020-06-12T16:59:44Z

Actually, there's a case where this fails, if the homeDocId selected does not exist in latest docs version.

As the "home" concept is currently not versioned, it is possible that the user selects a home that exists in next (ie /docs/next path will be created), but does not exist in current docs version (ie /docs will not be created)

Test with:
          homePageId: 'doesNotExist',

I have a fix, I will push changes

slorber · 2020-06-15T12:31:02Z

LGTM, merging as #2905 is not reviewed yet

slorber · 2020-06-18T14:14:48Z

Released in https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.58

Anshul Goyal and others added 6 commits June 10, 2020 11:47

feat(v2): add metadata to indicate the document is old

19301c9

feat(v2): add badge that links old versions to latest version

fb3e311

feat(v2): fix test related to metadata

4358f79

feat(v2): fix formatting

8aef76d

feat(v2): fix formatting

1629d92

feat(v2): use Link component instead of anchor tag

3239dff

teikjun requested review from lex111 and yangshun as code owners June 10, 2020 10:32

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 10, 2020

slorber requested changes Jun 10, 2020

View reviewed changes

lex111 suggested changes Jun 10, 2020

View reviewed changes

feat(v2): add pramlink to latest docs

7916468

Anshul Goyal and others added 5 commits June 10, 2020 17:28

feat(v2): add more vibrant warning message

2e89fde

feat(v2): position the banner above the article

c4b1159

feat(v2): link latest version to intro page

85ea598

fix(v2): fix some test cases

2d70251

feat(v2): fix tests

20b222f

teikjun requested review from slorber and lex111 June 11, 2020 10:21

slorber requested changes Jun 11, 2020

View reviewed changes

teikjun and others added 3 commits June 11, 2020 18:42

feat(v2): change banner to warning orange

f4a2fcd

feat(v2): compute root route from sidebar

32b7b07

style(v2): fix formatting

711dba8

teikjun requested a review from slorber June 11, 2020 16:53

teikjun changed the title ~~feat(v2): add a badge that links to latest version of documentation~~ feat(v2): add a banner that links to latest version of documentation Jun 11, 2020

slorber requested changes Jun 12, 2020

View reviewed changes

feat(v2): use homeid if provided to compute base route

d0f1ff3

teikjun requested a review from slorber June 12, 2020 15:58

slorber mentioned this pull request Jun 12, 2020

(v2) Make version switching to be aware of the current page #2923

Closed

slorber approved these changes Jun 12, 2020

View reviewed changes

slorber requested changes Jun 12, 2020

View reviewed changes

feat(v2): rename functions and fix a corner case

17c7e3a

anshulrgoyal force-pushed the teikjun/badge branch from 2fe191b to 17c7e3a Compare June 12, 2020 17:05

feat(v2): fix formating

4dfc06e

teikjun requested a review from slorber June 12, 2020 17:12

anshul and others added 3 commits June 12, 2020 22:55

feat(v2): compute homepageurl

10e7dd7

style(v2): improve code quality

373baf5

style(v2): unbold fullstop for consistency

12ef010

slorber merged commit 0c92f5a into facebook:master Jun 15, 2020

slorber added the pr: new feature This PR adds a new API or behavior. label Jun 17, 2020

slorber mentioned this pull request Jun 29, 2020

Upgrade Docusaurus v2 + try to fix Prism facebookresearch/hydra#730

Merged

eriveltonelias mentioned this pull request Jul 30, 2020

Allow defining which version is "unmaintained" on the banner #3169

Closed

snyk-bot mentioned this pull request Nov 3, 2021

[Snyk] Security upgrade workbox-build from 5.1.4 to 6.4.0 NikolayS/docusaurus#26

Open

NikolayS mentioned this pull request Apr 26, 2022

[Snyk] Security upgrade workbox-build from 5.1.4 to 6.4.0 NikolayS/docusaurus#37

Open

NikolayS mentioned this pull request Apr 29, 2024

[Snyk] Fix for 1 vulnerabilities NikolayS/docusaurus#205

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): add a banner that links to latest version of documentation #2916

feat(v2): add a banner that links to latest version of documentation #2916

teikjun commented Jun 10, 2020 •

edited

Loading

docusaurus-bot commented Jun 10, 2020 •

edited

Loading

slorber left a comment

slorber Jun 10, 2020

slorber Jun 10, 2020

anshulrgoyal Jun 10, 2020

slorber Jun 10, 2020

slorber commented Jun 10, 2020

slorber commented Jun 10, 2020 •

edited

Loading

lex111 left a comment

teikjun commented Jun 10, 2020

teikjun commented Jun 11, 2020 •

edited

Loading

slorber left a comment •

edited

Loading

slorber Jun 11, 2020

teikjun commented Jun 11, 2020 •

edited

Loading

slorber left a comment

slorber Jun 12, 2020

slorber commented Jun 12, 2020

slorber commented Jun 12, 2020 •

edited

Loading

slorber left a comment

slorber left a comment

anshulrgoyal commented Jun 12, 2020

slorber commented Jun 15, 2020

slorber commented Jun 18, 2020

feat(v2): add a banner that links to latest version of documentation #2916

feat(v2): add a banner that links to latest version of documentation #2916

Conversation

teikjun commented Jun 10, 2020 • edited Loading

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

docusaurus-bot commented Jun 10, 2020 • edited Loading

slorber left a comment

Choose a reason for hiding this comment

slorber Jun 10, 2020

Choose a reason for hiding this comment

slorber Jun 10, 2020

Choose a reason for hiding this comment

anshulrgoyal Jun 10, 2020

Choose a reason for hiding this comment

slorber Jun 10, 2020

Choose a reason for hiding this comment

slorber commented Jun 10, 2020

slorber commented Jun 10, 2020 • edited Loading

lex111 left a comment

Choose a reason for hiding this comment

teikjun commented Jun 10, 2020

teikjun commented Jun 11, 2020 • edited Loading

slorber left a comment • edited Loading

Choose a reason for hiding this comment

slorber Jun 11, 2020

Choose a reason for hiding this comment

teikjun commented Jun 11, 2020 • edited Loading

slorber left a comment

Choose a reason for hiding this comment

slorber Jun 12, 2020

Choose a reason for hiding this comment

slorber commented Jun 12, 2020

slorber commented Jun 12, 2020 • edited Loading

slorber left a comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

anshulrgoyal commented Jun 12, 2020

slorber commented Jun 15, 2020

slorber commented Jun 18, 2020

teikjun commented Jun 10, 2020 •

edited

Loading

docusaurus-bot commented Jun 10, 2020 •

edited

Loading

slorber commented Jun 10, 2020 •

edited

Loading

teikjun commented Jun 11, 2020 •

edited

Loading

slorber left a comment •

edited

Loading

teikjun commented Jun 11, 2020 •

edited

Loading

slorber commented Jun 12, 2020 •

edited

Loading