Default to render code blocks w/out syntax highlighting instead of hard failure

[unmultimedio]

Creating a new issue from:

@Gerrit0 Just bumped into this issue, with another language. According to the docs:

By default, TypeDoc will produce an error if a code block specifies a language which is not present in the highlightLanguages array.

I wonder if there's a way to tell TypeDoc to not fail for unknown languages, but instead just render w/out highlight. I can open a new issue with this question if you want.

Originally posted by @unmultimedio in #2943

[Gerrit0]

Apparently those docs are just wrong for TypeDoc today, I went to look at doing this, and this is already how TypeDoc behaves, when encountering an unsupported language, it warns, and continues to produce output with unhighlighted output

[warning] Unsupported highlight language blagh will not be highlighted in comment for TypeDoc API

Furthermore, the ignoredHighlightLanguages option exists to specify that a language should be accepted and not highlighted without producing a warning.

[unmultimedio]

Thanks for checking, I can see you attempted with a non-existing language. Could you pls attempt with a valid language but not load it? I was getting in the stderr of the command:

�[93m[warning]�... multiple warnings
�[91m[error]�[0m Language `proto` not found, you may need to load it first
�[91m[error]�[0m html output could not be generated due to the errors above
�[91m[error]�[0m Found X errors and Y warnings

I didn't add proto to the highlightLanguages nor to the ignoredHighlightLanguages config. I think TypeDoc should default to ignore it if it's not present in highlightLanguages and not even need ignoredHighlightLanguages at all?

TypeDoc version: 0.28.3
Typescript version: 5.8.2

[Gerrit0]

That really ought to be a warning not an error, fixed with c0d3cb3.

I think TypeDoc should default to ignore it if it's not present in highlightLanguages and not even need ignoredHighlightLanguages at all?

It should warn as it is useful to know that TypeDoc does support highlighting that language, but it isn't loaded. It's now possible to prevent that warning with ignoredHighlightLanguages

[unmultimedio]

Thanks for looking at this @Gerrit0, but I'm afraid this is not yet fixed ☹️, lemme share some repro examples, and if you agree with me please reopen this issue.

First, my package-lock.json, updated to your latest release 0.28.5:

{
  "name": "ts",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "devDependencies": {
        "typedoc": "^0.28.5"
      }
    },
    ...
    "node_modules/typedoc": {
      "version": "0.28.5",
      "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.28.5.tgz",
      ...
    },
    ...
  }
}

And my typedoc.json:

{
  "highlightLanguages": [
    "go",
    "typescript", // I'm forced to add this, otherwise code blocks without language don't work
  ],
  "ignoredHighlightLanguages": [
    "proto",
  ]
}

And my source:

/**
 * This function does something
 * 
 * ```
 * some code block
 * ```
 * 
 * More docs...
 **/
export function doSomething(inputA: string) {
  return "Make me!";
}

And the scenarios that I ran, setting the code block comment with:

Scenario	Language	Output
1. No language		OK (defaults to typescript language)
2. Language in highlightLanguages	go	OK (no warning)
3. Language in ignoredHighlightLanguages	proto	OK (no warning)
4. Made up language	foo	OK with: [warning] Unsupported highlight language foo will not be highlighted in comment for doSomething
5. Valid language, not present in any config	cpp	Fails with: [error] Language cpp not found, you may need to load it first

So my specific suggestions:

1. For scenario 1: don't use typescript as default and instead not do any code highlight, I'd categorize this as an improvement.
2. For scenario 5: raise a warning and don't do any code highlight instead of erroring, I'd categorize this as a bug.
3. I keep thinking that ignoredHighlightLanguages config is may be not needed. Whenever an unknown/unloaded language is detected in a code block, the logic could fallback to not highlight, and raise a warning.

[Gerrit0]

For scenario 1: don't use typescript as default and instead not do any code highlight, I'd categorize this as an improvement.

This is a breaking change which I'm not particularly enthralled by... TypeDoc is a TypeScript documentation generator. Eh... priority: lowest.

For scenario 5: raise a warning and don't do any code highlight instead of erroring, I'd categorize this as a bug.

Yes, that's an issue, I did the check backwards :/

I keep thinking that ignoredHighlightLanguages config is may be not needed. Whenever an unknown/unloaded language is detected in a code block, the logic could fallback to not highlight, and raise a warning.

This is how TypeDoc is intended to work, the entire point of ignoredHighlightLanguages is to disable the warning for languages which aren't supported/loaded.

[unmultimedio]

I can confirm I tested:

"typedoc": "git://github.com/TypeStrong/typedoc.git#17774dd3b1f3c7dc26a51b158ea3e3db34705c9f"

And it worked for scenario 5. Thank you a lot, I'll wait for your next release with it.

[unmultimedio]

Hi @Gerrit0, just a reminder to publish a release including this patch please 😄

[unmultimedio]

Hello @Gerrit0, sorry to bother again, just another ping to ask for a new release with this patch, thank you!