CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-highlight-js

Syntax highlighting with language autodetection for over 190 programming languages and markup formats.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

modes-utilities.mddocs/

Built-in Modes & Utilities

Pre-built modes and utility functions for common programming language constructs, plus regex helper utilities for building custom language definitions.

Capabilities

String Modes

Pre-defined modes for handling different types of string literals.

/** Double-quoted string mode with escape sequences */
const QUOTE_STRING_MODE: Mode;

/** Single-quoted string mode with escape sequences */
const APOS_STRING_MODE: Mode;

/** Backslash escape sequences for strings */
const BACKSLASH_ESCAPE: Mode;

Usage Examples:

// Using built-in string modes in custom languages
hljs.registerLanguage('mylang', function(hljs) {
  return {
    contains: [
      hljs.QUOTE_STRING_MODE,    // "double quoted strings"
      hljs.APOS_STRING_MODE,     // 'single quoted strings'
      {
        className: 'string',
        begin: '`',
        end: '`',
        contains: [hljs.BACKSLASH_ESCAPE]  // Template strings with escapes
      }
    ]
  };
});

// Customizing string modes
const CUSTOM_STRING_MODE = {
  ...hljs.QUOTE_STRING_MODE,
  className: 'custom-string',
  relevance: 5
};

Comment Modes

Standard comment patterns for various programming languages.

/** C-style line comments (//) */
const C_LINE_COMMENT_MODE: Mode;

/** C-style block comments (/* */) */
const C_BLOCK_COMMENT_MODE: Mode;

/** Hash-style comments (#) */
const HASH_COMMENT_MODE: Mode;

/** 
 * Custom comment mode factory
 * @param begin - Comment start pattern
 * @param end - Comment end pattern  
 * @param modeOptions - Additional mode options
 */
function COMMENT(begin: string | RegExp, end: string | RegExp, modeOptions?: Mode): Mode;

Usage Examples:

// Using built-in comment modes
hljs.registerLanguage('c-like', function(hljs) {
  return {
    contains: [
      hljs.C_LINE_COMMENT_MODE,    // // line comments
      hljs.C_BLOCK_COMMENT_MODE,   // /* block comments */
    ]
  };
});

hljs.registerLanguage('shell-like', function(hljs) {
  return {
    contains: [
      hljs.HASH_COMMENT_MODE       // # hash comments
    ]  
  };
});

// Creating custom comment modes
const XML_COMMENT_MODE = hljs.COMMENT('<!--', '-->', {
  relevance: 10
});

const SQL_COMMENT_MODE = hljs.COMMENT('--', '$', {
  relevance: 0
});

const PASCAL_COMMENT_MODE = hljs.COMMENT('{', '}', {
  relevance: 0
});

// Multi-line comment variations
const PYTHON_DOCSTRING_MODE = hljs.COMMENT('"""', '"""', {
  className: 'docstring',
  relevance: 10
});

Number Modes

Modes for recognizing numeric literals in different formats.

/** Basic integer and decimal numbers */
const NUMBER_MODE: Mode;

/** C-style numbers including hex, octal, binary, scientific notation */
const C_NUMBER_MODE: Mode;

/** Binary number literals (0b prefix) */
const BINARY_NUMBER_MODE: Mode;

Usage Examples:

// Using number modes
hljs.registerLanguage('calculator', function(hljs) {
  return {
    contains: [
      hljs.C_NUMBER_MODE,          // 123, 0xFF, 1.23e-4, etc.
      hljs.BINARY_NUMBER_MODE      // 0b1010101
    ]
  };
});

// Basic numbers only
hljs.registerLanguage('simple-math', function(hljs) {
  return {
    contains: [
      hljs.NUMBER_MODE             // 123, 45.67
    ]
  };
});

// Custom number mode
const CURRENCY_MODE = {
  className: 'number',
  begin: /\$\d+(\.\d{2})?/,
  relevance: 10
};

Other Built-in Modes

Additional utility modes for common language constructs.

/** Regular expression literals */
const REGEXP_MODE: Mode;

/** Function/method/class titles */
const TITLE_MODE: Mode;

/** Titles that can contain underscores */
const UNDERSCORE_TITLE_MODE: Mode;

/** Guard against method names being highlighted as keywords */
const METHOD_GUARD: Mode;

