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

Known issues upgrading to Docusaurus 3.4 #1780

Open
josh-padnick opened this issue Jun 18, 2024 · 1 comment
Open

Known issues upgrading to Docusaurus 3.4 #1780

josh-padnick opened this issue Jun 18, 2024 · 1 comment

Comments

@josh-padnick
Copy link
Contributor

I attempted to upgrade to Docusaurus 3.4, but hit too many roadblocks and ran out of time. I wanted to document what I've learned are some known issues with upgrading.

  • Upgrading dependencies. Docusaurus docs recommends updating a handful of dependencies, but we use dependencies beyond that and there are multiple yarn warnings when you run yarn install. So we need to figure out how to handle all the updated dependencies. I attempted this in ebaf937, however I am not confident that I did this correctly.
  • Fix ES module import syntax. In some cases, we needed to update the ES module import syntax. I fixed one example in b339762.
  • Adopt breaking API changes. In some cases, there were breaking API changes that required trivial, but non-obvious code changes. See 49081d2.
  • Fix MDX markdown strict rendering. The biggest source of issues was that we have both docs-site native content, and content pulled in from all our Library repos. All of this content must be compatible with MDX v3, so using simple expressions like { "a": "b" } without the ` marks surrounding it will throw errors. I fixed the native docs site content in 74e14b9, but in order to fix the generated content, we need to make direct updates in the Libary (like this one). And then I found that docs-sourcer doesn't always parse those updates correctly.
@josh-padnick
Copy link
Contributor Author

@ZachGoldberg I think this is worth doing at some point. Could you take the lead from here? For now, I'll work on the current version of the docs site.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant