milesj / docusaurus-plugin-typedoc-api Goto Github PK

I'm trying to determine how @category gets represented when the docs are generated. Ideally tagging entities with @category XXX would override the primitive kind (e.g. Class, Function, Interface etc) with value of @category. This seems to partially work. In the index for the package I'm able to re-map functions into Hooks but not classes into Components. Neither of these are represented in the sidebar.

// bar.ts

/**
 * @category Component
 */
export class Bar {}

/**
 * @category Hook
 */
export function useBar() {}

/**
 * @category Hook
 */
export function useFoo() {}

/**
 * @category Component
 */
export class Foo {}

// foo.ts

/**
 * @category Component
 */
export class Fizz {}

It would be awesome if it produced output that looked like:

When in polyrepo context, enabling readmes or changelogs make this webpack config include the whole project root, which makes docusaurus unhappy with the following:

SyntaxError: /Users/adamek/htdocs/apify/apify-client-js/docs/index.md: Identifier 'React' has already been declared. (32:396)
  30 | };
  31 |
> 32 | import _extends from"/Users/adamek/htdocs/apify/apify-client-js/website/node_modules/@babel/runtime/helpers/esm/extends.js";import _objectWithoutPropertiesLoose from"/Users/adamek/htdocs/apify/apify-client-js/website/node_modules/@babel/runtime/helpers/esm/objectWithoutPropertiesLoose.js";var _excluded=["components"];/* @jsxRuntime classic */ /* @jsx mdx */ /* @jsxFrag React.Fragment */import React from'react';import{mdx}from'@mdx-js/react';
     |                                                                                                                                                                                                                                                                                                                                                                                                             ^
  33 | export var frontMatter = {};
  34 | export var contentTitle = undefined;
  35 | export var toc = [];
    at parser.next (<anonymous>)
    at normalizeFile.next (<anonymous>)
    at run.next (<anonymous>)
    at transform.next (<anonymous>)
client (webpack 5.75.0) compiled with 1 error

Changing that include to the following helps on my end:

const include = packageConfigs.flatMap(cfg => [
    path__default.default.join(options.projectRoot, cfg.packagePath, options.readmeName),
    path__default.default.join(options.projectRoot, cfg.packagePath, options.changelogName),
]);

Will send a PR.

Issue

When I use Vercel they have some random path path0 in this case on the runner that builds the site. Which breaks the links cause now instead of my folder-name/package it is path0/package

Potential Solution

Ability to pass routeBasePath in config that take precedence over file-system root path.

Is it possible to add documentation for namespaces?

Clicking on the sidebar or any other hyperlink re-directs and jump to the section but it has some offset and often the title of the section gets behind the documentation header. Is this a known problem?

Github pages deployments have a base URL that is not /, which makes it impossible to use this plugin, as it requires the URL to be /api/. It seems like when adding the page, it should read the project's baseUrl and add it as a prefix to the pages it adds.

With the other docusaurus typedoc plugin, versioning worked automatically, as the api docs were just a folder with MD files. How can it work with this plugin?

Currently if the reference is not valid, it will be silently rendered as a regular text. Would be great to respect the docusaurus link validation hooks - onBrokenLinks and onBrokenMarkdownLinks. Maybe you could leverage the @docusaurus/Link component that handles this automatically (we extend this ourselves to do the versioned links to API docs from outside of it).

In our project, we use absolute path in our monorepo packages thanks to tsconfig-paths.
This doesn't allow us to use a common tsconfig file in the plugin configuration, because the absolute paths would not be resolved correctly.

A fix for us would be able to configure a different tsconfig file for each package:

