or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-highlighting.mdindex.mdlanguage-management.mdmodes-patterns.mdplugin-system.mdutilities.md
tile.json

configuration.mddocs/

Configuration

Configuration system for customizing highlight.js behavior, CSS classes, language detection, and processing options. These settings affect how highlight.js processes code and generates HTML output.

Capabilities

Configure Function

Main configuration function for setting global highlighting options. Changes apply to all subsequent highlighting operations.

/**
 * Configures global highlighting options
 * @param options - Partial configuration object with options to override
 */
function configure(options: Partial<HLJSOptions>): void;

interface HLJSOptions {
  /** Regular expression matching CSS classes that disable highlighting */
  noHighlightRe: RegExp;
  /** Regular expression for detecting language from CSS classes */
  languageDetectRe: RegExp;
  /** CSS class prefix for highlighted elements */
  classPrefix: string;
  /** String to replace tab characters with */
  tabReplace?: string;
  /** Whether to use <br> tags for line breaks instead of \n */
  useBR: boolean;
  /** Array of language names to include in auto-detection */
  languages?: string[];
  /** Internal emitter constructor for HTML generation */
  __emitter: EmitterConstructor;
}

Usage Examples:

import hljs from "highlight.js";

// Basic configuration
hljs.configure({
  classPrefix: 'code-',           // Use 'code-' instead of 'hljs-'
  tabReplace: '    ',            // Replace tabs with 4 spaces
  useBR: false                   // Use \n instead of <br> tags
});

// Custom no-highlight pattern
hljs.configure({
  noHighlightRe: /^(no-highlight|plain)$/i
});

// Custom language detection pattern
hljs.configure({
  languageDetectRe: /\blang(?:uage)?-(\w+)\b/i
});

// Restrict auto-detection to specific languages
hljs.configure({
  languages: ['javascript', 'python', 'java', 'html', 'css']
});

// Multiple options
hljs.configure({
  classPrefix: 'syntax-',
  tabReplace: '  ',
  languages: ['javascript', 'typescript', 'python'],
  useBR: false
});

Class Prefix Configuration

Controls the CSS class prefix used for highlighted elements. Useful for avoiding conflicts with existing CSS or following naming conventions.

// Default prefix is 'hljs-'
// Keywords become: <span class="hljs-keyword">function</span>

// Custom prefix example
hljs.configure({classPrefix: 'code-'});
// Keywords become: <span class="code-keyword">function</span>

Usage Examples:

// Avoid CSS conflicts
hljs.configure({classPrefix: 'highlight-'});

// Match existing CSS framework
hljs.configure({classPrefix: 'syntax-'});

// No prefix (use with caution)
hljs.configure({classPrefix: ''});

// Example CSS for custom prefix
/*
.syntax-keyword { color: #0066cc; }
.syntax-string { color: #009900; }
.syntax-comment { color: #666666; }
*/

No-Highlight Configuration

Controls which CSS classes disable highlighting. Elements with matching classes will not be processed.

// Default pattern matches: no-highlight, nohighlight
const defaultPattern = /^(no-?highlight)$/i;

hljs.configure({
  noHighlightRe: /^(no-highlight|plain|raw)$/i
});

Usage Examples:

// Add more no-highlight patterns
hljs.configure({
  noHighlightRe: /^(no-highlight|nohighlight|plain|raw|text)$/i
});

// Case-sensitive matching
hljs.configure({
  noHighlightRe: /^(PLAIN|RAW)$/
});

// Custom patterns
hljs.configure({
  noHighlightRe: /^skip-highlighting$/i
});

HTML Examples:

<!-- These will not be highlighted -->
<pre><code class="no-highlight">raw code here</code></pre>
<pre><code class="plain">plain text here</code></pre>
<pre><code class="raw">unprocessed code</code></pre>

Language Detection Configuration

Controls how highlight.js detects language names from CSS classes.

// Default pattern: language-xxx or lang-xxx
const defaultPattern = /\blang(?:uage)?-([\w-]+)\b/i;

hljs.configure({
  languageDetectRe: /\bcode-([\w-]+)\b/i
});

Usage Examples:

// Custom detection pattern
hljs.configure({
  languageDetectRe: /\bsyntax-([\w-]+)\b/i
});

// Multiple patterns (requires more complex regex)
hljs.configure({
  languageDetectRe: /\b(?:lang|language|syntax)-([\w-]+)\b/i
});

// Stricter pattern
hljs.configure({
  languageDetectRe: /^language-(\w+)$/
});

HTML Examples:

<!-- Default patterns -->
<code class="language-javascript">...</code>
<code class="lang-python">...</code>

<!-- Custom pattern: syntax-xxx -->
<code class="syntax-javascript">...</code>
<code class="syntax-python">...</code>

Tab Replacement Configuration

Controls how tab characters are handled in code. Can improve code formatting consistency.

hljs.configure({
  tabReplace: '    '  // Replace tabs with 4 spaces
});

hljs.configure({
  tabReplace: '  '    // Replace tabs with 2 spaces
});

hljs.configure({
  tabReplace: undefined // Keep original tabs
});

Usage Examples:

// Standard configurations
hljs.configure({tabReplace: '    '}); // 4 spaces
hljs.configure({tabReplace: '  '});   // 2 spaces
hljs.configure({tabReplace: '\u00a0\u00a0\u00a0\u00a0'}); // Non-breaking spaces

// Preserve tabs
hljs.configure({tabReplace: undefined});

// Visual tab indicator
hljs.configure({tabReplace: '→   '}); // Arrow + spaces

Line Break Configuration

Controls whether to use HTML 

<br>
tags or newline characters for line breaks.

hljs.configure({
  useBR: false  // Use \n characters (default)
});

hljs.configure({
  useBR: true   // Use <br> tags
});

Usage Examples:

// For HTML rendering (default)
hljs.configure({useBR: false});
// Output: "line1\nline2"

// For inline HTML contexts
hljs.configure({useBR: true});
// Output: "line1<br>line2"

// Context-specific configuration
function highlightForContext(code, language, isInline = false) {
  const originalConfig = getCurrentConfig(); // Hypothetical function
  
  hljs.configure({useBR: isInline});
  const result = hljs.highlight(code, {language});
  
  hljs.configure(originalConfig); // Restore
  return result;
}

Language Subset Configuration

Restricts auto-detection to specific languages for better performance and accuracy.

hljs.configure({
  languages: ['javascript', 'python', 'html', 'css']
});

// Clear restriction
hljs.configure({
  languages: undefined
});

Usage Examples:

// Web development focus
hljs.configure({
  languages: ['javascript', 'typescript', 'html', 'css', 'json', 'markdown']
});

// Data science focus
hljs.configure({
  languages: ['python', 'r', 'sql', 'json', 'yaml']
});

// Systems programming
hljs.configure({
  languages: ['c', 'cpp', 'rust', 'go', 'assembly']
});

// Dynamic configuration based on context
function configureForContext(context) {
  const languageSets = {
    web: ['javascript', 'typescript', 'html', 'css', 'json'],
    backend: ['python', 'java', 'go', 'sql', 'yaml'],
    mobile: ['swift', 'kotlin', 'java', 'javascript'],
    all: undefined // No restriction
  };
  
  hljs.configure({
    languages: languageSets[context] || languageSets.all
  });
}

Initialization Functions

Manual Initialization

Provides control over when and how highlighting is initialized.

/**
 * Manually initializes highlighting without processing existing code
 * Sets up the highlighting system but doesn't automatically process DOM elements
 */
function initHighlighting(): void;

/**
 * Sets up highlighting to run automatically when DOM is loaded
 * Equivalent to calling highlightAll() on DOMContentLoaded event
 */
function initHighlightingOnLoad(): void;

Usage Examples:

import hljs from "highlight.js";

// Manual control over initialization
hljs.configure({classPrefix: 'code-'});
hljs.initHighlighting();
// ... custom logic ...
hljs.highlightAll(); // Process when ready

// Automatic initialization
hljs.configure({tabReplace: '  '});
hljs.initHighlightingOnLoad(); // Will highlight when DOM loads

// Conditional initialization
if (document.readyState === 'loading') {
  hljs.initHighlightingOnLoad();
} else {
  hljs.initHighlighting();
  hljs.highlightAll();
}

// Custom initialization with error handling
function safeInitialization() {
  try {
    hljs.configure({
      classPrefix: 'syntax-',
      languages: ['javascript', 'python', 'html']
    });
    
    if (document.readyState === 'complete') {
      hljs.highlightAll();
    } else {
      hljs.initHighlightingOnLoad();
    }
  } catch (error) {
    console.error('Highlight.js initialization failed:', error);
  }
}

Configuration Best Practices

Performance Optimization

// Limit languages for better auto-detection performance
hljs.configure({
  languages: ['javascript', 'python', 'html', 'css', 'json']
});

// Use specific language when known
// This is faster than auto-detection
const result = hljs.highlight(code, {language: 'javascript'});

CSS Integration

// Match your CSS framework
hljs.configure({classPrefix: 'highlight-'});

// Corresponding CSS
/*
.highlight-keyword { color: var(--keyword-color); }
.highlight-string { color: var(--string-color); }
.highlight-comment { color: var(--comment-color); }
*/

Context-Aware Configuration

class HighlightManager {
  constructor() {
    this.contexts = {
      documentation: {
        classPrefix: 'doc-code-',
        languages: ['javascript', 'python', 'html', 'css', 'markdown'],
        tabReplace: '  '
      },
      codeEditor: {
        classPrefix: 'editor-',
        tabReplace: '    ',
        useBR: false
      },
      blog: {
        classPrefix: 'blog-syntax-',
        languages: ['javascript', 'python', 'html', 'css'],
        tabReplace: '  '
      }
    };
  }
  
  configureFor(context) {
    const config = this.contexts[context];
    if (config) {
      hljs.configure(config);
    }
  }
  
  highlight(code, language, context = 'default') {
    if (context !== 'default') {
      this.configureFor(context);
    }
    return hljs.highlight(code, {language});
  }
}

Server-Side Configuration

// Node.js server configuration
const hljs = require('highlight.js');

hljs.configure({
  classPrefix: 'hljs-',
  useBR: false,        // Use \n for server-side rendering
  tabReplace: '  ',    // Consistent spacing
  languages: ['javascript', 'python', 'html', 'css', 'sql']
});

// Express.js middleware example
app.use((req, res, next) => {
  res.locals.highlight = (code, language) => {
    return hljs.highlight(code, {language}).value;
  };
  next();
});