Scoped packages (e.g. @ds/package1) cause Docusaurus 404s

[sstone1]

I have several packages I'm trying to generate documentation for.

These packages are all scoped, so in my case have names starting with "@ds/".

I am using the following Docusaurus config with this plugin:

  plugins: [
    [
      'docusaurus-plugin-typedoc',
      {
        packages: [
          '/Users/Simon.Stone/git/monorepo/packages/package1', (@ds/package1)
          '/Users/Simon.Stone/git/monorepo/packages/package2', (@ds/package2)
          '/Users/Simon.Stone/git/monorepo/packages/package3' (@ds/package3)
        ]
      }
    ]
  ]

It works fine and seems to generate all of the expected Markdown files.

The problem is that all of the files are prefixed with an underscore _, and Docusaurus returns 404 when I to visit any of them. This is using docusaurus start so it's not a GitHub Pages + Jekyll thing, although the behaviour is similar.

The files I get look like:

docs/api/classes/_ds_package1.SomeClass.md
docs/api/interfaces/_ds_package1.SomeInterface.md
docs/api/modules/_ds_package1.md

I assume the prefixed _ is the replacement for the @ in the scoped package name.

I also get warnings from Docusaurus about unresolvable links:

warn Docs markdown link couldn't be resolved: (modules/_ds_package1.md) in /Users/Simon.Stone/git/monorepo/docs/api/modules.md for version current

If I remove the prefixed _ from the file names and fix up the links, things start to work, but it's not ideal!

Any ideas? Sorry if I've made something confusing whilst trying to obscure package names and such.

[tgreyuk]

hello.. i have had a quick look to try and replicate but will need a bit more time. I don't suppose your repo is public by any chance?

[sstone1]

@tgreyuk sorry for the delay, I've put together a repository that works in the same way as our internal repository: https://github.com/sstone1/typedoc-plugin-markdown-issue-248

git clone https://github.com/sstone1/typedoc-plugin-markdown-issue-248.git
cd typedoc-plugin-markdown-issue-248
npm install
npm run doc

You'll find all the files created start with an underscore, which will cause Docusaurus to ignore them:

% find docs -type f
docs/classes/_ds_package_b.Thing.md
docs/classes/_ds_package_a.Thing.md
docs/modules.md
docs/README.md
docs/modules/_ds_package_a.md
docs/modules/_ds_package_b.md

[tgreyuk]

@sstone1 thanks for detailed repo and apologies it took so long to get around to this one. typedoc-plugin-markdown@3.11.2 will remove the leading underscores.

The syntax for packages in typedoc 0.22 is now:

[
      'docusaurus-plugin-typedoc',
      {
        entryPoints: ['../packages/package-a', '../packages/package-b'],
        entryPointStrategy: 'packages',
      },
    ],

Let me know if you still have issues.

[sstone1]

Thanks @tgreyuk, just tried it locally and it works perfectly!