knodescommunity / typedoc-plugins Goto Github PK

View Code? Open in Web Editor NEW

21.0 3.0 4.0 4.04 MB

A monorepo containing all knodes-published TypeDoc plugins

Home Page: https://knodescommunity.github.io/typedoc-plugins/

License: MIT License

CSS 0.20% JavaScript 18.57% Shell 0.84% TypeScript 80.39%

typedoc typedocplugin typedoc-plugin typescript documentation documentation-generator

typedoc-plugins's People

Contributors

Stargazers

Watchers

Forkers

danieldspx whenderson stonecypher arundo

typedoc-plugins's Issues

TypeError: Cannot read properties of undefined (reading 'scope')

HI, getting next error with latest version of 'monorepo-readme' package

TypeError: Cannot read properties of undefined (reading 'scope')
    at MarkdownToSummary.processFromString (/Users/eldar/xxx/node_modules/.pnpm/@[email protected][email protected]/node_modules/@knodes/typedoc-pluginutils/dist/markdown-to-summary.js:59:35)
    at PageEvent.pageEvent.template (/Users/eldar/xxx/node_modules/.pnpm/@[email protected][email protected]/node_modules/@knodes/typedoc-plugin-monorepo-readmes/dist/plugin.js:75:57)
    at defaultLayout xx(/Users/eldar/x/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/themes/default/layouts/default.js:29:23)
    at DefaultThemeRenderContext.defaultLayout (/Users/eldar/xxx/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/themes/default/DefaultThemeRenderContext.js:32:22)
    at DefaultTheme.defaultLayoutTemplate (/Users/eldar/xxx/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/themes/default/DefaultTheme.js:30:53)
    at DefaultTheme.render (/Users/eldar/xxx/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/themes/default/DefaultTheme.js:175:37)
    at Renderer.renderDocument (/Users/eldar/xxx/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/renderer.js:169:40)
    at /Users/eldar/xxx/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/renderer.js:148:22
    at Array.forEach (<anonymous>)
    at Renderer.render (/Users/eldar/xxx/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/renderer.js:146:25)

[Feature]: Allow putting pages under namespaces (that are in same list as modules in generated documentation)

Plugin

@knodes/typedoc-plugin-pages

What would you want ?

Example repo: https://github.com/Hi-Fi/typedoc-plugins-example/tree/external_pages

When documentation is generated, external page can only be put at main level, not under "module" (which is actually namespace).

If trying to put page under module_2, it's not possible as it's not with moduleRoot as that produces error:

Error: Invalid pages configuration: could not find a workspace named "module_2"

And if just adding empty page, that would duplicate module_2 in list.

`lodash` is declared as a peer dependency

The installation documentation of e.g. the typedoc-plugin-pages package says:

npm install --save-dev @knodes/typedoc-plugin-pages typedoc@^0.22.0

However this is not sufficient since lodash is declared as a peer dependency. This means that if a project does not have lodash installed, the plugin will crash.

I am also questioning the motivation behind having lodash as a peer dependency, especially for a server-side only module.

In any case, thanks for the great plugins.

Getting "repo.getLineNumberAnchor is not a function" after typedoc update

Plugin

@knodes/typedoc-plugin-monorepo-readmes

Typedoc plugin(s) version(s)

^0.23.1

Typedoc version

0.23.18

Describe the problem


TypeDoc exiting with unexpected error:
TypeError: repo.getLineNumberAnchor is not a function
    at Object.createSourceReference (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/@[email protected][email protected]/node_modules/@knodes/typedoc-pluginutils/dist/utils/reflection-source.js:49:32)
    at MonorepoReadmePlugin._modifyModuleIndexPage (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/@[email protected][email protected]/node_modules/@knodes/typedoc-plugin-monorepo-readmes/dist/plugin.js:61:68)
    at Renderer.<anonymous> (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/@[email protected][email protected]/node_modules/@knodes/typedoc-plugin-monorepo-readmes/dist/plugin.js:32:30)
    at triggerEvents (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/utils/events.js:191:43)
    at triggerApi (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/utils/events.js:167:13)
    at eventsApi (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/utils/events.js:60:18)
    at Renderer.trigger (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/utils/events.js:389:13)
    at Renderer.renderDocument (/Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/renderer.js:151:14)
    at /Users/eldar/WebstormProjects/or-sdk-next/node_modules/.pnpm/[email protected][email protected]/node_modules/typedoc/dist/lib/output/renderer.js:135:22
    at Array.forEach (<anonymous>)

