feat(v2): global data + useGlobalData + docs versions dropdown #2971

slorber · 2020-06-19T17:13:17Z

This PR implements the ability to switch from one doc version to the other, directly from the navbar, without loosing "context" (ie, the doc you are on):

To do this, some infra needed to be built:

docs plugin should be able to set some global data, that can be accessed by theme layout/navbar
client api should be able to access that global data from anywhere
docs plugin should provide convenient hooks to query the docs global data (ie global data shape is not direct api surface)
navbar should allow configuring custom item types (ie, a docsVersionDropdown type)
all this should be built with the future multi-instance plugins in mind

Relevant docs:

setGlobalData plugin action
global data client api (useGlobalData, usePluginData , useAllPluginInstancesData)
Custom docs version navbar items
plugin ids for multi-instance

Breaking changes:

themeConfig.navbar.links renamed to themeConfig.navbar.items (with custom error msg to help user)

docusaurus-bot · 2020-06-19T17:17:57Z

Deploy preview for docusaurus-2 ready!

Built with commit 525b0c2

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

This reverts commit f657b4c

# Conflicts: # packages/docusaurus-module-type-aliases/src/index.d.ts # packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts # packages/docusaurus-plugin-content-docs/src/index.ts # packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx # packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx # packages/docusaurus-theme-classic/src/theme/Layout/index.tsx # packages/docusaurus-theme-classic/src/theme/Navbar/index.tsx

…+ try to fix remaining merge bugs

… convert to TS

yangshun

I think global data is unavoidable. Gatsby's GraphQL schema is in fact global data which is queryable by every page.

Hence we need to introduce ways to make it more robust, possibly via namespacing. It'd be horrible if plugins overwrote each other's global data due to colliding keys.

I mentioned before that we want to allow multiple docs plugins in a website but the current versioning approach is global, which makes it impossible to do so. We should avoid the same mistake with global data.

# Conflicts: # packages/docusaurus-types/src/index.d.ts # packages/docusaurus/src/client/App.tsx # packages/docusaurus/src/server/index.ts

…name + plugin id

… navbar items

… instance id

yangshun

My only question is the renaming from links to items. Is it a necessary change? The helpful error message is super good though, so I'm not opposed to renaming.

yangshun · 2020-07-18T07:17:08Z

packages/docusaurus-theme-classic/src/themeConfigSchema.js

