Upgrade `typedoc` - Githubissues

Peeja commented 1 year ago

# npm audit report

marked  <=4.0.9
Severity: high
Inefficient Regular Expression Complexity in marked - https://github.com/advisories/GHSA-5v2h-r2cx-5xgj
Inefficient Regular Expression Complexity in marked - https://github.com/advisories/GHSA-rrrm-qjm4-v8hf
Regular Expression Denial of Service (REDoS) in Marked - https://github.com/advisories/GHSA-4r62-v4vq-hr96
fix available via `npm audit fix --force`
Will install typedoc@0.24.8, which is a breaking change
node_modules/marked
  typedoc  <=0.21.9 || 0.22.0-beta.0 - 0.22.10 || >=1.0.0-dev.1
  Depends on vulnerable versions of marked
  node_modules/typedoc

2 high severity vulnerabilities

To address all issues (including breaking changes), run:
  npm audit fix --force

However, upgrading typedoc breaks the typedoc build, so this requires at least some actual thought to deal with.two

More specifically, some options have been removed:

mode was removed. Only what was library mode is now available. We currently use file mode.
readmeToc is not recognized. It didn't throw an error before, but I can't find a reference to its earlier usage anywhere on the web. It seems pretty intentional, though.
I also can't find references to stripInternal anywhere, but excludeInternal sounds like it's what that should mean. Is it possible that stripInternal never worked?

Peeja commented 1 year ago

@gsvarovsky Any insight about these? In particular, can we make the docs work properly in library mode?

gsvarovsky commented 1 year ago

The primary brake here is that we use a customised typedoc theme. The template for the theme changed extensively for typedoc 0.20.

The readmeToc thing is an extension in the theme: https://github.com/m-ld/typedoc-theme/commit/90b4d341bb1b340386af2a323fbd2b70d9763a8a

Not sure what stripInternal is about.

gsvarovsky commented 11 months ago

Suggestion: using a customised theme is going to cause this kind of problem repeatedly.

Let's switch to generating markdown docs using typedoc-plugin-markdown, then compose the final website using eleventy, via m-ld/m-ld-io-web-base.

I'll experiment with that approach in the gateway, particularly because it orients more to custom documentation rather than tsdoc.

m-ld / m-ld-js

Upgrade `typedoc` #155