-
Notifications
You must be signed in to change notification settings - Fork 242
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
[V3] Improved Docusaurus 3 compatibility #677
Conversation
Hi @Gijsdeman thanks for the PR, it's likely Docusaurus introduced some breaking change in 3.0.1. Will need to debug to determine the root cause. |
I found out that I forgot to update some of the Docusaurus dependencies to Updating these dependencies fixed the problem. Also, the versioned API documentation sidebar now works correctly. |
@sserrata I also looked into updating the demo to make full use of the improved TypScript support of Docusaurus 3. Docusaurus indicates that TypeScript |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @Gijsdeman was this possibly checked in by mistake?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, sorry. Let me remove it from the commit and fix the prettier
issues.
@Gijsdeman concerning the latest
After that, run |
Thanks. For some reason I also had to change the |
Visit the preview URL for this PR (updated for commit 9381c8b): https://docusaurus-openapi-36b86--pr677-kuhyatrz.web.app (expires Fri, 12 Jan 2024 00:25:11 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if upgrading packages introduced a change to our eslint/prettier rules? Before, we were not requiring comma dangle. It's not a huge issue but it is changing a lot of files unnecessarily.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point. I can add "trailingComma" : "none"
to .prettierrc.json
to keep the behaviour as it was before.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
By the way, thanks so much for all the effort - really appreciated 🙏🏽 !
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this actually made it worse. I do not think prettier enforced this rule at all in the past, so either way around there will be a lot of files changed.
I think "trailingComma": "es5"
might be what we want, but I will have to look at that again next week. Sorry!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll investigate further if I have time today. Either way, thanks!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Trailing Commas: Default value changed from es5 to all in v3.0.0
I changed and indeed no files are changed because of trailing commas, which indeed caused a lot less files to be changed due to the prettier
upgrade (in total 15 files compared to the ~90 earlier).
It looks like these changes are not due to the trailing comma, but due to some other minor changes in prettier (see packages/docusaurus-theme-openapi-docs/src/theme/ParamsItem/index.js and packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Response/_Response.scss for example).
Hi @Gijsdeman, just finished stepping through the recent changes and reviewed the deploy preview. LGTM! |
Description
Improved escaped descriptions and headers, introduced typing for sidebars.
Motivation and Context
Fixes some of the issues mentioned in #654:
The first two items are pretty much required for a proper Docusaurus 3 support. The last one introduces typed sidebars which has improved support in Docusaurus 3.
There is one issue which I am unsure to fully resolve. HTML sidebar items are broken in Docusaurus 3.0.0 and hence an upgrade to 3.0.1 was needed to make sure versioned sidebars function as expected. However, this now introduces an
Hook is called outside the <DocProvider>
error, which I am unable to replicate in other projects (this error seems to be caused by the@theme/ApiItem
in the docusaurus config file).How Has This Been Tested?
Tested by hand, using personal OpenAPI specifications.
Types of changes
Checklist