What did you expected ?

Expecting no errors

UPD:
[email protected] - still works
[email protected] - broken

Refering pages

Plugin

@knodes/typedoc-plugin-pages

Typedoc plugin(s) version(s)

@knodes/[email protected]

Typedoc version

0.23.15

Describe the problem

I was previously using typedoc-plugin-pages and refering pages seems not working or differently.
Before:

{@page <page title>}

Now:

{@page <path-to-file>}

Question: how do we refer pages from within the source code?
I tried different solutions to refer .md files but unsuccessfully

What did you expected ?

Be able to refer pages based on pages titles, from md files and from source code

[Bug]: @page reference doesn't seem to work

Plugin

@knodes/typedoc-plugin-code-blocks

Typedoc plugin(s) version(s)

@knodes/typedoc-plugin-pages": "^0.23.1

Typedoc version

typedoc": "^0.23.27

Describe the problem

Created a simple structure like this:

pages
    |--- test.md
    |----test2.md

In my typedoc.json, I specified "readme": "./pages/test.md"

My plugin config is just:

    "pluginPages": {
      "pages": [
        { "title": "test", "source": "test.md" }
      ]
    }

When I run typedoc, I get:

error [@knodes/typedoc-plugin-pages]: MarkdownPagesLinks ⇒ In "pages/test.md:3:1 (in expansion of @page)", could not resolve page "./test2.md[Test" from reflection test

All I am trying to do is that I have a set of existing MD files (about 30 of them) which have explanations of core topics for the package. They live under ./docs but I changed that to ./pages b/c it seems like that's what this plugin wants?

Those markdown (before) just had regular md links like [Test](./test.md), but that style of link doesn't seem to work here.

Any ideas what I'm doing wrong?

What did you expected ?

I expect to be able to have my own existing markdown files, which reference other markdown files in the same folder.

[Bug]: Crash "Error: Could not set option "pluginPages:pages": Every root pages should set `moduleRoot` to true, or none" when `pages` is empty array

Plugin

@knodes/typedoc-plugin-pages

Typedoc plugin(s) version(s)

@knodes/[email protected]

Typedoc version

0.23.10 (happens on 0.23.8 too)

Describe the problem

I'm running typedoc like that:
typedoc src/index.ts --out docs --includeVersion --pluginPages ./pagesconfig.json

and when pages property in my pages.config is empty, like that:

{
    "pages": [],
    "source": "tutorials"
}

This plugin crashes typedoc like that:

$ typedoc src/index.ts --out docs --includeVersion --pluginPages ./pagesconfig.json
Loaded plugin @knodes/typedoc-plugin-pages
TypeDoc exiting with unexpected error:
Error: Could not set option "pluginPages:pages": Every root pages should set `moduleRoot` to true, or none
    at /Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:144:31
    at /Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:160:34
    ... 2 lines matching cause stack trace ...
    at OptionGroup._setValue (/Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:137:34)
    at OptionGroup._setValueFromFile (/Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:118:18)
    at OptionGroup._setValue (/Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:133:22)
    at /Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:37:22
    at /Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/events-extra.js:69:13
    at Options.instance.<computed> (/Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/events-extra.js:102:29) {
  [cause]: AssertionError [ERR_ASSERTION]: Every root pages should set `moduleRoot` to true, or none
      at Object.validate (/Projects/bottom-line/node_modules/@knodes/typedoc-plugin-pages/dist/options/build.js:82:30)
      at Object.5 (/Projects/bottom-line/node_modules/typedoc/dist/lib/utils/options/declaration.js:146:26)
      at convert (/Projects/bottom-line/node_modules/typedoc/dist/lib/utils/options/declaration.js:184:60)
      at Options.setValue (/Projects/bottom-line/node_modules/typedoc/dist/lib/utils/options/options.js:167:53)
      at Option.setValue (/Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option.js:56:41)
      at /Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:141:27
      at /Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:160:34
      at Array.map (<anonymous>)
      at OptionGroup._mapOptions (/Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:160:14)
      at OptionGroup._setValue (/Projects/bottom-line/node_modules/@knodes/typedoc-pluginutils/dist/options/option-group.js:137:34) {
    generatedMessage: false,
    code: 'ERR_ASSERTION',
    actual: 0,
    expected: 1,
    operator: '=='
  }
}
error Command failed with exit code 6.

