tessl/npm-gatsby-remark-prismjs

Adds syntax highlighting to code blocks at build time using PrismJS

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Syntax Highlighting

Name: tessl/npm-gatsby-remark-prismjs
Author: tessl

Core syntax highlighting functionality with support for all PrismJS languages, dynamic language loading, and diff syntax highlighting.

Capabilities

Highlight Code Function

Core syntax highlighting function that processes code strings using PrismJS.

/**
 * Core syntax highlighting function using PrismJS
 * @param language - Programming language for syntax highlighting
 * @param code - Code string to highlight
 * @param additionalEscapeCharacters - Additional HTML entities to escape
 * @param lineNumbersHighlight - Array of line numbers to highlight
 * @param noInlineHighlight - Whether to skip inline highlighting
 * @param diffLanguage - Language for diff highlighting
 * @returns HTML string with syntax highlighting
 */
function highlightCode(
  language: string,
  code: string,
  additionalEscapeCharacters?: Record<string, string>,
  lineNumbersHighlight?: number[],
  noInlineHighlight?: boolean,
  diffLanguage?: string | null
): string;

Usage Examples:

// Basic highlighting
const highlighted = highlightCode("javascript", "const x = 42;");

// With line highlighting
const highlightedWithLines = highlightCode(
  "python", 
  "def hello():\n    print('Hello')", 
  {},
  [2]  // Highlight line 2
);

// Diff highlighting
const diffHighlighted = highlightCode(
  "diff",
  "- old line\n+ new line",
  {},
  [],
  false,
  "javascript"  // Diff of JavaScript code
);

Load Prism Language

Dynamically loads PrismJS language components on demand.

/**
 * Dynamically loads PrismJS language components
 * @param language - Language name or alias to load
 * @throws Error if language is not supported by PrismJS
 */
function loadPrismLanguage(language: string): void;

/**
 * Get the base language name from an alias
 * @param nameOrAlias - Language name or alias
 * @param components - PrismJS components registry
 * @returns Base language name or undefined
 */
function getBaseLanguageName(
  nameOrAlias: string, 
  components?: any
): string | undefined;

Usage Examples:

// Load a language before highlighting
loadPrismLanguage("rust");
loadPrismLanguage("typescript");

// Check if a language alias exists
const baseName = getBaseLanguageName("js"); // Returns "javascript"

Language Support

The plugin supports all PrismJS languages with automatic loading and alias resolution.

Supported Language Categories:

Web Technologies: HTML, CSS, JavaScript, TypeScript, JSX, TSX
Backend Languages: Python, Java, C#, PHP, Ruby, Go, Rust
System Languages: C, C++, Assembly, Shell/Bash
Data Languages: JSON, YAML, XML, SQL, GraphQL
Markup: Markdown, LaTeX, reStructuredText
Configuration: INI, TOML, Properties
**And 200+ more languages...

Diff Syntax Highlighting

Special syntax highlighting for diff blocks with language-specific highlighting.

Diff Language Syntax:

Use diff-<language> to enable syntax highlighting within diffs
Example: diff-javascript, diff-python, diff-css

Usage Examples:

```diff-javascript
function hello() {
- console.log("Hello");
+ console.log("Hello, World!");
}
```

```diff-css
.button {
- background: red;
+ background: blue;
  padding: 10px;
}
```

Error Handling

The highlighting system gracefully handles unsupported languages and syntax errors.

Error Behaviors:

Unsupported Language: Falls back to plain text with HTML escaping
none Language: Returns code without any processing or escaping
text Language: Applies HTML escaping but no syntax highlighting
Invalid Syntax: Processes what it can, leaves invalid parts as plain text

Console Warnings:

First occurrence of unsupported language triggers warning
Subsequent uses of same unsupported language are silent
Warnings include suggested fallback behavior

HTML Output Structure

The plugin generates a specific HTML structure with CSS classes and data attributes for styling.

Generated HTML Structure:

<div class="gatsby-highlight [has-highlighted-lines]" data-language="{languageName}">
  <pre class="{classPrefix}{languageName}[ line-numbers]"[ style="counter-reset: linenumber {start}"]>
    <code class="{classPrefix}{languageName}">
      <!-- Command line prompts if applicable -->
      <!-- Highlighted code content with <span class="token {tokenType}"> -->
    </code>
    <!-- Line numbers if enabled -->
  </pre>
</div>

CSS Classes Applied:

Container: Always gets gatsby-highlight class
Highlighted Lines: Adds has-highlighted-lines class when line highlighting is used
Language: Uses {classPrefix}{languageName} pattern (default: language-{languageName})
Line Numbers: Adds line-numbers class when enabled
Data Attribute: data-language="{languageName}" on container div

Example Output:

<!-- Basic highlighted code -->
<div class="gatsby-highlight" data-language="javascript">
  <pre class="language-javascript">
    <code class="language-javascript">
      <span class="token keyword">const</span> x <span class="token operator">=</span> <span class="token number">42</span><span class="token punctuation">;</span>
    </code>
  </pre>
</div>

<!-- With line numbers and highlighting -->
<div class="gatsby-highlight has-highlighted-lines" data-language="python">
  <pre class="language-python line-numbers" style="counter-reset: linenumber 0">
    <code class="language-python">
      <span class="token keyword">def</span> <span class="token function">hello</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span>
      <span class="gatsby-highlight-code-line">    <span class="token keyword">print</span><span class="token punctuation">(</span><span class="token string">"Hello"</span><span class="token punctuation">)</span></span>
    </code>
    <span aria-hidden="true" class="line-numbers-rows">
      <span></span>
      <span></span>
    </span>
  </pre>
</div>

<!-- With shell prompt -->
<div class="gatsby-highlight" data-language="bash">
  <pre class="language-bash">
    <code class="language-bash">
      <span class="command-line-prompt">
        <span data-user="root" data-host="localhost"></span>
      </span>
      <span class="token function">ls</span> <span class="token parameter variable">-la</span>
    </code>
  </pre>
</div>

HTML Escaping

Built-in HTML entity escaping for code content.

/**
 * Escapes HTML entities in code strings
 * @param code - Code string to escape
 * @param additionalHtmlEscapes - Additional entities to escape
 * @returns Escaped HTML string
 */
function escapeHTML(
  code: string, 
  additionalHtmlEscapes?: Record<string, string>
): string;

Default Escaped Entities:

& → &
> → >
< → <
" → "
' → '

Entity Precedence:

Base HTML escapes (listed above) are applied last
Additional escapes from escapeEntities option are applied first
Base escapes override additional escapes for same characters

Usage Example:

const escaped = escapeHTML(
  '<script>alert("XSS")</script>',
  { '{': '&#123;', '}': '&#125;' }
);
// Result: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;