diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b38103a9..941463bed 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/example/src/documents/syntax-highlighting.md b/example/src/documents/syntax-highlighting.md index 6bb96094a..b24674035 100644 --- a/example/src/documents/syntax-highlighting.md +++ b/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: diff --git a/site/options/output.md b/site/options/output.md index 4e280f7e1..b24aaa312 100644 --- a/site/options/output.md +++ b/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. diff --git a/src/lib/internationalization/locales/en.cts b/src/lib/internationalization/locales/en.cts index 8b38479a6..48c98b3d9 100644 --- a/src/lib/internationalization/locales/en.cts +++ b/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", diff --git a/src/lib/output/renderer.ts b/src/lib/output/renderer.ts index 1df30cbdc..2e17b4de7 100644 --- a/src/lib/output/renderer.ts +++ b/src/lib/output/renderer.ts @@ -247,6 +247,9 @@ export class Renderer extends AbstractComponent { @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 { this.darkTheme, // Checked in option validation this.highlightLanguages as BundledLanguage[], + this.ignoredHighlightLanguages, ); } diff --git a/src/lib/utils/highlighter.tsx b/src/lib/utils/highlighter.tsx index 57b321706..a3b904824 100644 --- a/src/lib/utils/highlighter.tsx +++ b/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}); } diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts index a55b214bc..cd19ea7d1 100644 --- a/src/lib/utils/options/declaration.ts +++ b/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; diff --git a/src/lib/utils/options/defaults.ts b/src/lib/utils/options/defaults.ts index e5c269f47..89e4d5335 100644 --- a/src/lib/utils/options/defaults.ts +++ b/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", diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts index d862771bb..467426ee1 100644 --- a/src/lib/utils/options/sources/typedoc.ts +++ b/src/lib/utils/options/sources/typedoc.ts @@ -366,6 +366,12 @@ export function addTypeDocOptions(options: Pick) { } }, }); + options.addDeclaration({ + name: "ignoredHighlightLanguages", + help: (i18n) => i18n.help_ignoredHighlightLanguages(), + type: ParameterType.Array, + defaultValue: OptionDefaults.ignoredHighlightLanguages, + }); options.addDeclaration({ name: "typePrintWidth", help: (i18n) => i18n.help_typePrintWidth(),