[microsite] Use Docusaurus@canary #17549
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: blam <[email protected]>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Signed-off-by: blam <[email protected]>
Signed-off-by: blam <[email protected]>
benjdlambert
force-pushed
the
blam/fix-microsite-build
branch
from
5b4aada to
79edc8e
Compare
Signed-off-by: blam <[email protected]>
| 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
Member
There was a problem hiding this comment.
Nice, is this perhaps a replacement for scripts/pre-build.js ?
Member
Author
There was a problem hiding this comment.
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.
2 tasks
jhaals
approved these changes
Apr 28, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 definedwhen 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