What did you expected ?

I use a template for my libraries, I'm having empty pages array by default, with a plan to add some pages when they are ready (which usually don't happen too early in the stage of creating somthing).

I'd like this plugin just not to inject anything as a page when there is nothing defined and just silently continue the process of building the docs.

Implement a theme based on the typedoc default theme compatible with those plugins

Related to needs of #100

[Bug]: Code Blocks no longer work with typedoc 0.23.28

Plugin

@knodes/typedoc-plugin-code-blocks

Typedoc plugin(s) version(s)

@knodes/[email protected]

Typedoc version

0.23.28

Describe the problem

TypeDoc can't expand code blocks anymore. Instead, when I run typedoc, I get an error repeated many times (once for each @codeblock):

error [@knodes/typedoc-plugin-code-blocks]: MarkdownCodeBlocks ⇒ In "FILE/PATH.md:r:c (in expansion of @codeblock)", failed to render code block from PAGE NAME: TypeError: Cannot read properties of undefined (reading 'GitHub').

The docs do build, but none of the @codeblocks are expanded and just appear in the docs as plain text.

I think the problem is that the plugin imports RepositoryType from typedoc, but typedoc no longer exports such a member… This is just a guess, however, and I'm struggling to find an older version of Typedoc that does export RepositoryType…

What did you expected ?

I was expecting the @codeblocks to be expanded correctly in the docs, as was the case with older versions.

I did consider using an older version to get this to work, but then I end up unable to use kindSortOrder, navigationLinks and sidebarLinks and I can't find a combination of versions for this plugin and TypeDoc where everything work correctly…

Tooling improvements

Release script should skip CI for docs branch
Release script should clone the docs branch without history
Sync proto should make sure the typedoc submodule version matches the dependency in package.json
Run precommit as part of CI tests to check behavior on windows & macos. Only use the version in .nvmrc
Sync nvmrc with circleci default version
Parallelize plugins test suites and merge lcov results
Sync packages & versions with github issue templates

[Feature]: Allow anchors in @page

Plugin

@knodes/typedoc-plugin-pages

What would you want ?

I want to link to a specific part of the page. Each header in markdown creates an anchor, so I can send a link to a friend to a given section of a page, like:
http://127.0.0.1:8082/pages/tutorials/03events.html#task_add

