Class TextUtils.DocumentBuilder

java.lang.Object
co.mindus.utils.TextUtils.DocumentBuilder
Enclosing class:
TextUtils
public static class TextUtils.DocumentBuilder extends Object
Builder for full HTML documents with configurable theme, title, language, and CSS handling.

All settings have sensible defaults — the minimal usage is: TextUtils.documentBuilder().markdown(text).build().

Two-Layer Theme System

The generated document supports two independent CSS layers:

  1. Document theme (theme(Theme)) — controls the overall page appearance: fonts, headings, tables, blockquotes, backgrounds. Choose from BASIC, MODERN, or GITHUB (each with a dark variant), or NONE for unstyled HTML. Default: TextUtils.Theme.GITHUB.
  2. Syntax highlight theme (highlightTheme(SyntaxHighlighter.HighlightTheme)) — controls code block colors when syntaxHighlight(boolean) is enabled. 77 themes are available (16 curated + 61 extended). See SyntaxHighlighter.HighlightTheme for the full catalog.

When no highlight theme is specified, one is auto-selected to match the document theme's brightness: light documents get GITHUB, dark documents get GITHUB_DARK.

Example

String html = TextUtils.documentBuilder()
    .markdown(text)
    .title("API Reference")
    .theme(TextUtils.Theme.GITHUB_DARK)
    .syntaxHighlight(true)
    .highlightTheme(SyntaxHighlighter.HighlightTheme.NORD)
    .autoDetectLanguage(true)
    .build();