plugins: [
    [
      'docusaurus-plugin-typedoc-api',
      {
        packages: [
          { path: 'packages/package-2', tsconfigName: 'packages/package-1/tsconfig.json' },
          { path: 'packages/package-1, tsconfigName: 'packages/package-2/tsconfig.json' },
        ],
      },
    ],
  ],

Do you think this could be possible ?
Would you like us to possibly work on this subject and propose a PR ?

When browsing non-latest version, we have this box with a link to the latest version, but its not working for a single package sites apparently, as it points to the /api route and not to the first package.

https://sdk.apify.com/api/next/apify

Might be good to make this warning box more in line with the one docusaurus uses, it looks like this nowadays:

Originally reported to typedoc, but after more debugging it looks like its a problem with the postprocessing. Looks like the JSON definition has changed in 0.23. Previosly the link macros were there intact, now they are provided as separate items in summary array.

with 0.22:

and with 0.23:

Currently a @default jsdoc tag is rendered this way:

Could we maybe do something like maxRequestRetries?: number = 3 instead?

I tried to adopt this plugin in MikroORM docs, and there is something wrong with the auto redirect from /api to the version. It works ok only for the current/next versions, but older versions get redirected to /api/4.5/4.5. I can see the redirect first goes to /api/4.5 which works (I see a flash of the sidebar with correct items) before it redirects further to /api/4.5/4.5.

It is definitely something with the local (browser) state and switching the versions. When I open https://mikro-orm.io/api/4.5 in anonymous windows, it works fine, but once you start switching versions it breaks.

Another minor issue I see is the root page with list of packages, for 4.5 it says the packages are v5.0.0, so it probably always takes the latest version on this page, even if I browser older one.

I was also thinking, maybe it would be possible to hijack the links on version dropdown if we are under the /api route? So if I am in the API docs, and use the version dropdown, it would go directly to API. Right now its always two clicks - select version and go back to API docs.

With excludeExternals: false we can get external symbols rendered in the docs. The code links (link to the code definition) are broken for such.

Example: https://crawlee.dev/api/next/core#log
Link goes to: https://undefined/apify/crawlee/blob/master/node_modules/@apify/log/index.d.ts#L8

We should probably not have the link at all, I am not sure there is a universal way to know where the actual symbol is defined (e.g. this also happens with internal node API, when extending things like EventEmitter here).

Hi @milesj!

I've noticed that the SourceLink component assumes that the source code to be linked to is on the master branch.

I'm happy to raise a PR to make it configurable, but I'm not sure what would be the best way to do it? Since DocusaurusConfig allows for organizationName and projectName, it would seem logical to have something like branchName in there, but that interface is not generic so that seems like a no-go. My second best bet seems to be global data, but I'm not sure if that's an idiomatic way to do it?

It's my first day playing around with Docusaurus, so any suggestions would be appreciated :-)

I just found out some links dont work with the regular @link macro (namely those to inherited properties) but with @apilink it works fine. So wanted to switch all the links to use @apilink, but now the logs are flooded with warnings from typedoc about every single link that uses it. Would be great if we could somehow let typedoc know those are fine.

Example from the logs:

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:311:95 - warning Encountered an unknown inline tag "@apilink"

311         * A reference to the underlying {@apilink RequestQueue} class that manages the crawler's {@apilink Request|requests}.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:317:38 - warning Encountered an unknown inline tag "@apilink"

317         * A reference to the underlying {@apilink SessionPool} class that manages the crawler's {@apilink Session|sessions}.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:317:94 - warning Encountered an unknown inline tag "@apilink"

317         * A reference to the underlying {@apilink SessionPool} class that manages the crawler's {@apilink Session|sessions}.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:323:38 - warning Encountered an unknown inline tag "@apilink"

323         * A reference to the underlying {@apilink AutoscaledPool} class that manages the concurrency of the crawler.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:324:70 - warning Encountered an unknown inline tag "@apilink"

324         * > *NOTE:* This property is only initialized after calling the {@apilink BasicCrawler.run|`crawler.run()`} function.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:326:40 - warning Encountered an unknown inline tag "@apilink"

326         * to pause the crawler by calling {@apilink AutoscaledPool.pause|`autoscaledPool.pause()`}

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:327:34 - warning Encountered an unknown inline tag "@apilink"

Is there any plan (or is it possible) to add the watch mode as typedoc has?

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 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 😕

With readmes: true we get the package's readme file rendered on the overview section, but the codeblocks are not highlighted. Its also visible in your boost package, e.g. here:

https://boostlib.dev/api/cli

Hey @milesj! It would be great if docusaurus-plugin-typedoc-api supported rendering information about the errors a method @throws

/**
 * @throws {@link UserError} if `max < min`
 */
export function rand(min: number, max: number): number;

At the moment, both @throws {CustomError} and @throws {@link CustomError} seem to be ignored.

When i try to run yarn docusaurus start on my project, i get the following error message:

[ERROR] Error: Cannot find module 'PROJECT_PATH/user-docs/documentation/.docusaurus/api-typedoc-default.json'
Require stack:
- PROJECT_PATH/node_modules/docusaurus-plugin-typedoc-api/lib/index.js
- PROJECT_PATH/node_modules/@docusaurus/core/lib/server/plugins/init.js
- PROJECT_PATH/node_modules/@docusaurus/core/lib/server/plugins/index.js
- PROJECT_PATH/node_modules/@docusaurus/core/lib/server/index.js
- PROJECT_PATH/node_modules/@docusaurus/core/lib/commands/build.js
- PROJECT_PATH/node_modules/@docusaurus/core/lib/index.js

I cloned the boost repository and i got the same error on master, after yarn docs
Do you encounter the same problem with those steps ?
If not, tell me which additional info you would like

Banner is added to plugin config under 'banner' property.

.docusaurus/docusaurus-plugin-typedoc-api/default/options.json
Contains {"banner":"Im a test banner",...}

Index page does not render banner above content.

I'm facing a strange behaviour where all the type properties are declared as optional even if they are mandatory. Here is one of my type aliases (it happens for all of them actually)

type Metadata = {
  BitsAllocated: number
  BitsStored: number
  SamplesPerPixel: number
  HighBit: number
  PhotometricInterpretation: string
  PixelRepresentation: number
}

which renders to

although I have noticed that option flag does not appear when minimal=false, so it is just the header that is wrong. I noticed it only happens for type aliases not interfaces

I've been testing out the versioning aspect of this plugin, and it works perfectly, with the only downside that it doesn't respect the selected version from docsVersionDropdown. 😢

I tried to implement it in ApiPage to redirect to the selected docs version, but I wasn't able to do it sadly... manually accessing the route works, so I could just automate it locally with fs, but that doesn't sound ideal

Any tips for how to handle this? 🙏 I'd love to contribute but I don't fully know where to look in docusaurus to get the version 😅

The h1 heading in changelog is rendered twice. I believe you are removing it dynamically somehow, as with different site it works, but for https://crawlee.dev/ it does not. I was working this around by hiding the element via css based on its ID, but with the recent update, that h1 element no longer has an ID.

https://crawlee.dev/api/core/changelog
https://github.com/apify/crawlee/tree/master/website

Note we have only one root changelog, that is symlinked to the packages/core folder.

https://github.com/apify/crawlee/blob/master/CHANGELOG.md

I also tried to manually add the ID to the h1 element, no luck there, it seems like the markdown processor removes it all the time.

After upgrading to 1.10 I'm getting the following error

Debug: Finished conversion in 990ms
Info: JSON written to ./.docusaurus/api-typedoc-default.json
Debug: JSON rendering took 225ms
[ERROR] TypeError: scopes.reduce is not a function

As we are getting closer to release, our API documentation is getting much bigger :) but recently I'm facing problems in the build regarding memory issues. I put the logs below. I can do cross-env NODE_OPTIONS=--max_old_space_size=10240 docusaurus build locally and it is fine, but netlify doesn't allow more than 6GB and fails miserably. I was wondering if you know such memory problems either in this plugin, or typedoc or in docusaurus.

