Enhance Code Emphasis

The enhanceCodeEmphasis source enhancer adds visual emphasis to specific lines in code examples by marking them with a data-hl attribute. This allows you to highlight important code patterns or call attention to specific sections in demos using simple comment annotations.

Features

• Single-line emphasis with @highlight comments
• Multi-line emphasis blocks with @highlight-start / @highlight-end pairs
• Text highlighting within a line with @highlight-text "text"
• Optional descriptions in quoted strings (e.g., @highlight "description")
• Strong emphasis with ! at the end of descriptions (e.g., @highlight "We must do this!")
• Automatic strong emphasis for nested blocks - lines inside multiple emphasis ranges are automatically marked as strong
• Works with all code languages that support comments
• Compatible with both inline and block comment styles

Basic Usage

import { enhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';

// Use as a source enhancer
const sourceEnhancers = [enhanceCodeEmphasis];

// Pass to CodeHighlighter or use with enhanceCode

The enhancer processes @highlight comments in your source files and adds data-hl to the corresponding line elements in the HAST tree.

Comment Patterns

Single Line Emphasis

Emphasize the line containing the comment:

export default function Button() {
  return (
    <button className="primary">Click me</button> {/* @highlight */}
  );
}

The line with the <button> element will be emphasized.

Single Line with Description

Add context about what's being emphasized:

export default function Component() {
  const [count, setCount] = useState(0); // @highlight "We track state"

  return <div>{count}</div>;
}

Strong Emphasis

End a description with ! to mark it as strong emphasis (data-hl="strong"):

export default function Component() {
  const apiKey = process.env.API_KEY; // @highlight "We must provide the API key!"

  return <div>...</div>;
}

Strong emphasis is useful for highlighting critical code that users must pay attention to or modify.

Multi-line Emphasis

Emphasize a range of lines between start and end markers:

export default function Component() {
  return (
    // @highlight-start
    <div>
      <h1>Heading 1</h1>
      <p>Some content</p>
    </div>
    // @highlight-end
  );
}

Lines 4-7 (from <div> through </div>) will be emphasized. The range starts at the first line after @highlight-start and ends at the last line before @highlight-end.

Multi-line with Description

Explain what the emphasized section demonstrates:

export default function Component() {
  return (
    // @highlight-start "We add a heading with an h1"
    <div>
      <h1>Heading 1</h1>
    </div>
    // @highlight-end
  );
}

Text Highlighting

Highlight specific text within a line:

export default function Component() {
  return (
    <div>
      <h1>Heading 1</h1> {/* @highlight-text "Heading 1" */}
    </div>
  );
}

This wraps the specified text in a <span data-hl=""> element, allowing you to highlight a specific word or phrase within a line rather than the entire line.

Comment Syntax

Supported Formats

The enhancer recognizes these comment patterns:

Description Format

Descriptions are provided as quoted strings:

// @highlight "We initialize the state"
const [value, setValue] = useState(0);

// @highlight-start "We render the component"
<div>
  <p>Content</p>
</div>;
// @highlight-end

Displaying Comments in Documentation

By default, @highlight comments are stripped from the rendered code. To show the comment syntax in documentation (while still applying the emphasis), use the displayComments code block attribute:

```jsx displayComments
export default function Button() {
  return (
    <button className="primary">Click me</button> {/* @highlight */}
  );
}
```

This is useful for documentation pages where you want to show users the comment syntax itself.

Advanced Patterns

Multiple Single Lines

You can emphasize multiple individual lines:

export default function Form() {
  const [name, setName] = useState(''); // @highlight
  const [email, setEmail] = useState(''); // @highlight

  return (
    <form>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      <input value={email} onChange={(e) => setEmail(e.target.value)} /> {/* @highlight */}
    </form>
  );
}

Nested Multi-line Blocks

The enhancer handles nested emphasis blocks using a stack-based algorithm. Lines that fall within multiple emphasis ranges are automatically marked with strong emphasis (data-hl="strong"):

export default function Component() {
  return (
    // @highlight-start "outer block"
    <div>
      <header>Title</header>
      {/* @highlight-start "inner block"  */}
      <main>
        <p>Content</p>
      </main>
      {/* @highlight-end  */}
      <footer>Footer</footer>
    </div>
    // @highlight-end
  );
}

In this example:

• The outer block lines (<div>, <header>, <footer>, </div>) get normal emphasis
• The inner block lines (<main>, <p>, </main>) get strong emphasis because they're nested within both ranges
• Position markers (data-hl-position) are preserved from the innermost range

Mixed Single and Multi-line

Combine both patterns in the same file:

export default function Dashboard() {
  const [data, setData] = useState([]); // @highlight

  return (
    <div>
      <Header />
      {/* @highlight-start */}
      <Chart data={data} />
      <Table data={data} />
      {/* @highlight-end */}
      <Footer /> {/* @highlight */}
    </div>
  );
}

Implementation Details

How It Works

1. Comment Extraction: Comments are extracted during parsing with notableCommentsPrefix: ['@highlight']
2. Directive Parsing: The enhancer scans comments for @highlight, @highlight-start, @highlight-end, and @highlight-text patterns
3. Line Calculation: Single-line directives mark their own line; multi-line directives mark all lines from the first line after @highlight-start to the last line before @highlight-end
4. Nested Detection: Lines inside multiple ranges are automatically marked as strong emphasis
5. HAST Modification: The enhancer traverses the HAST tree and adds dataHl: '' (or dataHl: 'strong' for nested lines or descriptions ending with !) to line elements

HAST Structure

Lines in the HAST tree have this structure after enhancement:

{
  type: 'element',
  tagName: 'span',
  properties: {
    className: 'line',
    dataLn: 3,                              // Line number
    dataHl: '',                             // Added by enhancer (or 'strong' for nested/!)
    dataHlDescription: 'We track state',    // Optional description
    dataHlPosition: 'single',               // 'single' | 'start' | 'end' for line position
  },
  children: [/* code tokens */]
}

For text highlighting with @highlight-text "text", the specified text within the line is wrapped in a span:

{
  type: 'element',
  tagName: 'span',
  properties: { dataHl: '' },
  children: [{ type: 'text', value: 'text' }]
}

Data Attributes

The enhancer adds these attributes to line elements:

For single-line emphasis with @highlight:

• data-hl is set (or data-hl="strong" if description ends with !)
• data-hl-description is set if a description was provided
• data-hl-position="single" is set to distinguish from multiline range boundaries

For multi-line emphasis with @highlight-start / @highlight-end:

• data-hl is set on all lines in the range (or data-hl="strong" if description ends with ! or line is nested)
• data-hl-description is set on the first line (if provided)
• data-hl-position="start" is set on the first line (only for ranges with more than one line)
• data-hl-position="end" is set on the last line (only for ranges with more than one line)

For text highlighting with @highlight-text "text":

• The specified text within the line is wrapped in a <span data-hl=""> element
• The line element itself does not receive any additional attributes

Stack-Based Pairing

Multi-line directives are paired using a stack:

• @highlight-start pushes onto the stack
• @highlight-end pops from the stack and emphasizes the range
• Inner (nested) ranges are processed before outer ranges
• Lines that appear in multiple ranges are automatically marked as strong emphasis
• Position markers from inner ranges are preserved when outer ranges are processed

Configuration

Adding to Source Enhancers

Configure in your webpack loader or server-side loading:

import { enhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
import { createLoadServerSource } from '@mui/internal-docs-infra/pipeline/loadServerSource';
import { loadCodeVariant } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const sourceEnhancers = [enhanceCodeEmphasis];

// Create a loadSource that extracts emphasis comments
const loadSource = createLoadServerSource({
  notableCommentsPrefix: ['@highlight'],
  removeCommentsWithPrefix: ['@highlight'],
});

// Use with loadCodeVariant
const { code } = await loadCodeVariant(url, variantName, variant, {
  loadSource,
  sourceEnhancers,
  sourceParser,
});

// Or with CodeHighlighter
<CodeHighlighter
  sourceEnhancers={sourceEnhancers}
  // ... other props
/>

// Or with useCode
const { selectedFile } = useCode(props, {
  sourceEnhancers,
});

Comment Prefix

The default comment prefix is @highlight, exported as EMPHASIS_COMMENT_PREFIX:

import { EMPHASIS_COMMENT_PREFIX } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';

console.log(EMPHASIS_COMMENT_PREFIX); // '@highlight'

To use a different prefix, you would need to create a custom enhancer based on this implementation.

Styling Emphasized Lines

The data-hl attribute can be targeted with CSS. First, ensure lines are displayed as blocks for proper highlighting:

/* Required: Display lines as blocks for line-based highlighting */
.frame[data-lined] {
  display: block;
  white-space: normal;
}

.frame[data-lined] .line {
  display: block;
  white-space: pre;
}

/* Highlight emphasized lines */
.line[data-hl] {
  background-color: rgba(255, 255, 0, 0.1);
  border-left: 2px solid #ffd700;
  padding-left: 8px;
}

/* Strong emphasis for critical lines (descriptions ending with !) */
.line[data-hl='strong'] {
  background-color: rgba(255, 100, 100, 0.15);
  border-left: 3px solid #ff4444;
}

/* Single-line emphasis - rounded on all corners */
.line[data-hl-position='single'] {
  border-radius: 4px;
}

/* Multiline block start - rounded top corners */
.line[data-hl-position='start'] {
  border-top-left-radius: 4px;
  border-top-right-radius: 4px;
}

/* Multiline block end - rounded bottom corners */
.line[data-hl-position='end'] {
  border-bottom-left-radius: 4px;
  border-bottom-right-radius: 4px;
}

/* Dark mode variant */
@media (prefers-color-scheme: dark) {
  .line[data-hl] {
    background-color: rgba(255, 255, 0, 0.05);
    border-left-color: #b8860b;
  }

  .line[data-hl='strong'] {
    background-color: rgba(255, 100, 100, 0.1);
    border-left-color: #cc3333;
  }
}

Showing Descriptions

You can display the description using CSS ::before:

/* Show description as tooltip */
.line[data-hl-description]::before {
  content: attr(data-hl-description);
  position: absolute;
  /* ... tooltip styles */
}

Best Practices

Be Specific

Use single-line emphasis for specific statements:

// ✓ Good - highlights the important line
const result = await fetchData();

// ✗ Avoid - too vague
function processData() {
  const result = await fetchData();
  return result;
}

Use Descriptions

Add context when the emphasis isn't obvious:

// ✓ Good - explains what to notice
<div className="container"> {/* @highlight "We add the container class" */}

// ✗ Less helpful - just marks the line
<div className="container"> {/* @highlight */}

Group Related Lines

Use multi-line emphasis for logical code blocks:

// ✓ Good - emphasizes the complete pattern
// @highlight-start "We handle the form submission"
<form onSubmit={handleSubmit}>
  <input type="text" value={name} onChange={handleChange} />
  <button type="submit">Submit</button>
</form>
// @highlight-end

Match Comment Style

Use the appropriate comment style for your language:

// JSX/TSX - use {/* */} for inline, // for block
<div>{/* @highlight */}</div>
// @highlight-start

// JavaScript/TypeScript - use //
const x = 42; // @highlight

// CSS - use /* */
.button {
  color: blue; /* @highlight */
}

Troubleshooting

Lines Not Being Emphasized

Check that:

1. Comments are being extracted with notableCommentsPrefix: ['@highlight']
2. The comment syntax exactly matches the expected patterns
3. Multi-line pairs have matching start/end markers
4. Line numbers in the HAST tree match your source

Unmatched Multi-line Pairs

If you have unmatched @highlight-start or @highlight-end:

• Extra @highlight-end → ignored (no effect)
• Extra @highlight-start → ignored (no matching end)

Check your code for balanced pairs.

Wrong Lines Emphasized

Verify that:

• Comments are on the correct lines in your source
• Line numbers in HAST tree match (check dataLn properties)
• Comment extraction isn't removing the comments from the source

Type Definitions

/**
 * Source enhancer that adds emphasis to code lines based on @highlight comments.
 */
export const enhanceCodeEmphasis: SourceEnhancer;

/**
 * The prefix used to identify emphasis comments in source code.
 */
export const EMPHASIS_COMMENT_PREFIX: '@highlight';

/**
 * Source enhancer function type.
 */
type SourceEnhancer = (
  root: HastRoot,
  comments: SourceComments | undefined,
  fileName: string,
) => HastRoot | Promise<HastRoot>;

/**
 * Comments extracted from source code, keyed by line number.
 */
type SourceComments = Record<number, string[]>;

Related

• Parse Source - Syntax highlighting and HAST generation
• HAST Utilities - Converting HAST to React JSX
• Load Server Source - Loading source files with enhancers
• Code Highlighter - Displaying code with emphasis