+    // TODO temporary (@alpha-58)
+    links: Joi.any().forbidden().messages({
+      'any.unknown':
+        'themeConfig.navbar.links has been renamed as themeConfig.navbar.items',


This is awesome

Thanks 😊

The renaming is not required but I think items makes more sense than links, now that navbar items have custom types.

I imagine we'd have more navbar item types in the future, including custom ones provided by the user, and maybe the ability for plugins to provide some

yangshun

Ship it!

slorber · 2020-07-21T09:15:55Z

thanks :)

slorber added 3 commits June 19, 2020 17:19

doc components initial simplification

ad5918e

doc components initial simplification

f657b4c

add docContext test

56c2c5c

slorber requested a review from lex111 as a code owner June 19, 2020 17:13

slorber marked this pull request as draft June 19, 2020 17:13

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

slorber added 8 commits June 24, 2020 15:29

Add poc of global data system + use it in the theme

8da1e31

Revert "doc components initial simplification"

1ad1629

This reverts commit f657b4c

revert useless changes

63170a1

avoid loosing context on docs switch

5154a52

fix docs tests

b244d88

fix @generated/globalData ts declaration / es import

23212db

typo

2e7ad2c

revert bad commit

f37ff02

slorber changed the title ~~docs version context~~ feat(v2): docs versioning data available globally Jun 24, 2020

slorber mentioned this pull request Jun 24, 2020

Dropdown with all versions #2492

Closed

slorber changed the title ~~feat(v2): docs versioning data available globally~~ feat(v2): global data + expose docs versioning data globally Jun 24, 2020

slorber requested a review from yangshun June 24, 2020 18:16

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

This was referenced Jul 1, 2020

[V2] Change mobile theme button behavior to enable page heading TOC #2220

Closed

Allow disabling or customizing the next version banner #3013

Closed

slorber added 6 commits July 1, 2020 16:04

refactor navbar in multiple parts + add navbar item types validation …

8d5efef

…+ try to fix remaining merge bugs

Merge branch 'master' into slorber/docs-version-context

912629d

add missing watch mode for plugin debug

8d33f49

fix docs global data integration, move related hooks to docs plugin +…

3d86758

… convert to TS

change versions link label

6518d28

yangshun reviewed Jul 6, 2020

View reviewed changes

Merge branch 'master' into slorber/docs-version-context

d0c2928

slorber added 9 commits July 16, 2020 13:04

Merge branch 'master' into slorber/docs-version-context

f766709

# Conflicts: # packages/docusaurus-types/src/index.d.ts # packages/docusaurus/src/client/App.tsx # packages/docusaurus/src/server/index.ts

fix bug preventing the deployment

8f32a34

refactor the global data system to namespace automatically by plugin …

1979949

…name + plugin id

proper NavbarItem comp

da2ccc3

fix tests

d4053b1

fix snapshot

7c4832d

extract theme config schema in separate file + rename navbar links to…

33e12c2

… navbar items

minor typos

2a5d834

polish docs components/api

c0f7fbf

slorber added the pr: breaking change Existing sites may not build successfully in the new version. Description contains more details. label Jul 16, 2020

slorber added 4 commits July 16, 2020 19:44

polish useDocs api surface

fe0d9b2

fix the docs version suggestions comp + data

d542764

refactors + add docsClientUtils unit tests

4162a6d

Add documentation

ad28572

slorber changed the title ~~feat(v2): global data + expose docs versioning data globally~~ feat(v2): global data + useGlobalData + navbar versions dropdown Jul 17, 2020

slorber changed the title ~~feat(v2): global data + useGlobalData + navbar versions dropdown~~ feat(v2): global data + useGlobalData + docs versions dropdown Jul 17, 2020

slorber added 3 commits July 17, 2020 18:08

typo

e67fbba

Add check for duplicate plugin ids detection

2731aad

multi-instance: createData plugin data should be namespaced by plugin…

e5a98a9

… instance id

slorber marked this pull request as ready for review July 17, 2020 17:42

remove attempt for multi-instance support

525b0c2

yangshun reviewed Jul 18, 2020

View reviewed changes

yangshun approved these changes Jul 21, 2020

View reviewed changes

slorber merged commit 15e73da into master Jul 21, 2020

yangshun deleted the slorber/docs-version-context branch July 26, 2020 12:36

slorber mentioned this pull request Aug 11, 2020

Error: Broken links found! facing on docusaurus build #3136

Closed

snyk-bot mentioned this pull request Jan 26, 2022

[Snyk] Security upgrade sharp from 0.25.4 to 0.29.3 NikolayS/docusaurus#31

Open

snyk-bot mentioned this pull request Jun 8, 2022

[Snyk] Security upgrade sharp from 0.25.4 to 0.29.3 NikolayS/docusaurus#41

Open

NikolayS mentioned this pull request Jun 21, 2023

[Snyk] Security upgrade sharp from 0.25.4 to 0.29.3 NikolayS/docusaurus#83

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): global data + useGlobalData + docs versions dropdown #2971

feat(v2): global data + useGlobalData + docs versions dropdown #2971

slorber commented Jun 19, 2020 •

edited

Loading

docusaurus-bot commented Jun 19, 2020 •

edited

Loading

yangshun left a comment

yangshun left a comment

yangshun Jul 18, 2020

slorber Jul 18, 2020

yangshun left a comment

slorber commented Jul 21, 2020

feat(v2): global data + useGlobalData + docs versions dropdown #2971

feat(v2): global data + useGlobalData + docs versions dropdown #2971

Conversation

slorber commented Jun 19, 2020 • edited Loading

docusaurus-bot commented Jun 19, 2020 • edited Loading

yangshun left a comment

Choose a reason for hiding this comment

yangshun left a comment

Choose a reason for hiding this comment

yangshun Jul 18, 2020

Choose a reason for hiding this comment

slorber Jul 18, 2020

Choose a reason for hiding this comment

yangshun left a comment

Choose a reason for hiding this comment

slorber commented Jul 21, 2020

slorber commented Jun 19, 2020 •

edited

Loading

docusaurus-bot commented Jun 19, 2020 •

edited

Loading