typedoc2md / typedoc-plugin-markdown

A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.
https://typedoc-plugin-markdown.org
MIT License
725 stars 177 forks source link

Dead links when `useCodeBlocks: true` #536

Closed elringus closed 10 months ago

elringus commented 10 months ago

Description

When useCodeBlocks is enabled, some pages are not generated causing dead links. When typedoc-plugin-markdown is not used, the pages are generated, so it doesn't seem to be a typedoc issue.

Tested typedoc-plugin-markdown version: 4.0.0-next.39.

Repro

  1. Clone https://github.com/elringus/imgit/tree/157689cbc3c8914dff9d32c96bb91d3c126c44a7
  2. Run following:
    • cd docs
    • npm i
    • npm run docs:api
  3. Notice docs/api/plugin/astro/type-aliases/AstroIntegration.md file is generated
  4. Change useCodeBlocks to true in docs/scripts/api.sh
  5. Run npm run docs:api
  6. Notice docs/api/plugin/astro/type-aliases/AstroIntegration.md is missing

Expected

docs/api/plugin/astro/type-aliases/AstroIntegration.md is generated when useCodeBlocks is enabled

Note

AstroIntegration is not the only file that is missing, run npm run docs:build for the full list.

tgreyuk commented 10 months ago

Hello and thank you for such a clear description and associated repo.

If you update to 1.0.0-next.6 these issues should be fixed.

I also noticed that you were attempting to tweak a few bits to the output that can actually be accomplished with existing TypeDoc options.

In addition I have added an additional collapsed option to the VitePress sidebar object.

This is what my new api.sh looks like with v1.0.0-next.6:

echo '{
    "entryPoints": [
        "../src/server/index.ts",
        "../src/plugin/youtube/index.ts",
        "../src/plugin/svg.ts",
        "../src/plugin/astro.ts",
        "../src/plugin/vite.ts"
    ],
    "tsconfig": "../src/tsconfig.json",
    "hideBreadcrumbs": true,
    "useCodeBlocks": true,
    "out": "api",
    "textContentMappings": {
        "title.indexPage": "API Reference",
        "title.memberPage": "{name}",
    },
    "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],

    "githubPages": false,
    "readme": "none",
    "hideGenerator": true,
    "sidebar": {
        "collapsed": false
    }

}' > typedoc.json

typedoc
elringus commented 10 months ago

Thank you so much for the fast fix and the example! It's now all working perfectly. I've actually hacked the sidebar collapse because it used to show expand icons next to items that couldn't be expanded, but it seems to be fixed now as well. The plugin is brilliant, thanks again!