/** Common English words mode */
const PHRASAL_WORDS_MODE: Mode;

/**
 * Shebang line mode factory
 * @param options - Mode options including binary pattern
 */
function SHEBANG(options?: Partial<Mode> & {binary?: string | RegExp}): Mode;

/**
 * Helper for modes where end pattern matches begin pattern
 * @param mode - Mode with begin pattern to match for end
 */
function END_SAME_AS_BEGIN(mode: Mode): Mode;

Usage Examples:

// JavaScript-like language with regex support
hljs.registerLanguage('js-like', function(hljs) {
  return {
    contains: [
      hljs.REGEXP_MODE,            // /regex/flags
      hljs.C_LINE_COMMENT_MODE,
      hljs.QUOTE_STRING_MODE
    ]
  };
});

// Language with shebang support
hljs.registerLanguage('script', function(hljs) {
  return {
    contains: [
      hljs.SHEBANG(),              // #!/bin/bash, #!/usr/bin/env python
      hljs.HASH_COMMENT_MODE
    ]
  };
});

// Custom shebang with specific binary
const PYTHON_SHEBANG = hljs.SHEBANG({
  binary: /python[0-9.]*/
});

// Function definition with title
const FUNCTION_DEF = {
  beginKeywords: 'function def class',
  end: /[{(:]/,
  contains: [
    hljs.TITLE_MODE              // Function/class names
  ]
};

// Heredoc-style strings
const HEREDOC_MODE = hljs.END_SAME_AS_BEGIN({
  begin: /<<<(\w+)/,
  end: /(\w+)/,
  className: 'string'
});

Regular Expression Constants

Pre-defined regex patterns for common programming constructs.

/** Basic identifier pattern [a-zA-Z_][a-zA-Z0-9_]* */
const IDENT_RE: string;

/** Identifier allowing leading underscores */
const UNDERSCORE_IDENT_RE: string;

/** Number pattern matching integers and decimals */
const NUMBER_RE: string;

/** C-style number pattern with hex, scientific notation */
const C_NUMBER_RE: string;

/** Binary number pattern */
const BINARY_NUMBER_RE: string;

/** Characters that can start a regex literal */
const RE_STARTERS_RE: string;

/** Pattern that matches nothing (useful for placeholders) */
const MATCH_NOTHING_RE: string;

Usage Examples:

// Using regex constants in custom modes
hljs.registerLanguage('custom', function(hljs) {
  return {
    keywords: 'if else while for',
    contains: [
      {
        className: 'variable',
        begin: hljs.IDENT_RE + '\\s*=',
        end: hljs.MATCH_NOTHING_RE
      },
      {
        className: 'number',
        begin: hljs.C_NUMBER_RE,
        relevance: 0
      }
    ]
  };
});

// Building complex patterns
const FUNCTION_CALL = {
  className: 'function-call',
  begin: hljs.IDENT_RE + '\\s*\\(',
  returnBegin: true,
  contains: [
    {
      className: 'function-name',
      begin: hljs.IDENT_RE,
      end: hljs.MATCH_NOTHING_RE
    }
  ]
};

Utility Functions

Object Inheritance Utility

Shallow merge utility for combining objects, commonly used in language definitions.

/**
 * Performs a shallow merge of multiple objects into one
 * @param original - Base object to extend
 * @param objects - Objects to merge into the original
 * @returns New merged object
 */
function inherit<T>(original: T, ...objects: Record<string, any>[]): T;

Usage Examples:

// Extending base modes
const BASE_STRING_MODE = {
  className: 'string',
  begin: '"',
  end: '"'
};

const INTERPOLATED_STRING_MODE = hljs.inherit(BASE_STRING_MODE, {
  contains: [
    {
      className: 'variable',
      begin: '\\$\\{',
      end: '\\}'
    }
  ]
});

// Language inheritance
const C_KEYWORDS = {
  keyword: 'if else while for do break continue return',
  type: 'int char float double void',
  literal: 'true false null'
};

const CPP_KEYWORDS = hljs.inherit(C_KEYWORDS, {
  keyword: C_KEYWORDS.keyword + ' class public private protected virtual',
  type: C_KEYWORDS.type + ' bool string vector map'
});

// Mode extension
const BASE_MODE = {
  relevance: 5,
  illegal: /[{}]/
};

const EXTENDED_MODE = hljs.inherit(BASE_MODE, {
  className: 'custom',
  begin: 'start',
  end: 'end'
});

Regex Utilities

Helper functions for building complex regular expressions in language definitions.

const regex: {
  /** Concatenate regex patterns */
  concat(...args: (RegExp | string)[]): string;
  
  /** Create positive lookahead assertion */
  lookahead(re: RegExp | string): string;
  
  /** Create alternation pattern (a|b|c) */
  either(...args: (RegExp | string)[] | [...(RegExp | string)[], RegexEitherOptions]): string;
  
  /** Make pattern optional (?) */
  optional(re: RegExp | string): string;
  
  /** Create zero-or-more quantifier (*) */
  anyNumberOfTimes(re: RegExp | string): string;
};

interface RegexEitherOptions {
  capture?: boolean;
}

Usage Examples:

const { regex } = hljs;

// Building complex patterns
const IDENTIFIER = /[a-zA-Z_][a-zA-Z0-9_]*/;
const NUMBER = /\d+(\.\d+)?/;

// Concatenation
const VARIABLE_ASSIGNMENT = regex.concat(
  IDENTIFIER,
  /\s*=\s*/,
  regex.either(NUMBER, /"[^"]*"/, IDENTIFIER)
);

// Optional patterns
const FUNCTION_DECLARATION = regex.concat(
  'function',
  /\s+/,
  IDENTIFIER,
  regex.optional(/\s*<[^>]*>/),  // Optional generics
  /\s*\(/
);

// Alternation with capture groups
const STRING_LITERAL = regex.either(
  /"[^"]*"/,
  /'[^']*'/,
  /`[^`]*`/,
  { capture: false }
);

// Lookahead assertions
const KEYWORD_BOUNDARY = regex.concat(
  'class',
  regex.lookahead(/\s/)  // Must be followed by whitespace
);

// Repetition patterns
const MULTIPLE_DOTS = regex.anyNumberOfTimes(/\./);
const OPTIONAL_WHITESPACE = regex.anyNumberOfTimes(/\s/);

// Complex language constructs
hljs.registerLanguage('example', function(hljs) {
  const KEYWORD = regex.either(
    'if', 'else', 'while', 'for', 'function', 'class'
  );
  
  const TYPE_ANNOTATION = regex.concat(
    ':',
    regex.optional(/\s+/),
    regex.either('string', 'number', 'boolean', IDENTIFIER)
  );
  
  return {
    keywords: KEYWORD,
    contains: [
      {
        className: 'variable',
        begin: regex.concat(
          IDENTIFIER,
          regex.optional(TYPE_ANNOTATION),
          /\s*=/
        )
      },
      {
        className: 'function',
        begin: regex.concat(
          'function',
          /\s+/,
          IDENTIFIER,
          regex.lookahead(/\s*\(/)
        )
      }
    ]
  };
});

Advanced Mode Patterns

Self-Referencing Modes

// Mode that can contain itself
const NESTED_MODE = {
  className: 'nested',
  begin: '{',
  end: '}',
  contains: ['self']  // Can contain other instances of this mode
};

Conditional Modes

// Mode with variants based on context
const CONDITIONAL_STRING = {
  className: 'string',
  variants: [
    {
      begin: '"',
      end: '"',
      contains: [hljs.BACKSLASH_ESCAPE]
    },
    {
      begin: "'",
      end: "'",
      contains: [hljs.BACKSLASH_ESCAPE]
    },
    {
      begin: '`',
      end: '`',
      contains: [
        hljs.BACKSLASH_ESCAPE,
        {
          className: 'variable',
          begin: '\\$\\{',
          end: '\\}'
        }
      ]
    }
  ]
};

Context-Sensitive Modes

// Mode that changes behavior based on context
const CONTEXT_MODE = {
  className: 'context',
  begin: 'start',
  end: 'end',
  beginScope: 'context-begin',
  endScope: 'context-end',
  contains: [
    {
      className: 'inner',
      begin: 'inner',
      end: '$',
      endsParent: true  // Ends the parent context mode
    }
  ]
};

docs

configuration-modes.md

core-highlighting.md

dom-integration.md

index.md

language-management.md

modes-utilities.md

plugin-system.md

vue-integration.md

tile.json