-
Notifications
You must be signed in to change notification settings - Fork 5.6k
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
[microsite] Use Docusaurus@canary #17549
Conversation
Signed-off-by: blam <ben@blam.sh>
Signed-off-by: blam <ben@blam.sh>
Signed-off-by: blam <ben@blam.sh>
5b4aada
to
79edc8e
Compare
Signed-off-by: blam <ben@blam.sh>
microsite/docusaurus.config.js
Dismissed
markdown: { | ||
preprocessor({ filePath, fileContent }) { | ||
// Replace all HTML comments with emtpy strings as these are not supported by MDXv2. | ||
return fileContent.replace(/<!--.*?-->/gs, ''); |
Check failure
Code scanning / CodeQL
Incomplete multi-character sanitization High
<!--
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.
Nice, is this perhaps a replacement for scripts/pre-build.js
?
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.
Yep - now html docs are not supported anywhere, so I just strip them everywhere rather than just the API docs. But we can of course still write comments where needed, as we do have some examples where we need them.
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.
Love it
Ok - Controversial I know, but thinking that it could be good.
Right now the microsite is broken because of the MDX parser @v1 which is used in Docusarus, which means that when people write API doc comments, they get converted into Markdown and then get parsed by the MDX parser. There's been a few cases where PR's have broken the microsite as we don't build the microsite for any API doc changes.
facebook/docusaurus#8288 was merged recently, which switches MDX@1 to MDX@2 which gives us many benefits, performance, and better parsing, which means that we can be more confident with doc changes moving forward and they wont break our microsite.
It's also got some pre-processing in here, so we can strip HTML comments (which aren't supported at all in MDX2) in one place and do it cleanly in the loader config for all .md files rather than just the docs/reference like before.
The
<!-- prettier-ignore -->
is an unfortunate side effect that{/* truncate */}
gets converted to{/_ truncate _/}
which is not what we want.Microsite is currently broken with the error message
ReferenceError: pluginId is not defined
when parsing the generated API docs for the newFrontendHostDiscovery
. So it's basically when it's parsing this:backstage/packages/core-app-api/src/apis/implementations/DiscoveryApi/FrontendHostDiscovery.ts
Line 37 in 1c907ad
And
backstage/packages/core-app-api/src/apis/implementations/DiscoveryApi/FrontendHostDiscovery.ts
Line 46 in 1c907ad