bug: (v4) markdown html `style` tags do not get converted to JSX compliant style tags

favna commented 6 months ago

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.

tgreyuk commented 6 months ago

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')
 },

favna commented 6 months ago

Thanks, that solution worked great!

typedoc2md / typedoc-plugin-markdown