Advanced line-based features including line highlighting, line numbering, and line hiding capabilities controlled through code block metadata or inline directives.
Parses language string and options from code block metadata to extract line-based feature configurations.
/**
* Parses language string and options from code block metadata
* @param language - Language string with optional metadata (e.g., "javascript{1,3-5}")
* @returns Parsed options object with line-based configurations or just language
*/
function parseOptions(language: string):
| { splitLanguage: string } // When no options present
| { // When options are present
splitLanguage: string;
highlightLines?: number[];
showLineNumbersLocal?: boolean;
numberLinesStartAt?: number;
outputLines?: number[];
promptUserLocal?: string;
promptHostLocal?: string;
};Usage Examples:
// Parse highlight ranges
parseOptions("javascript{1,3-5}");
// Returns: { splitLanguage: "javascript", highlightLines: [1,3,4,5] }
// Parse line numbering
parseOptions("python{numberLines: true}");
// Returns: { splitLanguage: "python", showLineNumbersLocal: true, numberLinesStartAt: 1 }
// Parse line numbering with custom start
parseOptions("java{numberLines: 10}");
// Returns: { splitLanguage: "java", showLineNumbersLocal: true, numberLinesStartAt: 10 }
// Parse shell prompt options
parseOptions("bash{promptUser: alice}{promptHost: server}");
// Returns: { splitLanguage: "bash", promptUserLocal: "alice", promptHostLocal: "server" }Highlight specific lines in code blocks using ranges or inline directives.
Metadata Syntax:
```javascript{1,3-5,8}
// Lines 1, 3, 4, 5, and 8 will be highlighted
```
```python{1-3,7}
# Lines 1, 2, 3, and 7 will be highlighted
```Inline Directive Syntax:
```javascript
const x = 42; // highlight-line
const y = 100;
// highlight-next-line
const z = x + y;
// highlight-start
function calculate(a, b) {
return a + b;
}
// highlight-end
// highlight-range{1,3-4}
const result = calculate(x, y);
```Add line numbers to code blocks with customizable starting positions.
Global Configuration:
// In gatsby-config.js
options: {
showLineNumbers: true // Enable for all code blocks
}Per-Block Configuration:
```javascript{numberLines: true}
// This block will show line numbers starting from 1
```
```python{numberLines: 5}
# This block will show line numbers starting from 5
```Required CSS:
// gatsby-browser.js
require("prismjs/plugins/line-numbers/prism-line-numbers.css")Hide specific lines from the rendered output while preserving line numbering.
Inline Directive Syntax:
```javascript
const secret = "hidden"; // hide-line
const visible = "shown";
// hide-next-line
const alsoHidden = "not shown";
// hide-start
const hiddenBlock = {
key: "value"
};
// hide-end
// hide-range{1,3-4}
const moreCode = true;
```Generates HTML structure for line numbering display.
/**
* Generates HTML for line numbering display
* @param code - Highlighted code string
* @returns HTML string with line number spans
*/
function addLineNumbers(code?: string): string;Usage Example:
const numberedHTML = addLineNumbers(highlightedCode);
// Returns: '<span aria-hidden="true" class="line-numbers-rows">...</span>'Processes highlight and hide directives within code, splitting into manageable segments.
/**
* Processes highlight/hide directives and line ranges in code
* @param code - Highlighted code string with directives
* @param highlights - Array of line numbers to highlight from metadata
* @returns Array of code segments with highlight/hide flags
*/
function handleDirectives(
code: string,
highlights?: number[]
): Array<{
code: string;
highlight: boolean;
hide: boolean;
flagSources: Array<{
feature: string;
index: number;
directive: string;
}>;
}>;Directive Types:
Error Handling:
// Throws error if line is both hidden and highlighted
// Error: "Line 5 has been marked as both hidden and highlighted."The line features system generates specific CSS classes for styling:
.gatsby-highlight: Container wrapper for code blocks.gatsby-highlight-code-line: Individual highlighted lines.line-numbers: Code blocks with line numbering enabled.line-numbers-rows: Container for line number spans.has-highlighted-lines: Code blocks containing highlighted linesRequired CSS Examples:
/* Line highlighting */
.gatsby-highlight-code-line {
background-color: #feb;
display: block;
margin-right: -1em;
margin-left: -1em;
padding-right: 1em;
padding-left: 0.75em;
border-left: 0.25em solid #f99;
}
/* Container styling */
.gatsby-highlight {
background-color: #fdf6e3;
border-radius: 0.3em;
margin: 0.5em 0;
padding: 1em;
overflow: auto;
}
/* Line numbers positioning */
.gatsby-highlight pre[class*="language-"].line-numbers {
padding-left: 2.8em;
}