Rendering readmes breaks with Docusaurus 2.2.0

[jan-molak]

Hey @milesj!

It looks like docusaurus-plugin-typedoc-api doesn't work with Docusaurus 2.2.0 when readmes are set to true.

// docusaurus.config.js
plugins: [
        [
            'docusaurus-plugin-typedoc-api',
            {
                readmes: true,
                // other config that doesn't affect the outcome

Running Docusaurus results with the below error, even though I'm not using Mermaid:

Finished conversion in 2400ms
JSON written to ./.docusaurus/api-typedoc-default.json
JSON rendering took 167ms
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

● Client █████████████████████████ building (46%) 2/3 entries 1322/1334 dependencies 172/478 modules 192 active 
 json|/Users/jan/Projects/serenity-js/serenity-js/documentation/serenity-js.org/.docusaurus/docusaurus-plugin-changelog/default/changelog-page-7-bde.json

[ERROR] TypeError: Cannot read properties of undefined (reading 'mermaid')
    at Object.mdxLoader (/Users/jan/Projects/serenity-js/serenity-js/node_modules/@docusaurus/mdx-loader/lib/loader.js:115:43)
    at LOADER_EXECUTION (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:132:14)
    at runSyncOrAsync (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:133:4)
    at iterateNormalLoaders (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:251:2)
    at iterateNormalLoaders (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:240:10)
    at /Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:255:3
    at context.callback (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:124:13)
    at Object.markdownLoader (/Users/jan/Projects/serenity-js/serenity-js/node_modules/docusaurus-plugin-typedoc-api/lib/markdownLoader.js:7:19)
    at LOADER_EXECUTION (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:132:14)
    at runSyncOrAsync (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:133:4)
    at iterateNormalLoaders (/Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:251:2)
    at /Users/jan/Projects/serenity-js/serenity-js/node_modules/loader-runner/lib/LoaderRunner.js:224:4
    at /Users/jan/Projects/serenity-js/serenity-js/node_modules/webpack/lib/NormalModule.js:834:15
    at Array.eval (eval at create (/Users/jan/Projects/serenity-js/serenity-js/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:12:1)
    at runCallbacks (/Users/jan/Projects/serenity-js/serenity-js/node_modules/enhanced-resolve/lib/CachedInputFileSystem.js:27:15)
    at /Users/jan/Projects/serenity-js/serenity-js/node_modules/enhanced-resolve/lib/CachedInputFileSystem.js:200:4
    at /Users/jan/Projects/serenity-js/serenity-js/node_modules/graceful-fs/graceful-fs.js:123:16
    at FSReqCallback.readFileAfterClose [as oncomplete] (node:internal/fs/read_file_context:68:3)
[INFO] Docusaurus version: 2.2.0
Node version: v16.17.1

When readmes are set to false the website starts up correctly.

Steps to reproduce

You should be able to see the same error in boost after upgrading all the Docusaurus modules to 2.2.0 and enabling readmes.

Root cause

I'm not sure what the exact root cause is, but here's what I found out so far:

• Docusaurus 2.2.0 introduced built-in support for Mermaid in feat: support mermaid code blocks in Markdown facebook/docusaurus#7490
• This feature relies on a configuration property markdown.mermaid that @docusaurus/mdx-loader assumes is available
• When Docusarus Webpack invokes docusaurus-plugin-typedoc-api markdownLoader, the loading process blows up as reqOptions.markdownConfig is undefined, and therefore reqOptions.markdownConfig.mermaid is an invalid reference.

Interestingly enough, all the other .md and .mdx files are processed correctly and it's only the readmes that break it.

This leads me to believe that in order to be compatible with Docusaurus 2.2.0, docusaurus-plugin-typedoc-api needs to somehow populate the default configuration values for markdownConfig.

Unfortunately, I'm not sure where this would need to be done.

Adding {markdown:{mermaid:false}} to docusaurus.config.js did not resolve the issue, so I'm not sure how the config object passed to the loader is determined 😕

[jan-molak]

@B4nan - I wonder if you'd get the same error on Crawlee with Docusaurus 2.2.0? I think you're using readmes, aren't you?

[B4nan]

Yes, we have multiple sites set up this way and I was debugging the exact same issue today with one of them.

[milesj]

Thanks for the report, will look into tonight!

[milesj]

I believe this fixes it https://github.com/milesj/docusaurus-plugin-typedoc-api/pull/80/files#diff-a6a085138505e7ad124af8df6353efa6ec96cd337a74d0a522070bb2e4af0c53R389

[milesj]

Published, let me know if it doesn't work.

[B4nan]

Perfect, works like a charm, thanks!

[jan-molak]

Fab, thanks @milesj! Have a coffee on me ☕