Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 37 commits into from
Jul 21, 2020

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented Jun 19, 2020

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):

image

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:

Breaking changes:

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

@slorber slorber requested a review from lex111 as a code owner June 19, 2020 17:13
@slorber slorber marked this pull request as draft June 19, 2020 17:13
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 19, 2020
@docusaurus-bot
Copy link
Contributor

docusaurus-bot commented Jun 19, 2020

Deploy preview for docusaurus-2 ready!

Built with commit 525b0c2

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

@slorber slorber changed the title docs version context feat(v2): docs versioning data available globally Jun 24, 2020
@slorber slorber changed the title feat(v2): docs versioning data available globally feat(v2): global data + expose docs versioning data globally Jun 24, 2020
@slorber slorber requested a review from yangshun June 24, 2020 18:16
@slorber slorber added the pr: new feature This PR adds a new API or behavior. label Jun 24, 2020
# 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
Copy link
Contributor

@yangshun yangshun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@slorber 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 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 slorber changed the title feat(v2): global data + useGlobalData + navbar versions dropdown feat(v2): global data + useGlobalData + docs versions dropdown Jul 17, 2020
@slorber slorber marked this pull request as ready for review July 17, 2020 17:42
Copy link
Contributor

@yangshun yangshun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is awesome

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@yangshun yangshun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ship it!

@slorber
Copy link
Collaborator Author

slorber commented Jul 21, 2020

thanks :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: breaking change Existing sites may not build successfully in the new version. Description contains more details. pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants