bug: (v4) markdown html `style` tags do not get converted to JSX compliant style tags
favna opened this issue · 2 comments
What package is the bug related to?
docusaurus-plugin-typedoc
Describe the issue
When this plugin encounters a README that uses HTML for layout such as padding styling here: https://github.com/sapphiredev/framework/blob/35b7e1674db4d3430b841494b9066b2f581f4f62/README.md?plain=1#L23 this does not get converted to JSX compliant CSS and put 1:1 in the index.mdx
file. Subsequently this causes build errors when running docusaurus build
(not when running docusaurus start
oddly enough). This is probably only a problem for the README file being picked up, because it is fairly safe to assume people wouldn't put div tags inside their TSDoc (I don't think that even works)
The error is:
✔ Client
Compiled successfully in 1.93m
✔ Server
[ERROR] Error: Unable to build website for locale en.
at tryToBuildLocale (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:53:19)
at async F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:64:9
at async mapAsyncSequential (F:\sapphiredev\website-main\node_modules\@docusaurus\utils\lib\jsUtils.js:20:24)
at async Command.build (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:62:5) {
[cause]: Error: Docusaurus static site generation failed for 1 paths:
- "/docs/Documentation/api-framework/"
at generateStaticFiles (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\ssg.js:85:15)
at async executeSSG (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:146:23)
... 4 lines matching cause stack trace ...
at async Command.build (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:62:5) {
[cause]: AggregateError
at generateStaticFiles (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\ssg.js:86:20)
at async executeSSG (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:146:23)
at async buildLocale (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:126:31)
at async tryToBuildLocale (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:46:13)
at async F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:64:9
at async mapAsyncSequential (F:\sapphiredev\website-main\node_modules\@docusaurus\utils\lib\jsUtils.js:20:24)
at async Command.build (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\commands\build.js:62:5) {
[errors]: [
Error: Can't render static file for pathname "/docs/Documentation/api-framework/"
at generateStaticFile (F:\sapphiredev\website-main\node_modules\@docusaurus\core\lib\ssg.js:119:15)
at runNextTicks (node:internal/process/task_queues:60:5)
at process.processImmediate (node:internal/timers:449:9)
at async F:\sapphiredev\website-main\node_modules\p-map\index.js:57:22 {
[cause]: Error: The `style` prop expects a mapping from style properties to values, not a string. For example, style={{marginRight: spacing + 'em'}} when using JSX.
at Fa (server.bundle.js:733032:49)
at K (server.bundle.js:733034:44)
at Ka (server.bundle.js:733037:184)
at Pa (server.bundle.js:733045:68)
at Xc (server.bundle.js:733078:32)
at Z (server.bundle.js:733083:89)
at Yc (server.bundle.js:733086:98)
at $c (server.bundle.js:733085:140)
at Z (server.bundle.js:733083:345)
at Xc (server.bundle.js:733078:476)
}
]
}
}
}
[INFO] Docusaurus version: 3.3.2
Node version: v20.12.2
TypeDoc configuration
[
'docusaurus-plugin-typedoc',
{
id: 'Framework',
entryPoints: ['./projects/framework/src/index.ts'],
tsconfig: './projects/framework/src/tsconfig.json',
readme: './projects/framework/README.md',
out: 'docs/Documentation/api-framework',
plugin: ['typedoc-plugin-mdn-links', 'typedoc-plugin-djs-links'],
includeVersion: true,
fileExtension: '.md',
excludeExternals: true,
expandParameters: true,
parametersFormat: 'table',
enumMembersFormat: 'table',
indexFormat: 'table'
}
],
Note
I also tried setting fileExtension
to .mdx
Expected behavior
The style tags get detected and converted to JSX compliant style so the site can build and render correctly.
What you need to do here is keep the .md
extension and add this to docusaurus.config
markdown: {
format: 'detect'
},
This will ask Docusaurus to parse as CommonMark (not mdx) and will fix the error.
https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark
Another tip (if you haven't worked it out) is to add this to your sidebar config. This will link the nav category item to the readme:
{
type: 'category',
link: {
type: 'doc',
id: 'Documentation/api-framework/index'
},
label: '@sapphire/framework',
items: require('./docs/Documentation/api-framework/typedoc-sidebar.cjs')
},
Thanks, that solution worked great!