typedoc2md/typedoc-plugin-markdown

Sidebar 'typedoc-sidebar.cjs' is generated with backward slashes instead of forward slashes

Closed this issue · 3 comments

ultimate commented

What package is the bug related to?

docusaurus-plugin-typedoc

Describe the issue

Summary

Introduced with version 1.0.3 the typedoc-sidebar.cjs is generated with \\ in the path resulting in an error "sidebar document ids do not exist". With version 1.0.2 everything works fine.

Details

We are using the docusaurus-plugin-typedoc to generate markdown documentation from source. This also automatically generates a typedoc-sidebar.cjs.

With version 1.0.2 the sidebar looked like this:

// @ts-check
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const typedocSidebar = { items: [{"type":"category","label":"Variables","items":[
    {"type":"doc","id":"api-references/viewer/variables/emitter","label":"emitter"}
]}]};
module.exports = typedocSidebar.items;

With version 1.0.3 the sidebar ids contain \\:

// @ts-check
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const typedocSidebar = { items: [{"type":"category","label":"Variables","items":[
    {"type":"doc","id":"api-references\\viewer/variables/emitter","label":"emitter"}
]}]};
module.exports = typedocSidebar.items;

Although the sidebar file is created, the build fails after that with the error:

[ERROR] Error: Invalid sidebar file at "config/sidebars.js".
These sidebar document ids do not exist:

  • api-references\viewer/variables/emitter

Available document ids are:

  • README
  • api-references/viewer/globals
  • api-references/viewer/index
  • api-references/viewer/variables/emitter
    at Object.checkSidebarsDocIds (C:\Dev\viewer\node_modules@docusaurus\plugin-content-docs\lib\sidebars\utils.js:181:19)
    at addDocNavigation (C:\Dev\viewer\node_modules@docusaurus\plugin-content-docs\lib\docs.js:206:19)
    at doLoadVersion (C:\Dev\viewer\node_modules@docusaurus\plugin-content-docs\lib\index.js:106:55)
    at async loadVersion (C:\Dev\viewer\node_modules@docusaurus\plugin-content-docs\lib\index.js:113:28)
    at async Promise.all (index 0)
    at async Object.loadContent (C:\Dev\viewer\node_modules@docusaurus\plugin-content-docs\lib\index.js:121:33)
    at async C:\Dev\viewer\node_modules@docusaurus\core\lib\server\plugins\index.js:35:25
    at async Promise.all (index 0)
    at async loadPlugins (C:\Dev\viewer\node_modules@docusaurus\core\lib\server\plugins\index.js:34:27)
    at async load (C:\Dev\viewer\node_modules@docusaurus\core\lib\server\index.js:76:58)

Note that the id is otherwise correct, just the / vs. \ after api-references is different.

Reverting docusaurus-plugin-typedoc to 1.0.2 in package-json resolves the issue.

Please let me know if the description is not enough and you need more information.

TypeDoc configuration

snippet from site-config.js

[
      'docusaurus-plugin-typedoc',
      {
        entryPoints: ['../../src/core/api.ts'],
        tsconfig: '../../tsconfig.json',
        out: 'docs/api-references/viewer',
        excludePrivate: true,
        excludeProtected: true,
        excludeInternal: true,
        disableSources: true,
        gitRevision: 'main',
      },
]

Expected behavior

Page ids generated in typedoc-sidebar.cjs should be valid and match existing ids. They should not contain backward slashes when ids are otherwise only containing forward slashes.

tgreyuk commented

Thanks - Should be fixed in docusaurus-plugin-typedoc@1.0.4

  • 👍1
ultimate commented

@tgreyuk : awesome. Works like a charm. Thank you for the immediate fix 😄

Should I close the issue or will you do?

tgreyuk commented

Ok great - i'll close it (but feel free to close in future). thanks.

  • 👍1