$ docusaurus build
[INFO] [en] Creating an optimized production build...
Debug: Using TypeScript 4.5.5 from /Users/username/dev/myRepository/myRepository.git/docs/docs-remaining/node_modules/typescript/lib
Debug: Converting with 1 programs 3 entry points

<--- Last few GCs --->

[17231:0x1046c6000]   157771 ms: Mark-sweep (reduce) 4088.5 (4100.8) -> 4087.4 (4101.6) MB, 2121.0 / 0.0 ms  (average mu = 0.097, current mu = 0.006) allocation failure scavenge might not succeed
[17231:0x1046c6000]   159689 ms: Mark-sweep (reduce) 4088.4 (4100.8) -> 4087.3 (4101.8) MB, 1910.8 / 0.0 ms  (average mu = 0.053, current mu = 0.004) allocation failure scavenge might not succeed


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
 1: 0x1012e2ba5 node::Abort() (.cold.1) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 2: 0x1000a5cb9 node::Abort() [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 3: 0x1000a5e1f node::OnFatalError(char const*, char const*) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 4: 0x1001e83e7 v8::Utils::ReportOOMFailure(v8::internal::Isolate*, char const*, bool) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 5: 0x1001e8383 v8::internal::V8::FatalProcessOutOfMemory(v8::internal::Isolate*, char const*, bool) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 6: 0x100397275 v8::internal::Heap::FatalProcessOutOfMemory(char const*) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 7: 0x100398d3a v8::internal::Heap::RecomputeLimits(v8::internal::GarbageCollector) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 8: 0x100394409 v8::internal::Heap::PerformGarbageCollection(v8::internal::GarbageCollector, v8::GCCallbackFlags) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
 9: 0x100391ca1 v8::internal::Heap::CollectGarbage(v8::internal::AllocationSpace, v8::internal::GarbageCollectionReason, v8::GCCallbackFlags) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
10: 0x1003a053a v8::internal::Heap::AllocateRawWithLightRetrySlowPath(int, v8::internal::AllocationType, v8::internal::AllocationOrigin, v8::internal::AllocationAlignment) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
11: 0x1003a05c1 v8::internal::Heap::AllocateRawWithRetryOrFailSlowPath(int, v8::internal::AllocationType, v8::internal::AllocationOrigin, v8::internal::AllocationAlignment) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
12: 0x10036df67 v8::internal::Factory::NewFillerObject(int, bool, v8::internal::AllocationType, v8::internal::AllocationOrigin) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
13: 0x1006ecca8 v8::internal::Runtime_AllocateInYoungGeneration(int, unsigned long*, v8::internal::Isolate*) [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
14: 0x100a795f9 Builtins_CEntry_Return1_DontSaveFPRegs_ArgvOnStack_NoBuiltinExit [/Users/username/.nvm/versions/node/v14.15.0/bin/node]
15: 0x36102225ddde 
error Command failed with signal "SIGABRT".

I just joined the users for your plugin, first of all great work! it looks amazing.

Immediate thing that caught my attention was that when the names are long, the layout just gets crazy and breaks into new line. Can we have a check for long strings to truncate after some number of letters?

I have a long scope string and long package name which results in the following unfortunate render.
I was wondering whether it is possible to define an alias for packages when passed in the docusaurus config?

See this page for example: https://apify.github.io/apify-ts/api/apify/namespace/utils#requestAsBrowser

The signature includes RequestAsBrowserOptions interface that is defined on the same page, and there is no link to it. It looks like it works only for symbols that have their dedicated page.

Hi @milesj and thanks for your awesome work on this plugin! I'm planning to use it to generate API docs for Serenity/JS.
I came across an issue with symbol references I was hoping you could help me with, though.

Consider the following code sample:

class Student {
}

/**
 * A place for {@link Student}
 */
class Classroom {
}

The way I understand Typedoc docs on symbol references, {@link Student} should be rendered as a hyperlink to the Student class.

Instead, it doesn't seem to be interpreted at all:

I've tried with {@link Student}, {@apilink Student} and {@doclink Student}, unfortunately, all with the same result.

I've then gone through Boost docs, to find this piece of code using @link. However, I see it doesn't get rendered on the website either:

I haven't found any examples of linking to symbols, so I'd be grateful for any suggestions on how to get them to work.

This issue seems to be similar to #30; Interestingly enough, @doclink works correctly when specifying a link to a documentation page, so it's just @link and @apilink that don't seem to behave.

Thanks!

You're hardcoding SourceLinks to point to github.com.

my repos are accessible on a self hosted gitea instance, you should probably add an option to define the link base per package (link base ex: https://{domain}/{user}/{repo}).

Currently the packages are ordered alphabetically, which often results in not so good UX, as often the very first package will be some small CLI package that is not really important in terms of API docs. I would like to have some control over this, especially for the sidebar, but ideally it should affect the list of packages (https://crawlee.dev/api) too.

We have multiple packages that have their own docs, is this something that the plugin could handle including as a result of configuring API generation for these packages?

[
    'docusaurus-plugin-typedoc-api',
    {
      projectRoot: path.join(__dirname, '..', '..', '..'),
      packages: [{
        path: 'packages/foo',
        entry: 'addon/'
        includeMarkdown: ['docs/*.md']
      }]
    }
  ]

Is it possible to publish the react components as a separate package?

Hi @milesj!

Consider the following configuration of a package which describes three entry points: index , adapters and events:

    plugins: [
        [
            'docusaurus-plugin-typedoc-api',
            {
                packages: [
                    {
                        path: 'packages/core',
                        entry: {
                            index: { label: 'index', path: 'src/index.ts' },
                            adapter: { label: 'Test runner adapter', path: 'src/adapter/index.ts' },
                            events: { label: 'Domain Events', path: 'src/events/index.ts' },
                        },
                    },

It seems like docusaurus-plugin-typedoc-api sorts those entry points alphabetically based on the src attribute instead of relying on the order in which the configuration keys are defined (which would be my preference).

This results in the following issues:

Sidebar

Additional entry points, so adapter and events, are rendered before the main (index) entry point in the sidebar:

I'd prefer for them to be listed alphabetically together with other groups, so "Domain Events" after "Answerables" and "Test runner adapter" after "Domain Events". Alternatively, the additional exports could be listed at the end of the list too.

Incorrect link from /api

The link to the module listed on the /api page is incorrect as it leads to the first entry point the plugin has detected (so /api/core-adapter) instead of the main one - /api/core:

Proposed solution

It would be great if docusaurus-plugin-typedoc-api considered the order in which keys are defined in the configuration object to be the preferred sorting order. This way I could define index entry point as first and have both the above issue solved (I think).

Hey @milesj!

It seems like @link, @apiLink and [[...]] have a slightly inconsistent behaviour, so I thought I'd summarise it here.

In short, using @link with descriptions works fine when linking to classes in other modules of my monorepo, but fails when used to link to classes in the same module.

Would you say it's fair to conclude that using @apiLink is preferable over @link? Or am I missing something?

Also, would you expect {@apiLink MyClass} to work when used in Docusaurus docs? Or should a regular markdown link be used instead?

Thanks!

Hey @milesj! It could be useful for docusaurus-plugin-typedoc-api to support Docusaurus admonitions to draw readers' attention to specific points in the API docs.

For example:

class Actor {

    /**
     * Returns a human-readable string representation of this actor and their properties.
     *
     * :::tip
     * To get the name of the actor, use [[Actor.name]] instead.
     * :::
     */
    toString(): string { /* ... */ }

}

At the moment, the admonition is rendered as regular text.

Hey @milesj, so here's an interesting bug I'm not yet sure how we should fix.

Consider a mono-repo (e.g. boost) with the following directory structure:

So all the modules have the same "root" called packages.

Now, when TypeDoc parses the source code of such monorepo, it determines a fileName property of each JSONOutput.SourceReference. To do that, TypeDoc uses a function called getCommonDirectory.

This function generates fileName as relative path from that common directory. Which means that, since the common root of all the above modules is packages, TypeDoc drops the packages subdir from the fileName. So for example you'd get fileName equal args/src/index.ts instead of packages/args/src/index.ts.

This then means that all the SourceLinks generated by docusaurus-plugin-typedoc-api are invalid, because they're missing the packages subdir.

- https://github.com/serenity-js/serenity-js/blob/main/core/src/Serenity.ts#L43          // actual
+ https://github.com/serenity-js/serenity-js/blob/main/packages/core/src/Serenity.ts#L43 // expected

You might be wondering, how is it possible that this works for Boost?
Well, I've been wondering the same thing myself.

Turns out that when we inspect the sources loaded by TypeDoc for Boost, we'll notice that apart from all the modules under packages, TypeDoc also loads node_modules/@types/debug/index.d.ts:

    "/Users/jan-molak/Projects/boost/packages/args/src/index.ts",
    "/Users/jan-molak/Projects/boost/packages/debug/src/index.ts",
    "/Users/jan-molak/Projects/boost/packages/debug/src/test.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/ArgsError.ts",
    "/Users/jan-molak/Projects/boost/packages/internal/dts/createScopedError.d.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/constants.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/format.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/parse.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/ParseError.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/parseInContext.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/types.ts",
    "/Users/jan-molak/Projects/boost/packages/args/src/ValidationError.ts",
    "/Users/jan-molak/Projects/boost/packages/debug/src/CrashReporter.ts",
    "/Users/jan-molak/Projects/boost/packages/debug/src/createDebugger.ts",
    "/Users/jan-molak/Projects/boost/packages/debug/src/types.ts",
    "/Users/jan-molak/Projects/boost/node_modules/@types/debug/index.d.ts"        // <--

Since @types/debug lives outside packages, getCommonDirectory returns /Users/jan-molak/Projects/boost instead of /Users/jan-molak/Projects/boost/packages so the relative path works, but only by accident.

To reproduce the issue, you could modify the docusaurus.config.js in this project and leave only those modules that don't depend on external types, e.g. args and common:

const local = {
	projectRoot: path.join(__dirname, '../../boost'),
	gitRefName: 'main',
	packages: [
		...[
			'args',
			'common',
			
		].map((pkg) => `packages/${pkg}`),
		// remove the rest
	],
};

Notice the invalid link:

- https://github.com/facebook/docusaurus/blob/master/common/src/ModulePath.ts#L12
+ https://github.com/facebook/docusaurus/blob/master/packages/common/src/ModulePath.ts#L12

It feels like this TypeDoc behaviour is intentional and probably something that docusaurus-plugin-typedoc-api should work around, what do you think?

I'm not sure where would be the best place to attack it, though.

I've been trying to get this plugin working for my library simple-obs, and have only had moderate success. When specifying packages in the plugin's settings, putting only one of the two packages that are present in the monorepo will successfully generate API documentation for that package, but putting both packages results in no documentation being generated.

It appears that TypeDoc is analysing both packages successfully, since the generated JSON file contains information on both packages, but the plugin does not create the pages for the website. If you clone simple-obs, you should just be able to yarn and yarn start in the website directory and have the same results occur.

Currently breakcrumbs just show the nesting, but are not clickable. While its understandable that we dont have any page for "Classes" or "Functions", we definitely can have a link for the root/package name, as that can go to the overview page.

Here I would expect the @crawlee/core link to the overview page of that package, so https://crawlee.dev/api/core.

This package currently only allows to work in a monorepo setup. I am trying to play around with this to generate API docs for graphql-js. How can I use this in a standalone repo? If you can guide how I can help with this change.

Hi there, trying to use this plugin instead of https://github.com/tgreyuk/typedoc-plugin-markdown, the output looks much better, but there are some gotchas:

• polyrepo mode is not working for me, namely this condition always returns false
  • our use case is with custom entry point (src/exports.ts) as the index file can't be used (it contains default export which messes up the typedoc structure)
  • basically the comment here is exactly right, but i have no idea what you meant by that - one side of the equation is src/exports.ts and the other exports.ts, what is the purpose of the basename call? seems like this can only work for deep imports
• {@link} tags are not working at all, this is also crucial for us

I will be happy to help with fixing those, especially if you could point me in the right direction.

If we use links inside JSDoc, we can either use regular markdown links or the @link macro. The latter can be used only to link to other symbols defined in the API docs, right? So in case we want to link to the documentation part, we need markdown links. Only way I was able to make them work was by using absolute links (e.g. /docs/abc'). Those links are then not converted once new version is tagged, and they don't respect the "next" version either, they are absolute so they always point to the very same page.

We got around this via custom ApiLink component from inside the regular documentation files that respects current version, but we also need the same in the other direction - linking to versioned docs from inside the API docs. Can you think of a way to handle this?

I noticed that some of the inline codeblocks are not rendered, namely those that are inside markdown tables.

This is the table definition inside jsdoc of a class (source)

 * ## Supported Configuration Options
 *
 * Key | Environment Variable | Default Value
 * ---|---|---
 * `defaultDatasetId` | `APIFY_DEFAULT_DATASET_ID` | `'default'`
 * `defaultKeyValueStoreId` | `APIFY_DEFAULT_KEY_VALUE_STORE_ID` | `'default'`
 * `defaultRequestQueueId` | `APIFY_DEFAULT_REQUEST_QUEUE_ID` | `'default'`
 * `localStorageDir` | `APIFY_LOCAL_STORAGE_DIR` | `'./apify_storage'`
 * `localStorageEnableWalMode` | `APIFY_LOCAL_STORAGE_ENABLE_WAL_MODE` | `true`
 * `persistStateIntervalMillis` | `APIFY_PERSIST_STATE_INTERVAL_MILLIS` | `60e3`
 * `token` | `APIFY_TOKEN` | -

Note that it does work for lists, few lines under this code is a list with items as codeblocks and that renders just fine.

One of the API docs pages fails to render with this error. Can you suggest a way to debug this? I checked the typedoc.json, and didn't find ID 21 there, but not sure what it should be referring to and from where it is linked.

PendingNavigation.js?eb1e:48 Error: Unable to find declaration with ID 21
    at Object.useReflection (useReflection.ts?314f:13)
    at ApiItem (ApiItem.tsx?6edc:87)
    at renderWithHooks (react-dom.development.js?61bb:14985)
    at mountIndeterminateComponent (react-dom.development.js?61bb:17811)
    at beginWork (react-dom.development.js?61bb:19049)
    at HTMLUnknownElement.callCallback (react-dom.development.js?61bb:3945)
    at Object.invokeGuardedCallbackDev (react-dom.development.js?61bb:3994)
    at invokeGuardedCallback (react-dom.development.js?61bb:4056)
    at beginWork$1 (react-dom.development.js?61bb:23964)
    at performUnitOfWork (react-dom.development.js?61bb:22779)
    at workLoopSync (react-dom.development.js?61bb:22707)
    at renderRootSync (react-dom.development.js?61bb:22670)
    at performSyncWorkOnRoot (react-dom.development.js?61bb:22293)
    at eval (react-dom.development.js?61bb:11327)
    at unstable_runWithPriority (scheduler.development.js?3069:468)
    at runWithPriority$1 (react-dom.development.js?61bb:11276)
    at flushSyncCallbackQueueImpl (react-dom.development.js?61bb:11322)
    at flushSyncCallbackQueue (react-dom.development.js?61bb:11309)
    at scheduleUpdateOnFiber (react-dom.development.js?61bb:21893)
    at Object.enqueueSetState (react-dom.development.js?61bb:12467)
    at PendingNavigation.Component.setState (react.development.js?72d0:365)
    at eval (PendingNavigation.js?eb1e:48)
eval @ PendingNavigation.js?eb1e:48
Promise.catch (async)
shouldComponentUpdate @ PendingNavigation.js?eb1e:48
checkShouldComponentUpdate @ react-dom.development.js?61bb:12525
updateClassInstance @ react-dom.development.js?61bb:13039
updateClassComponent @ react-dom.development.js?61bb:17432
beginWork @ react-dom.development.js?61bb:19073
beginWork$1 @ react-dom.development.js?61bb:23940
performUnitOfWork @ react-dom.development.js?61bb:22779
workLoopSync @ react-dom.development.js?61bb:22707
renderRootSync @ react-dom.development.js?61bb:22670
performSyncWorkOnRoot @ react-dom.development.js?61bb:22293
eval @ react-dom.development.js?61bb:11327
unstable_runWithPriority @ scheduler.development.js?3069:468
runWithPriority$1 @ react-dom.development.js?61bb:11276
flushSyncCallbackQueueImpl @ react-dom.development.js?61bb:11322
flushSyncCallbackQueue @ react-dom.development.js?61bb:11309
discreteUpdates$1 @ react-dom.development.js?61bb:22420
discreteUpdates @ react-dom.development.js?61bb:3756
dispatchDiscreteEvent @ react-dom.development.js?61bb:5889

Hello!

I've recently deployed a website with your plugin, but I've encountered a strange issue with numeric enum members: https://discord-api-types.dev/api/next/discord-api-types-v10/enum/ActivityFlags#Embedded

The source code for the website is visible at https://github.com/discordjs/discord-api-types, in the website folder

For some reason, reflection.type is undefined in this case. Could it be an issue with the JSON I made? Is there an easy fix for this?

Thanks!

Hi,

I am using this plugin to generate API docs for a mono repo. There is one concern I could not resolve, the types reference across mono-repo packages are not linked.

There is a typeodc plugin for this purpose, which is loaded but not performs what's expected.
https://github.com/luizstacio/typedoc-monorepo-link-types

When we have following snippet.

// packages/package-1/src/index.ts

import {BaseClass} from 'package-2';

class ExtendedClass extends BaseClass { }

The docs for the ExtendedClass under hierarchy section does not link the BaseClass.

If we use the @link for those imported types these works fine.

// packages/package-1/src/index.ts

import {BaseClass} from 'package-2';

/**
* {@link BaseClass}
*/
class ExtendedClass extends BaseClass { }

In above snippet the @link modifier works fine and points to the right package in the API docs. That means the type info is available but not rendered properly. This seems to be a very basic behavior for a mono-repo packages.

Is there some configuration to enable this or is it a bug?

Hello!

I'm currently trying to use this module here https://github.com/discordjs/discord-api-types/tree/chore/docs-site/website, but the website can never load due to a mismatch between what the generated routes.js has for paths and what routesChunkNames.json has.

I'm running version 2.0.0-beta.14 of docusaurus, and 1.7.0 of your plugin.

As you can see from the attached screenshot, the escape characters seem to be wrong. I don't know if this is an issue in docusaurus or in your plugin, and I'd love to help debug this further, but I also don't know how to solve this.
On the left is the json, on the right is the routes.js

As well as that, I find it weird that it's separated by a backwards slash rather than a forwards one (so you'd end up with /api/:slug? rather than /api\:slug?

Is there anything I can do to solve this? Do you know where to look for this?
Thanks!

Hi, I'm looking around for the tools to enable me generate api documentation for my typescript library. I came across this repo and also the docusaurus-plugin-typedoc.

Is it possible to let me know what is the difference between these two?

Thanks