Configuration

/**
 * Configure global highlight.js options
 * @param options - Partial configuration object with options to set
 */
function configure(options: Partial<HLJSOptions>): void;

interface HLJSOptions {
  /** Regex pattern for elements to skip during highlightAll() */
  noHighlightRe: RegExp;
  /** Regex pattern to detect language from CSS classes */
  languageDetectRe: RegExp;
  /** CSS class name prefix for highlighted elements */
  classPrefix: string;
  /** CSS selector for finding code elements */
  cssSelector: string;
  /** Array of language names to restrict auto-detection to */
  languages?: string[];
  /** Custom emitter constructor (advanced usage) */
  __emitter: EmitterConstructor;
  /** Whether to ignore unescaped HTML in code */
  ignoreUnescapedHTML?: boolean;
  /** Whether to throw errors on unescaped HTML */
  throwUnescapedHTML?: boolean;
}

import hljs from '@highlightjs/cdn-assets/es/highlight.js';

// Configure CSS class prefix
hljs.configure({
  classPrefix: 'syntax-'
});
// Now generates <span class="syntax-keyword"> instead of <span class="hljs-keyword">

// Configure CSS selector for finding code blocks
hljs.configure({
  cssSelector: 'pre code, .code-block, .highlight'
});

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

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

// Security configurations
hljs.configure({
  ignoreUnescapedHTML: false,  // Default behavior
  throwUnescapedHTML: true     // Throw errors on unescaped HTML
});

// Skip certain elements during highlightAll()
hljs.configure({
  noHighlightRe: /^no-?highlight$/i
});

/**
 * Initialize highlighting for the current page
 * Equivalent to calling highlightAll() but intended for manual initialization
 */
function initHighlighting(): void;

// Manual initialization after DOM is ready
document.addEventListener('DOMContentLoaded', () => {
  hljs.initHighlighting();
});

// Initialize after dynamically adding content
function addCodeBlock(code, language) {
  const pre = document.createElement('pre');
  const codeEl = document.createElement('code');
  codeEl.className = `language-${language}`;
  codeEl.textContent = code;
  pre.appendChild(codeEl);
  document.body.appendChild(pre);
  
  // Re-initialize highlighting
  hljs.initHighlighting();
}

// Configure before initializing
hljs.configure({ classPrefix: 'code-' });
hljs.initHighlighting();

/**
 * Initialize highlighting automatically when DOM is loaded
 * Uses DOMContentLoaded event to trigger highlighting
 */
function initHighlightingOnLoad(): void;

// Set up automatic highlighting
hljs.initHighlightingOnLoad();

// This is equivalent to:
document.addEventListener('DOMContentLoaded', () => {
  hljs.highlightAll();
});

// Configure before auto-initialization
hljs.configure({
  cssSelector: 'pre code, .code',
  classPrefix: 'hl-'
});
hljs.initHighlightingOnLoad();

// Use custom CSS class prefix
hljs.configure({ classPrefix: 'syntax-' });

// CSS to style with custom prefix
/*
.syntax-keyword { color: blue; }
.syntax-string { color: green; }
.syntax-number { color: orange; }
*/

// Only allow specific languages for auto-detection
hljs.configure({
  languages: ['javascript', 'typescript', 'python', 'json']
});

// This affects highlightAuto() and highlightAll()
const result = hljs.highlightAuto('print("hello")');
// Will only consider the specified languages

// Strict HTML handling
hljs.configure({
  ignoreUnescapedHTML: false,
  throwUnescapedHTML: true
});

try {
  // This might throw if code contains unescaped HTML
  const result = hljs.highlight('<script>alert("xss")</script>', {
    language: 'html'
  });
} catch (error) {
  console.error('Security error:', error);
}

// Target different elements for highlighting
hljs.configure({
  cssSelector: '.code-sample, pre code, .highlight code'
});

// HTML that will be highlighted:
/*
<div class="code-sample">console.log("hello");</div>
<pre><code>print("world")</code></pre>
<div class="highlight"><code>function test() {}</code></div>
*/

hljs.highlightAll();

// Configure elements to skip
hljs.configure({
  noHighlightRe: /^(no-highlight|nohighlight|plain)$/i
});

// HTML that will be skipped:
/*
<pre><code class="no-highlight">
This will not be highlighted
</code></pre>

<pre><code class="nohighlight">
This will also be skipped
</code></pre>

<pre><code class="javascript">
// This will be highlighted as JavaScript
console.log("hello");
</code></pre>
*/

// Custom language detection regex
hljs.configure({
  languageDetectRe: /\b(lang|language|syntax)-([\w-]+)\b/i
});

// HTML that will be detected:
/*
<code class="lang-python">print("hello")</code>
<code class="language-javascript">console.log("hi")</code>
<code class="syntax-cpp">int main() {}</code>
*/

// Default configuration (for reference)
const defaultConfig = {
  noHighlightRe: /^no-?highlight$/i,
  languageDetectRe: /\blang(?:uage)?-([\w-]+)\b/i,
  classPrefix: 'hljs-',
  cssSelector: 'pre code',
  languages: undefined, // No restriction
  ignoreUnescapedHTML: false,
  throwUnescapedHTML: false
};

// Theme-specific configuration
function applyDarkTheme() {
  hljs.configure({
    classPrefix: 'dark-'
  });
  // Load dark theme CSS
  const link = document.createElement('link');
  link.rel = 'stylesheet';
  link.href = '@highlightjs/cdn-assets/styles/dark.css';
  document.head.appendChild(link);
}

// Environment-specific configuration  
if (process.env.NODE_ENV === 'development') {
  hljs.configure({
    throwUnescapedHTML: true // Strict checking in development
  });
} else {
  hljs.configure({
    ignoreUnescapedHTML: true // Graceful handling in production
  });
}

// Dynamic configuration based on user preferences
function configureForUser(userPrefs) {
  hljs.configure({
    classPrefix: userPrefs.codeTheme === 'dark' ? 'dark-' : 'light-',
    languages: userPrefs.allowedLanguages || undefined
  });
}