Add ignoredHighlightLanguages option

Resolves #2819

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,11 @@ title: Changelog
 
 ## Unreleased
 
+### Features
+
+-   Added `ignoredHighlightLanguages` option to specify languages which will be
+    allowed in code blocks but not highlighted, #2819.
+
 ### Bug Fixes
 
 -   `@include` and `@includeCode` now work in the readme file, #2814.

example/src/documents/syntax-highlighting.md

@@ -8,7 +8,8 @@ TypeDoc supports code blocks in Markdown and uses
 
 TypeDoc supports all languages supported by Shiki, but does not load all of
 them by default. The `highlightLanguages` option can be used to customize
-which languages are loaded for highlighting.
+which languages are loaded for highlighting. The `ignoredHighlightLanguages`
+option can be used to specify languages which should not be highlighted.
 
 If no language is specified, the code block is assumed to be TypeScript:
 

site/options/output.md

@@ -162,6 +162,18 @@ loads the following languages.
 }
 ```
 
+## ignoredHighlightLanguages
+
+Specifies languages used in code blocks which should be silently ignored by TypeDoc.
+By default, TypeDoc will produce an error if a code block specifies a language which
+is not present in the highlightLanguages array.
+
+```json
+{
+    "ignoredHighlightLanguages": ["mkdocs"]
+}
+```
+
 ## typePrintWidth
 
 Specifies the width at which to wrap code when rendering types, defaults to 80.

src/lib/internationalization/locales/en.cts

@@ -237,6 +237,8 @@ export = {
     help_darkHighlightTheme: "Specify the code highlighting theme in dark mode",
     help_highlightLanguages:
         "Specify the languages which will be loaded to highlight code when rendering",
+    help_ignoredHighlightLanguages:
+        "Specify languages which will be accepted as valid highlight languages, but will not be highlighted at runtime",
     help_typePrintWidth:
         "Width at which to wrap code to a new line when rendering a type",
     help_customCss: "Path to a custom CSS file to for the theme to import",

src/lib/output/renderer.ts

@@ -247,6 +247,9 @@ export class Renderer extends AbstractComponent<Application, RendererEvents> {
     @Option("highlightLanguages")
     private accessor highlightLanguages!: string[];
 
+    @Option("ignoredHighlightLanguages")
+    private accessor ignoredHighlightLanguages!: string[];
+
     @Option("pretty")
     private accessor pretty!: boolean;
 
@@ -342,6 +345,7 @@ export class Renderer extends AbstractComponent<Application, RendererEvents> {
             this.darkTheme,
             // Checked in option validation
             this.highlightLanguages as BundledLanguage[],
+            this.ignoredHighlightLanguages,
         );
     }
 

src/lib/utils/highlighter.tsx

@@ -116,14 +116,18 @@ class DoubleHighlighter {
 
 let shikiEngine: shiki.RegexEngine | undefined;
 let highlighter: DoubleHighlighter | undefined;
+let ignoredLanguages: string[] | undefined;
 
 export async function loadHighlighter(
     lightTheme: shiki.BundledTheme,
     darkTheme: shiki.BundledTheme,
     langs: shiki.BundledLanguage[],
+    ignoredLangs: string[] | undefined,
 ) {
     if (highlighter) return;
 
+    ignoredLanguages = ignoredLangs;
+
     if (!shikiEngine) {
         await shiki.loadBuiltinWasm();
         shikiEngine = await shiki.createOnigurumaEngine();
@@ -138,7 +142,7 @@ export async function loadHighlighter(
 }
 
 export function isSupportedLanguage(lang: string) {
-    return getSupportedLanguages().includes(lang);
+    return ignoredLanguages?.includes(lang) || getSupportedLanguages().includes(lang);
 }
 
 export function getSupportedLanguages(): string[] {
@@ -150,13 +154,15 @@ export function getSupportedThemes(): string[] {
 }
 
 export function isLoadedLanguage(lang: string): boolean {
-    return plaintextLanguages.includes(lang) || (highlighter?.supports(lang) ?? false);
+    return (
+        plaintextLanguages.includes(lang) || ignoredLanguages?.includes(lang) || highlighter?.supports(lang) || false
+    );
 }
 
 export function highlight(code: string, lang: string): string {
     assert(highlighter, "Tried to highlight with an uninitialized highlighter");
 
-    if (plaintextLanguages.includes(lang)) {
+    if (plaintextLanguages.includes(lang) || ignoredLanguages?.includes(lang)) {
         return JSX.renderElement(<>{code}</>);
     }
 

src/lib/utils/options/declaration.ts

@@ -145,6 +145,7 @@ export interface TypeDocOptionMap {
     lightHighlightTheme: ShikiTheme;
     darkHighlightTheme: ShikiTheme;
     highlightLanguages: string[];
+    ignoredHighlightLanguages: string[];
     typePrintWidth: number;
     customCss: string;
     customJs: string;

src/lib/utils/options/defaults.ts

@@ -77,6 +77,8 @@ export const highlightLanguages: readonly BundledLanguage[] = [
     "typescript",
 ];
 
+export const ignoredHighlightLanguages: readonly string[] = [];
+
 export const sort: readonly string[] = [
     "kind",
     "instance-first",

src/lib/utils/options/sources/typedoc.ts

@@ -366,6 +366,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
             }
         },
     });
+    options.addDeclaration({
+        name: "ignoredHighlightLanguages",
+        help: (i18n) => i18n.help_ignoredHighlightLanguages(),
+        type: ParameterType.Array,
+        defaultValue: OptionDefaults.ignoredHighlightLanguages,
+    });
     options.addDeclaration({
         name: "typePrintWidth",
         help: (i18n) => i18n.help_typePrintWidth(),