Author:
Christopher Mindus
See Also:

  • Method Details

    • markdown

      public TextUtils.DocumentBuilder markdown(String md)
      Sets the Markdown source text to convert.
      Parameters:
      md - The Markdown source text.
      Returns:
      This builder, for method chaining.

    • title

      public TextUtils.DocumentBuilder title(String t)
      Sets the HTML <title> element (default: none).
      Parameters:
      t - Applies the title.
      Returns:
      This builder, for method chaining.

    • lang

      public TextUtils.DocumentBuilder lang(String l)
      Sets the lang attribute on <html> (default: "en").
      Parameters:
      l - Applies the language (code).
      Returns:
      This builder, for method chaining.

    • charset

      public TextUtils.DocumentBuilder charset(String cs)
      Sets the character encoding declared in <meta charset>.
      Parameters:
      cs - Applies the @code cs} as CharSet for Strings (default "UTF-8").
      Returns:
      This builder, for method chaining.

    • theme

      public TextUtils.DocumentBuilder theme(TextUtils.Theme t)
      Sets the CSS theme (default: TextUtils.Theme.GITHUB). Use TextUtils.Theme.NONE for no CSS.
      Parameters:
      t - Applies the Theme.
      Returns:
      This builder, for method chaining.

    • inlineCss

      public TextUtils.DocumentBuilder inlineCss(boolean b)
      If true (default), embeds the theme CSS in a <style> block. If false, use cssUrl(String) to provide an external stylesheet link.
      Parameters:
      b - true to enable theme CSS (default: true).
      Returns:
      This builder, for method chaining.

    • customCss

      public TextUtils.DocumentBuilder customCss(String css)
      Additional CSS appended after the theme CSS (default: none).
      Parameters:
      css - The additional css or null for none.
      Returns:
      This builder, for method chaining.

    • cssUrl

      public TextUtils.DocumentBuilder cssUrl(String url)
      URL string for an external stylesheet (used when inlineCss(boolean) is false).
      Parameters:
      url - Applies the URL for an external CSS file.
      Returns:
      This builder, for method chaining.

    • cssFrom

      public TextUtils.DocumentBuilder cssFrom(URI uri)
      External stylesheet from a URI (sets inlineCss(boolean) to false).
      Parameters:
      uri - Applies the URI for an external CSS file.
      Returns:
      This builder, for method chaining.

    • cssFrom

      public TextUtils.DocumentBuilder cssFrom(URL url)
      External stylesheet from a URL (sets inlineCss(boolean) to false).
      Parameters:
      url - Applies the URL for an external CSS file.
      Returns:
      This builder, for method chaining.

    • bodyClass

      public TextUtils.DocumentBuilder bodyClass(String cls)
      CSS class on the <article> wrapper.
      Parameters:
      cls - Applies the body class, default: "markdown-body".

    • syntaxHighlight

      public TextUtils.DocumentBuilder syntaxHighlight(boolean b)
      Enables or disables server-side syntax highlighting of fenced code blocks.

      When enabled, the SyntaxHighlighter engine is loaded on demand and all <pre><code class="language-xxx"> blocks in the output are processed. A suitable highlight CSS theme is included automatically (can be overridden with highlightTheme(SyntaxHighlighter.HighlightTheme)).

      Parameters:
      b - true to enable syntax highlighting (default: false).
      Returns:
      This builder, for method chaining.

    • syntaxHighlighter

      public TextUtils.DocumentBuilder syntaxHighlighter(SyntaxHighlighter hl)
      Provides an existing SyntaxHighlighter instance to reuse.

      Implies syntaxHighlight(true). The provided instance is not disposed after build() — the caller retains ownership. This is efficient when rendering multiple documents, as the engine is initialized only once.

      Parameters:
      hl - An existing highlighter instance, or null to create on demand.
      Returns:
      This builder, for method chaining.

    • highlightTheme

      public TextUtils.DocumentBuilder highlightTheme(SyntaxHighlighter.HighlightTheme t)
      Sets the CSS theme for syntax-highlighted code blocks.

      Implies syntaxHighlight(true). If not set, a theme matching the document's TextUtils.Theme brightness is selected automatically.

      Parameters:
      t - The highlight theme, or null for automatic selection.
      Returns:
      This builder, for method chaining.

    • autoDetectLanguage

      public TextUtils.DocumentBuilder autoDetectLanguage(boolean b)
      Enables or disables automatic language detection for code blocks that do not have an explicit language-xxx class (i.e. bare <pre><code> blocks produced by unfenced or unlabeled code in Markdown).

      Implies syntaxHighlight(true). When enabled, the highlighter's highlightAuto method is used. Only results whose relevance score meets or exceeds SyntaxHighlighter.AUTO_DETECT_MIN_RELEVANCE are applied; below this threshold the code block is left as plain escaped text.

      When disabled (false), bare code blocks are left entirely untouched — only blocks with an explicit language class are highlighted.

      Parameters:
      b - true to enable auto-detection (default: true).
      Returns:
      This builder, for method chaining.
      See Also:

    • disposeHighlighterAfterBuild

      public TextUtils.DocumentBuilder disposeHighlighterAfterBuild(boolean b)
      If true, the highlighting engine is disposed after build() completes, releasing the engine instance.

      This is the default behavior for one-off document generation. If you are rendering many documents, set this to false to avoid repeated engine initialization.

      Note: since the highlighting library is on the class path, disposal releases only this engine instance — the library's classes remain loaded. It no longer closes a class loader.

      Parameters:
      b - true to dispose after build (default: true).
      Returns:
      This builder, for method chaining.

    • escapeNonAscii

      public TextUtils.DocumentBuilder escapeNonAscii(boolean b)
      Controls whether non-ASCII characters in the rendered HTML body are replaced with numeric HTML entities (&#xNNNN;).

      When enabled (the default), the output document is pure ASCII and renders correctly regardless of the HTTP Content-Type charset sent by the web server. This prevents mojibake when the server does not include charset=UTF-8 in the response headers.

      Disable this if the serving infrastructure guarantees UTF-8 encoding and you prefer smaller output without entity escaping.

      Parameters:
      b - true to escape non-ASCII (default: true).
      Returns:
      This builder, for method chaining.
      See Also:

    • build

      public String build()
      Builds the complete HTML document.
      Returns:
      A full HTML5 document string.
      Throws:
      IllegalStateException - if the Markdown engine could not be initialized.