Class SyntaxHighlighter

Method Details

• create

  public static SyntaxHighlighter create()

  Creates a new syntax highlighter instance.

  The highlighting library is referenced directly, so this simply builds an engine with the hljs- renderer factory. Instances are cheap; dispose() exists for callers written against the previous dynamic-loading design and releases only the engine reference.

  For one-shot usage through the TextUtils.DocumentBuilder, prefer .syntaxHighlight(true) which manages the lifecycle automatically.

  Returns:

  A new, ready-to-use highlighter instance.

  Throws:

  IllegalStateException - if the engine cannot be created.

• highlight

  public String highlight(String language, String code)

  Highlights a code block for a specific language.

  The input code should be plain text (not HTML-escaped). The output contains <span class="hljs-xxx"> elements wrapping language tokens. HTML special characters in the source code are properly escaped in the output.

  The language identifier is case-insensitive; it is normalized to lower case before being passed to the underlying engine.

  Parameters:

  language - The language identifier (e.g. "java", "javascript", "css", "json", "sql", "bash"). Case-insensitive. If null or empty, falls back to highlightAuto(String).

  code - The source code text to highlight.

  Returns:

  The highlighted HTML, or the original code (HTML-escaped) if the language is not recognized.

• highlightAuto

  public SyntaxHighlighter.HighlightResult highlightAuto(String code)

  Highlights a code block with automatic language detection.

  The highlighter analyzes the code and selects the best-matching language. Use the returned SyntaxHighlighter.HighlightResult to access the highlighted HTML, detected language name, and relevance score.

  Parameters:

  code - The source code text to highlight.

  Returns:

  A result containing the highlighted HTML and detection metadata.

• getSupportedLanguages

  public String[] getSupportedLanguages()

  Returns the list of language identifiers supported by the highlighter.

  Always returns an empty array. The bundled Highlight.java exposes no public enumeration of its registered languages, so there is nothing to query; this was already the effective behaviour when the library was driven by reflection. See the class-level "Supported Languages" section for the verified list of the 25 registered identifiers.

  Returns:

  An empty array.

• highlightCodeBlocks

  public String highlightCodeBlocks(String html)

  Processes an HTML fragment and highlights all fenced code blocks in-place, with automatic language detection enabled for bare code blocks.

  This convenience overload delegates to highlightCodeBlocks(html, true).

  Parameters:

  html - An HTML fragment containing zero or more code blocks.

  Returns:

  The HTML with all code blocks syntax-highlighted.

  See Also:

  • highlightCodeBlocks(String,boolean)

• highlightCodeBlocks

  public String highlightCodeBlocks(String html, boolean autoDetect)

  Processes an HTML fragment and highlights all fenced code blocks in-place.

  This method performs up to two passes over the HTML:

  1. Explicit language — scans for <pre><code class="language-xxx"> blocks (as produced by commonmark) and highlights them using the declared language. This pass always runs.
  2. Auto-detection (optional) — if autoDetect is true, scans for bare <pre><code> blocks (no language-xxx class) and uses highlightAuto(String) to guess the language. Only results whose relevance score meets or exceeds AUTO_DETECT_MIN_RELEVANCE are applied; below the threshold the block is left as plain escaped text to avoid garbled output from low-confidence guesses.

  The same highlighter instance is used for all code blocks in the fragment, ensuring the engine is initialized exactly once regardless of how many code blocks are present.

  Parameters:

  html - An HTML fragment containing zero or more code blocks.

  autoDetect - true to enable automatic language detection for bare code blocks; false to leave them untouched.

  Returns:

  The HTML with code blocks syntax-highlighted.

• dispose

  public void dispose()

  Releases this instance's highlighting engine.

  The library is loaded by the application class loader, so there is no class loader to close; this drops the engine reference and the instance must not be used afterwards. Retained because callers written against the previous dynamic-loading design call it.

  This method is idempotent — calling it multiple times has no effect.

• loadThemeCss

  public static String loadThemeCss(SyntaxHighlighter.HighlightTheme theme)

  Loads the CSS text for a given highlight theme.

  Results are cached after first load. This method does not require a SyntaxHighlighter instance — theme CSS files are classpath resources that can be loaded at any time.

  Parameters:

  theme - The highlight theme to load.

  Returns:

  The CSS text, or null if the theme's CSS resource cannot be found.

• clearThemeCache

  public static void clearThemeCache()

  Clears the theme CSS cache, freeing memory.

  Subsequent calls to loadThemeCss(HighlightTheme) will reload from classpath resources.

• getConflictResolutionCss

  public static String getConflictResolutionCss()

  Returns a CSS snippet that resolves padding conflicts between Markdown document themes and highlight.js code block themes.

  When both a Markdown document theme (from TextUtils.Theme) and a syntax highlight theme are active in the same document, the document theme may apply its own padding and background to <pre> elements, which conflicts with the highlight theme's code.hljs styling. Injecting this snippet after both theme CSS blocks ensures the highlight theme controls code block appearance without double padding.

  Example usage:

  sb.append("<style>\n").append(docThemeCss).append("\n</style>\n");
  sb.append("<style>\n").append(hlThemeCss).append("\n</style>\n");
  sb.append("<style>\n").append(SyntaxHighlighter.getConflictResolutionCss())
    .append("\n</style>\n");
  

  Returns:

  A CSS fragment (two rules) to include after both theme CSS blocks.

• getAvailableThemes

  public static SyntaxHighlighter.HighlightTheme[] getAvailableThemes()

  Returns all available themes.

  Returns:

  An array of all themes (curated and extended).

• getThemes

  public static SyntaxHighlighter.HighlightTheme[] getThemes(SyntaxHighlighter.ThemeType type)

  Returns themes matching the given type classification.

  Parameters:

  type - The desired theme type (LIGHT, DARK, or NEUTRAL).

  Returns:

  An array of matching themes.

• getThemes

  public static SyntaxHighlighter.HighlightTheme[] getThemes(SyntaxHighlighter.ThemeSet set)

  Returns themes from the given set.

  Parameters:

  set - The desired theme set (CURATED or EXTENDED).

  Returns:

  An array of matching themes.

• getThemes

  public static SyntaxHighlighter.HighlightTheme[] getThemes(SyntaxHighlighter.ThemeType type, SyntaxHighlighter.ThemeSet set)

  Returns themes matching both a type and a set.

  Parameters:

  type - The desired theme type.

  set - The desired theme set.

  Returns:

  An array of matching themes.

• defaultThemeFor

  public static SyntaxHighlighter.HighlightTheme defaultThemeFor(TextUtils.Theme mdTheme)

  Selects an appropriate default highlight theme that matches a Markdown document theme's light/dark classification.

  If the Markdown theme is light, returns DEFAULT_LIGHT_THEME. If dark, returns DEFAULT_DARK_THEME. For NONE or unknown themes, defaults to the light theme.

  Parameters:

  mdTheme - The Markdown document theme (from TextUtils.Theme).

  Returns:

  A suitable highlight theme.