Core Highlighting

/**
 * Highlights code with specified language or options
 * @param code - The code string to highlight
 * @param options - Highlighting options including language
 * @returns HighlightResult with syntax-highlighted HTML
 */
function highlight(code: string, options: HighlightOptions): HighlightResult;

/**
 * @deprecated Use highlight(code, {language: languageName, ignoreIllegals: ignoreIllegals})
 * Highlights code with specified language (legacy signature)
 * @param languageName - Name of the language to use for highlighting
 * @param code - The code string to highlight
 * @param ignoreIllegals - Whether to ignore illegal syntax
 * @returns HighlightResult with syntax-highlighted HTML
 */
function highlight(languageName: string, code: string, ignoreIllegals?: boolean): HighlightResult;

interface HighlightOptions {
  /** Language name to use for highlighting */
  language: string;
  /** Whether to ignore illegal syntax patterns */
  ignoreIllegals?: boolean;
}

interface HighlightResult {
  /** Original code string (optional) */
  code?: string;
  /** Relevance score indicating confidence in language detection */
  relevance: number;
  /** Syntax-highlighted HTML string */
  value: string;
  /** Detected or specified language name */
  language?: string;
  /** Whether illegal syntax was encountered */
  illegal: boolean;
  /** Error that occurred during highlighting, if any */
  errorRaised?: Error;
  /** Second-best language match for auto-detection */
  secondBest?: Omit<HighlightResult, 'secondBest'>;
}

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

// Modern API with options object
const result = hljs.highlight('console.log("Hello, World!");', { 
  language: 'javascript' 
});
console.log(result.value); // '<span class="hljs-variable">console</span>...'
console.log(result.relevance); // 10

// Handle illegal syntax gracefully  
const badCode = hljs.highlight('invalid syntax here', { 
  language: 'javascript',
  ignoreIllegals: true 
});

// Legacy API (deprecated)
const legacyResult = hljs.highlight('javascript', 'console.log("Hello");');

/**
 * Automatically detects language and highlights code
 * @param code - The code string to highlight
 * @param languageSubset - Optional array of language names to consider
 * @returns AutoHighlightResult with detected language and highlighted HTML
 */
function highlightAuto(code: string, languageSubset?: string[]): AutoHighlightResult;

interface AutoHighlightResult extends HighlightResult {
  /** Detected language with highest relevance score */
  language?: string;
  /** Second-best language match */
  secondBest?: Omit<HighlightResult, 'secondBest'>;
}

// Detect language automatically
const autoResult = hljs.highlightAuto(`
function fibonacci(n) {
  return n < 2 ? n : fibonacci(n - 1) + fibonacci(n - 2);
}
`);
console.log(autoResult.language); // 'javascript'
console.log(autoResult.relevance); // 15

// Limit detection to specific languages
const limitedResult = hljs.highlightAuto(`
def fibonacci(n):
    return n if n < 2 else fibonacci(n-1) + fibonacci(n-2)
`, ['python', 'ruby', 'javascript']);
console.log(limitedResult.language); // 'python'

// Check second-best match
if (autoResult.secondBest) {
  console.log('Second choice:', autoResult.secondBest.language);
}

/**
 * Highlights all pre>code blocks on the page
 * Looks for elements matching the configured CSS selector (default: 'pre code')
 * Uses class names or data attributes to determine language
 */
function highlightAll(): void;

// HTML setup
/*
<pre><code class="language-javascript">
console.log("This will be highlighted");
</code></pre>

<pre><code class="hljs python">
print("This will be highlighted as Python")
</code></pre>

<pre><code>
// Language will be auto-detected
function hello() { console.log("Hi!"); }
</code></pre>
*/

// Highlight all code blocks
hljs.highlightAll();

// Configure before highlighting
hljs.configure({ 
  classPrefix: 'code-',
  cssSelector: 'pre code, .code-block' 
});
hljs.highlightAll();

/**
 * Highlights a single DOM element
 * @param element - The HTML element containing code to highlight
 */
function highlightElement(element: HTMLElement): void;

type HighlightedHTMLElement = HTMLElement & {
  /** Result object attached after highlighting */
  result?: HighlightResult;
  /** Second-best language match */
  secondBest?: HighlightResult;
  parentNode: HTMLElement;
};

// Get element and highlight it
const codeElement = document.querySelector('#my-code');
hljs.highlightElement(codeElement);

// Access highlighting results
console.log(codeElement.result.language);
console.log(codeElement.result.relevance);

// Highlight multiple elements individually
document.querySelectorAll('pre code').forEach(el => {
  hljs.highlightElement(el);
});

// Check if element was already highlighted
if (!codeElement.classList.contains('hljs')) {
  hljs.highlightElement(codeElement);
}

/**
 * @deprecated since v10.7.0, will be removed in v12.0
 * Use highlightElement() instead
 * @param element - The HTML element containing code to highlight
 */
function highlightBlock(element: HTMLElement): void;

// Old way (deprecated)
hljs.highlightBlock(element);

// New way
hljs.highlightElement(element);

try {
  const result = hljs.highlight('malformed code', { language: 'nonexistent' });
} catch (error) {
  console.error('Highlighting failed:', error.message);
}

// Check for errors in result
const result = hljs.highlightAuto('some code');
if (result.errorRaised) {
  console.warn('Highlighting error:', result.errorRaised);
}

// Use ignoreIllegals to handle syntax errors gracefully
const safeResult = hljs.highlight('bad syntax', {
  language: 'javascript',
  ignoreIllegals: true
});