now I want to link to this specific part of the page from a {@page} link, i tried using {@page 02advanced.md#Something-something Title} but it doesn't work.

Something like that would be appreciated. I know hash is a valid character for a filename - there are few approaches to that:

first try full file name, if not found look for hash - if found use the left part as a file name - if it's valid then create a link to the page and append the hash part
Add a optional hash parameter between the file path and title. This will prevent possibility of the title from starting with hash however, but maybe an escaping can be added here if really needed.
something else, that will be breaking change in one-in-the-million case only?

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Warning

These dependencies are deprecated:

Datasource	Name	Replacement PR?
npm	`@types/concurrently`
npm	`@types/marked`

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

Detected dependencies

circleci

.circleci/config.yml

node 5.2.0

node 5.2.0

git-submodules

.gitmodules

typedoc master@415c819bc97bd8ac48817d42891b17460b81f59a

npm

package.json

@alex_neo/jest-expect-message ^1.0.5

@commitlint/cli ^17.0.2

@commitlint/config-conventional ^17.0.2

@knodes/eslint-config ^1.6.5

@testing-library/jest-dom ^5.16.4

@types/concurrently ^7.0.0

@types/diff ^5.0.2

@types/fs-extra ^11.0.0

@types/jest ^29.0.0

@types/js-beautify ^1.13.3

@types/jsdom ^21.0.0

@types/lodash ^4.14.182

@types/lunr ^2.3.4

@types/marked ^4.0.2

@types/minimatch ^5.0.0

@types/mock-fs ^4.13.1

@types/node ^18.0.0

@types/react ^18.0.14

@types/semver ^7.3.9

@types/tmp ^0.2.3

@typescript-eslint/eslint-plugin ^5.28.0

@typescript-eslint/parser ^5.28.0

concurrently ^8.0.0

conventional-changelog-cli ^3.0.0

cross-env ^7.0.3

diff ^5.1.0

eslint ^8.18.0

eslint-plugin-eslint-comments ^3.2.0

eslint-plugin-import ^2.26.0

eslint-plugin-jsdoc ^39.3.3

eslint-plugin-prefer-arrow ^1.2.3

eslint-plugin-sort-export-all ^1.2.2

expect-type ^0.16.0

format-package ^7.0.0

fs-monkey ^1.0.3

glob ^10.0.0

husky ^8.0.1

jest ^29.0.0

jest-cli ^29.0.0

jest-extended ^4.0.0

jest-junit ^16.0.0

js-beautify ^1.14.0

jsdom ^21.0.0

lodash ^4.17.21

lunr ^2.3.0

markdownlint-cli ^0.36.0

marked ^4.0.12

memfs ^3.4.1

minimatch ^9.0.0

nyc ^15.1.0

rimraf ^5.0.0

run-script-os ^1.1.6

semver ^7.3.5

tmp ^0.2.1

ts-jest ^29.0.0

type-fest ^3.0.0

typedoc ^0.23.28

typescript ^5.0.0

unionfs ^4.4.0

yaml ^2.1.1

fastest-levenshtein ^1.0.16

typedoc ^0.23.0

packages/plugin-code-blocks/package.json

lodash ^4.17.21

@knodes/eslint-config ^1.6.5

@testing-library/jest-dom ^5.16.4

@types/jest ^29.0.0

@types/jsdom ^21.0.0

@types/lodash ^4.14.182

@types/node ^18.0.0

@types/react ^18.0.14

@typescript-eslint/eslint-plugin ^5.28.0

@typescript-eslint/parser ^5.28.0

eslint ^8.18.0

eslint-plugin-eslint-comments ^3.2.0

eslint-plugin-import ^2.26.0

eslint-plugin-jsdoc ^39.3.3

eslint-plugin-prefer-arrow ^1.2.3

eslint-plugin-sort-export-all ^1.2.2

jest ^29.0.0

jest-extended ^4.0.0

jest-junit ^16.0.0

jsdom ^21.0.0

rimraf ^5.0.0

ts-jest ^29.0.0

typedoc ^0.23.28

typescript ^5.0.0

@types/minimatch ^5.0.0

@types/marked ^4.0.2

@types/mock-fs ^4.13.1

conventional-changelog-cli ^3.0.0

typedoc ^0.23.0

minimatch ^5.1.0 || ^8.0.0 || ^9.0.0

packages/plugin-pages/package.json

lodash ^4.17.21

@knodes/eslint-config ^1.6.5

@testing-library/jest-dom ^5.16.4

@types/jest ^29.0.0

@types/jsdom ^21.0.0

@types/lodash ^4.14.182

@types/node ^18.0.0

@types/react ^18.0.14

@typescript-eslint/eslint-plugin ^5.28.0

@typescript-eslint/parser ^5.28.0

eslint ^8.18.0

eslint-plugin-eslint-comments ^3.2.0

eslint-plugin-import ^2.26.0

eslint-plugin-jsdoc ^39.3.3

eslint-plugin-prefer-arrow ^1.2.3

eslint-plugin-sort-export-all ^1.2.2

jest ^29.0.0

jest-extended ^4.0.0

jest-junit ^16.0.0

jsdom ^21.0.0

rimraf ^5.0.0

ts-jest ^29.0.0

typedoc ^0.23.28

typescript ^5.0.0

@types/fs-extra ^11.0.0

@types/lunr ^2.3.4

conventional-changelog-cli ^3.0.0

type-fest ^3.0.0

typedoc ^0.23.0

lunr ^2.3.0

packages/plugintestbed/package.json

lodash ^4.17.21

memfs ^3.4.1

unionfs ^4.4.0

@knodes/eslint-config ^1.6.5

@testing-library/jest-dom ^5.16.4

@types/jest ^29.0.0

@types/jsdom ^21.0.0

@types/lodash ^4.14.182

@types/node ^18.0.0

@types/react ^18.0.14

@typescript-eslint/eslint-plugin ^5.28.0

@typescript-eslint/parser ^5.28.0

eslint ^8.18.0

eslint-plugin-eslint-comments ^3.2.0

eslint-plugin-import ^2.26.0

eslint-plugin-jsdoc ^39.3.3

eslint-plugin-prefer-arrow ^1.2.3

eslint-plugin-sort-export-all ^1.2.2

jest ^29.0.0

jest-extended ^4.0.0

jest-junit ^16.0.0

jsdom ^21.0.0

rimraf ^5.0.0

ts-jest ^29.0.0

typedoc ^0.23.28

typescript ^5.0.0

@types/js-beautify ^1.13.3

fs-monkey ^1.0.3

js-beautify ^1.14.0

typedoc ^0.23.0

packages/pluginutils/package.json

lodash ^4.17.21

fastest-levenshtein ^1.0.16

semver ^7.3.5

@knodes/eslint-config ^1.6.5

@testing-library/jest-dom ^5.16.4

@types/jest ^29.0.0

@types/jsdom ^21.0.0

@types/lodash ^4.14.182

@types/node ^18.0.0

@types/react ^18.0.14

@typescript-eslint/eslint-plugin ^5.28.0

@typescript-eslint/parser ^5.28.0

eslint ^8.18.0

eslint-plugin-eslint-comments ^3.2.0

eslint-plugin-import ^2.26.0

eslint-plugin-jsdoc ^39.3.3

eslint-plugin-prefer-arrow ^1.2.3

eslint-plugin-sort-export-all ^1.2.2

jest ^29.0.0

jest-extended ^4.0.0

jest-junit ^16.0.0

jsdom ^21.0.0

rimraf ^5.0.0

ts-jest ^29.0.0

typedoc ^0.23.28

typescript ^5.0.0

@alex_neo/jest-expect-message ^1.0.5

@types/semver ^7.3.9

@types/tmp ^0.2.3

conventional-changelog-cli ^3.0.0

expect-type ^0.16.0

tmp ^0.2.1

type-fest ^3.0.0

typedoc ^0.23.0

tools/proto/package.json

lodash ^4.17.21

@knodes/eslint-config ^1.6.5

@testing-library/jest-dom ^5.16.4

@types/jest ^29.0.0

@types/jsdom ^21.0.0

@types/lodash ^4.14.182

@types/node ^18.0.0

@types/react ^18.0.14

@typescript-eslint/eslint-plugin ^5.28.0

@typescript-eslint/parser ^5.28.0

eslint ^8.18.0

eslint-plugin-eslint-comments ^3.2.0

eslint-plugin-import ^2.26.0

eslint-plugin-jsdoc ^39.3.3

eslint-plugin-prefer-arrow ^1.2.3

eslint-plugin-sort-export-all ^1.2.2

jest ^29.0.0

jest-extended ^4.0.0

jest-junit ^16.0.0

jsdom ^21.0.0

rimraf ^5.0.0

ts-jest ^29.0.0

typedoc ^0.23.28

typescript ^5.0.0

typedoc ^0.23.0

nvm

.nvmrc

node 18.20.2

Check this box to trigger a request for Renovate to run again on this repository

pluginutils: Allow specifying a list of matches to ignore from markdown replacer

See

plugin-pages: @page for any file

Hi!
Is its possible to add a link to page for not described pages in config?

example:
I want to add the link to my change-log file at the bottom of readme, i have around 40 packages and all of theme have readme and changelog files at the root. i do not want to discribe the whole pages tree..

v0.23 support

Hi!
Do you plan to support current newest version?

Thanks!

"Virtual" pages always selected?

Excellent work on these plugins! I'm just getting started with typedoc and these plugins really make the generated documentation feel "fuller".

You can see the above issue in the documentation itself, e.g. visit the following page:

https://knodescommunity.github.io/typedoc-plugins/_knodes_typedoc_plugin_pages/pages/options.html

Notice that the Changelog renders as if it is selected even though it is not:

Create issue templates

Not sure how to build

Want to add a feature for hidden pages, so that I can add a huge list of subpages and not spam the index

First step is to fork, build, and install locally

npm install && npm run build

Oh, there's ... no build. Okay. Let's look at the package. There's a projects:build.

$ npm run projects:build

> @knodes/[email protected] projects:build
> npm run projects:patch -- apply && node ./tools/s-projects 'npm run build -- --pretty'


> @knodes/[email protected] projects:patch
> node ./tools/typedoc-patcher --no-stash "apply"

Applying patches from packages/plugin-pages/src/theme-plugins/search/default-pages-javascript-index-plugin.GENERATED.ts.patch
node:internal/process/promises:246
          triggerUncaughtException(err, true /* fromPromise */);
          ^

AssertionError [ERR_ASSERTION]: The expression evaluated to a falsy value:

  assert( match && match[1] )

    at E:\projects\typedoc-plugins\tools\typedoc-patcher.js:28:2
    at async E:\projects\typedoc-plugins\tools\typedoc-patcher.js:118:100
    at async Promise.all (index 0)
    at async E:\projects\typedoc-plugins\tools\typedoc-patcher.js:118:31 {
  generatedMessage: true,
  code: 'ERR_ASSERTION',
  actual: null,
  expected: true,
  operator: '=='
}

Node.js v17.2.0

Er.

There's no gh action to mimic

Not really sure how to get this to build.

[Bug]: Importing regions with backticks (`) yields escaped backticks, breaking syntax highlighting

Plugin

@knodes/typedoc-plugin-code-blocks

Typedoc plugin(s) version(s)

@knodes/[email protected]

Typedoc version

0.23.26

Describe the problem

When importing the following region from a Typescript file:

// #region    test
const x = `hello`
const y = `world`
// #endregion test

I get the following output in my docs:

const x = \`hello\`
const y = \`world\`

Notice the backticks are now escaped. This breaks Typescript syntax, but also syntax highlighting in the Markdown render (as it is doing here in GitHub too).

What did you expected ?

I was expecting unaltered code.

[Bug]: Cannot read symlinked files?

Plugin

@knodes/typedoc-plugin-pages

Typedoc plugin(s) version(s)

@knodes/typedoc-plugin-pages 0.23.1

Typedoc version

0.23.12

Describe the problem

I’m running typedoc in <package_path>/ts. I have a symlink spec.md -> ../spec/README.md and the following in my typedoc.js configuration:

module.exports = {
  // …
  pluginPages: {
    pages: [
      { title: 'Spec', children: [{ title: 'Specification', source: './spec.md' }] },
    ],
  },
}

When I run with this config, I get the following (elided):

Error: Could not locate page for "mypackage - v1.0.0" ⇥ "My Documentation" ⇥ "Specification"
…
  [cause]: Error: Resolved file "<package_path>/ts/pages/spec.md" does not exists

If I change the source reference from ./spec.md to either ../spec/README.md or ../ts/spec.md it works just fine.

What did you expected ?

I expected that documentation generation would work.

[Bug, incompatible Typedoc version]: Leaf Pages always contain the top-menu as children

Plugin

@knodes/typedoc-plugin-pages

Typedoc plugin(s) version(s)

@knodes/[email protected]

Typedoc version

0.24.6

Describe the problem

Hi, thanks for all your work on this plugin!

I am having trouble with the menu in the output.

Here is my config:

{
"pluginPages": {
    "source": "docs",
    "pages": [
      {
        "name": "Configuration",
        "childrenSourceDir": "./docs",
        "children": [
          {
            "name": "CLI usage",
            "source": "cli.md"
          },
          {
            "name": "Node.js usage",
            "source": "node.md"
          },
          {
            "name": "Templates",
            "source": "templates.md"
          },
          {
            "name": "Configuration Files",
            "source": "configuration_files.md"
          }
        ]
      }
    ]
  }
}

But the output looks like this (notice the duplication, highlighted in red):

What did you expected ?

I expect the pages to be the bottom of the navigation in these subsections. Not sure what I've done wrong.

I have toyed around with childrenDir, childrenSourceDir and children sub-grouping but to no avail.

Improve test coverage

[Feature]: Single codeblock showing multiple regions from a single file

Plugin

@knodes/typedoc-plugin-code-blocks

What would you want ?

When embedding multiple regions of code from the same file into a markdown file, I would love to be able to provide the @codeblock tag with a list of regions and get them all shown in a single code block, with any gaps hinted at with […], or something like that.

How it works now

What I do now instead looks like this:

{@codeblock clients/unauthenticated.test-d.ts#import}

{@codeblock clients/unauthenticated.test-d.ts#instantiation}

It yields two code boxes, as you can see in the screenshots, under two labels:

From ./examples/clients/unauthenticated.test-d.ts#3~7
From ./examples/clients/unauthenticated.test-d.ts#17~20

In my wildest dreams

I wish I could use a single block like this:

{@codeblock clients/unauthenticated.test-d.ts#import,instantiation}

This would produce a single label:

From ./examples/clients/unauthenticated.test-d.ts#3~7&17~20

and a single codeblock with the following contents (for comparison with screenshot above):

import HypothesisRestClient, {
  UnauthenticatedClient
} from 'hypothesis-rest'
// […]
const client = HypothesisRestClient()
expectType<UnauthenticatedClient>(client)

@knodes/typedoc-plugin-pages could not be loaded in 0.22.6

With typedoc 0.22.18 and @knodes/typedoc-plugin-pages 0.22.6 I get the following error on a Windows device. Version 0.22.5 works without any issues.

Info: Loaded plugin @knodes/typedoc-plugin-monorepo-readmes
Error: The plugin @knodes/typedoc-plugin-pages could not be loaded.
Error: Error: Cannot find module './default-pages-javascript-index-plugin.GENERATED'
Require stack:
- <projectroot>\node_modules\@knodes\typedoc-plugin-pages\dist\theme-plugins\search\index.js
- <projectroot>\node_modules\@knodes\typedoc-plugin-pages\dist\theme-plugins\index.js
- <projectroot>\node_modules\@knodes\typedoc-plugin-pages\dist\plugin.js
- <projectroot>\node_modules\@knodes\typedoc-plugin-pages\dist\load.js
- <projectroot>\node_modules\@knodes\typedoc-plugin-pages\dist\index.js
- <projectroot>\node_modules\typedoc\dist\lib\utils\plugins.js
- <projectroot>\node_modules\typedoc\dist\lib\utils\index.js
- <projectroot>\node_modules\typedoc\dist\lib\models\reflections\project.js
- <projectroot>\node_modules\typedoc\dist\lib\models\reflections\index.js
- <projectroot>\node_modules\typedoc\dist\lib\models\index.js
- <projectroot>\node_modules\typedoc\dist\lib\converter\context.js
- <projectroot>\node_modules\typedoc\dist\lib\converter\index.js
- <projectroot>\node_modules\typedoc\dist\lib\application.js
- <projectroot>\node_modules\typedoc\dist\index.js
- ...
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (<projectroot>\node_modules\@knodes\typedoc-plugin-pages\dist\theme-plugins\search\index.js:17:14)
    at Module._compile (node:internal/modules/cjs/loader:1105:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1159:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19)

[Bug]: rootDir assumes --options is used and config file is in project root

Plugin

@knodes/typedoc-pluginutils

Typedoc plugin(s) version(s)

@knodes/[email protected], @knodes/[email protected]

Typedoc version

0.25.4

Describe the problem

The rootDir calculation in ABasePlugin makes two invalid assumptions that result in errors in some projects.

First, if --options has been specified, but the options file is in a subdirectory of the project, the selected root directory is incorrect.

Second, if --options has not been specified as a command-line argument, it tries to statSync(undefined) (in rootDir from utils/misc.js).

What did you expected ?

The rootDir to be calculated independently of --options and without throwing an error.

What does "Invalid pages configuration: could not find a workspace named "xxx"" means?

Plugin

@knodes/typedoc-plugin-pages

Typedoc plugin(s) version(s)

0.23.1

Typedoc version

0.23.21

Describe the problem

I set up everything as documented, but kept getting this cryptic error message and couldn't figure out what it means nor did any search got something up

What did you expected ?

better error

Export helper scripts to alter README.md files for npm publish

[Feature]: support typedoc 0.24.6

Plugin

@knodes/typedoc-plugin-pages

What would you want ?

I need to use the latest version of typedoc (0.24.6). However, I get a dependency error during install of this plugin. I tried npm i --force but then get runtime error when running typedoc. Any estimate on when this plugin will be available for typedoc 0.24.6?

Thanks.

plugin-pages: rename node `title` to `name`

[Question]: The old style of linking to API docs from pages is broken

Plugin

@knodes/typedoc-plugin-pages

Typedoc plugin(s) version(s)

0.23.1

Typedoc version

0.23.8

Describe the problem

In the old pages plugin ([email protected]) you could link to "objects" like classes etc in the API docs from pages like so [[Clazz | clazz]] but that seems like it is not supported anymore? Are there plans to support this in the future? If not, what is the suggested approach to specify these links besides providing the path to the generated docs like so [clazz](../classes/framework_Clazz.Clazz.html).

What did you expected ?

I expect [[Clazz | clazz]] to link to the Clazz in the generated docs

[Bug]: root sources aren't added with incremental --watch

Plugin

@knodes/typedoc-pluginutils

Typedoc plugin(s) version(s)

@knodes/[email protected], @knodes/[email protected]

Typedoc version

0.25.4

Describe the problem

ABasePlugin._addSourceToProject() is only called once for the lifetime of a typedoc run, but this means that when you run typedoc --watch, the added sources aren't present in the project when later calls to findModuleRoot are made. This causes the pages plugin to crash with errors when trying to process pages for a subsequent build.

What did you expected ?

The extra sources should be added on each resolve begin event, so that they're present in all builds, not just the first one. Removing the once() wrapper fixes the issue for me.

plugin-pages: menus are always expanded

The plugin-pages does not appear to work correctly on simple non-monorepositories.

Following the example shown on this page:

pages: [
  { title: 'Getting started', source: 'getting-started.md', children: [
    { title: 'Configuration', source: 'configuration.md' },
  ] },
  { title: 'Additional resources', childrenDir: 'additional-resources', children: [
    { title: 'Some cool docs', source: 'some-cool-docs.md' },
  ] },
],

I obtain the following tree structure:

I observe that:

The menus are always expanded, regardless the currently selected page
The second menu is represented by an attribute-less <a>...</a> tag

I tested other combinations of parameters but couldn't make it work correctly. I haven't tested on a mono-repository but by looking at the configuration of this very repository and seeing the result I'm assuming it works correctly in that case.

package.json folder incorrectly identified for each project

Config

module.exports = {
    name: '@crikey/stores-mono',
    out: 'docs',
    entryPointStrategy: 'packages',
    entryPoints: [
        'packages/*'
    ]
}

Approximation of file structure

/README.md
/package.json
/packages/a/package.json
/packages/a/README.md
/packages/b/package.json
/packages/b/README.md

Result

For each project, the README.md from the root of the mono repo is selected instead of the README.md alongside the projects package.json.

Cause/Solution

plugin.ts
Line 28.

Change:
const src = u.model.sources?.[0].fileName; (filename path is relative to the package configuration, not the project root)
to something like:
const src = u.model.sources?.[0].file.fullFileName; (full absolute path)

I haven't reviewed this change in depth, so there may be a better solution, but it solves the issue for my configuration.

Other

Also, thanks for writing these plugins. They really fill a hole in TypeDoc for me :-)