function example() { }
// No line numbers
Line 1
Line 2 - highlighted
Line 3
Line 4 - highlighted
Line 5 - highlighted
Line 6 - highlighted
Line 7
Line 1
Line 2 - red highlight
Line 3
Line 1
Line 2 - highlighted (range 2-5)
Line 3 - highlighted
Line 4 - highlighted
Line 5 - highlighted
Line 6
Line 7 - highlighted (single)
Line 8
Line 9
Line 10 - highlighted (range 10-18)
Line 11 - highlighted
...
Line 18 - highlighted
Line 19
const x = 42;
def hello(): pass
```
### Borders (figure, fieldset, details)
**Attributes:**
- `data-cli-border` - Border color
- `data-cli-border-style` - Border style (round, single, double, classic, etc.)
- `data-cli-border-dim` - Dim border (true/false)
- `data-cli-title-color` - Title color (fieldset only)
- `data-cli-marker` - Marker (details only)
**Border styles:**
- `round` - ╭─╮│╰─╯
- `single` - ┌─┐││└─┘
- `double` - ╔═╗║╚═╝
- `classic` - +-+|+-+
- `bold` - ┏━┓┃┗━┛
- `singleDouble` - ╓─╖║╙─╜
- `doubleSingle` - ╒═╕│╘═╛
- `arrow` - ↘↓↙→←↗↑↖
**Examples:**
```html
Content
Content
Quote text``` ## Important Architecture Principles ### 1. config.yaml as Single Source of Truth **CRITICAL:** The `config.yaml` file is the **single source of truth** for all theme configuration. - ✅ All default values must be defined in `config.yaml` - ✅ All documentation examples must match `config.yaml` structure exactly - ✅ All code examples in AGENTS.md must reflect current `config.yaml` - ❌ Never add fallback values in JavaScript code - ❌ Never use hardcoded defaults scattered across files The `lib/utils/get-theme.js` file does NOT use fallback values - it reads directly from the config structure: **❌ WRONG:** ```javascript const codeColor = baseTheme.code?.block?.color ?? "yellowBright"; ``` **✅ CORRECT:** ```javascript const codeColor = baseTheme.code?.block?.color; ``` This ensures that the theme system is predictable and all defaults are defined in `config.yaml`, not scattered across JavaScript files. ### 2. Language Detection in Code Blocks Language detection is automatic via the `class` attribute: - `class="lang-javascript"` → JavaScript - `class="language-python"` → Python The library includes a mapping of 1100+ languages in `lib/data/languages.js`, converting short codes to display names (e.g., "js" → "JavaScript", "py" → "Python"). ### 3. Prefix/Suffix Pattern Many elements now use a consistent prefix/suffix pattern for wrapping markers: ```yaml element: prefix: marker: "[" color: "gray" suffix: marker: "]" color: "gray" ``` This applies to: - Code block language labels - Abbreviation titles - Link titles - Image alt text - Keyboard shortcuts (kbd) - Sample output (samp) - Subscript/superscript ### 4. Special Display Features with enabled Flags **CRITICAL PATTERN:** All special display features that can change the visual structure or add extra elements must be isolated in nested objects with an `enabled` flag. **Examples of special display features:** - Code block line numbers (`code.block.numbers.enabled`) - Code block language labels (`code.block.label.enabled`) - Link href display (`a.href.enabled`) - Link title display (`a.title.enabled`) - Diff-style markers for del/ins (`del.diff.enabled`, `ins.diff.enabled`) - Key-by-key styling for kbd (`kbd.key.enabled`) **Pattern structure:** ```yaml element: color: "base color" specialFeature: enabled: false # Must be false by default style: "variant" # Style variant (e.g., simple, git, box) marker: "symbol" # Display marker/symbol color: "feature color" # Color for the special feature ``` **Why this pattern:** - Ensures backward compatibility (features disabled by default) - Makes features discoverable in configuration - Provides clear on/off toggle without removing configuration - Separates base styling from enhanced features - All defaults centralized in config.yaml **When to use this pattern:** - ✅ Feature adds new visual elements (markers, labels, prefixes) - ✅ Feature changes display structure (line numbers, boxes) - ✅ Feature is optional enhancement (not core rendering) - ❌ Feature is just a color/style change (use simple color property) - ❌ Feature is core to element rendering (use direct property) ### 5. Attribute Inheritance (pre/code) For code blocks, custom attributes can be placed on either `
` or `` tags:
- Attributes on `` take precedence
- Attributes on `` are used as fallback
- This allows flexible customization at either level
## Implementation Guide for Agents
### Adding New Custom Attributes
1. **Update `lib/utilities.js`:**
```javascript
export const getCustomAttributes = (tag) => {
return {
// ... existing attributes
newAttribute: getAttribute(tag, 'data-cli-new-attribute', null),
};
};
```
2. **Update tag implementation:**
```javascript
import chalkString from 'chalk-string';
export const myTag = (tag, context) => {
const custom = getCustomAttributes(tag);
// ✅ CORRECT: Use theme value directly (no fallback)
const value = custom.newAttribute || context.theme.myTag.defaultValue;
// Apply color using chalkString
const coloredValue = chalkString(value, { colors: true })('text content');
// Use value in rendering
};
```
3. **Update config.yaml** (if needed):
```yaml
theme:
myTag:
defaultValue: "red bold" # All defaults must be in config.yaml
```
**Important:** When using `chalkString`:
- Always pass `{ colors: true }` as the second parameter
- The first parameter is the color string (chalk-string format)
- The returned function is then called with the text to style
```javascript
// ✅ CORRECT
const styledText = chalkString('red bold', { colors: true })('Hello');
// ❌ WRONG
const styledText = chalkString('red bold')('Hello'); // Missing { colors: true }
```
4. **Add examples:**
- Create example in `examples/html/tags-custom/`
- Update README.md documentation
5. **Synchronize with config.yaml:**
- When adding new theme properties, ALWAYS update `config.yaml` first
- Then update AGENTS.md "Theme Structure" section to match exactly
- Verify all examples use the same default values as `config.yaml`
- Never create documentation examples with different defaults
### Adding Special Display Features with enabled Flags
When adding a new optional display feature that changes visual structure or adds extra elements:
**1. Update config.yaml first:**
```yaml
theme:
myElement:
color: "base color"
specialFeature:
enabled: false # MUST be false by default
style: "simple" # Default style variant
marker: "→" # Default marker/symbol
color: "cyan" # Feature-specific color
```
**2. Update lib/utils/get-theme.js:**
Add the new element with its nested structure to extraKeys:
```javascript
myElement: parseStyleEntry(
customTheme.myElement,
baseTheme.myElement,
["specialFeature"] // Include nested object in extraKeys
),
```
**3. Update tag implementation (lib/tags/my-element.js):**
```javascript
export const myElement = inlineTag((value, tag, context) => {
const custom = getCustomAttributes(tag);
const theme = context.theme.myElement || {};
const specialFeature = theme.specialFeature || {};
const styledValue = applyCustomColor(
custom.color,
theme.color,
value,
chalkString
);
// Check if special feature is enabled
const isEnabled = specialFeature.enabled === true;
if (!isEnabled) {
return styledValue;
}
// Apply special feature
const style = specialFeature.style || 'simple';
const marker = specialFeature.marker || '→';
const featureColor = specialFeature.color || '';
const styledMarker = featureColor
? chalkString(featureColor, { colors: true })(marker)
: marker;
if (style === 'simple') {
return `${styledMarker} ${styledValue}`;
}
// Add other style variants...
return styledValue;
});
```
**4. Update TypeScript definitions (index.d.ts):**
```typescript
export interface MyElementFeatureStyle {
enabled?: boolean;
style?: 'simple' | 'advanced';
marker?: string;
color?: ChalkString;
}
export interface MyElementStyle {
color?: ChalkString;
specialFeature?: MyElementFeatureStyle;
}
export interface Theme {
// ... other properties
myElement?: ChalkString | MyElementStyle;
}
```
**5. Test the implementation:**
```bash
# Test with feature disabled (default)
echo 'Test ' | node bin/html.js
# Test with feature enabled
# Create test config with enabled: true
node bin/html.js --config /tmp/test-config.yaml test.html
```
**6. Update AGENTS.md:**
- Add to theme structure section
- Document inline customization attributes if applicable
- Add examples showing enabled: false and enabled: true
### Synchronizing Documentation with config.yaml
**When config.yaml changes:**
1. **Read the entire config.yaml** to get current structure
2. **Update AGENTS.md** "Theme Structure" section with exact YAML from config.yaml
3. **Update all code examples** in AGENTS.md to use correct default values
4. **Check CUSTOMIZATION.md** for consistency with new structure
5. **Verify examples/** files use correct defaults
**Example workflow:**
```bash
# 1. Make changes to config.yaml
vim config.yaml
# 2. Read and copy the entire theme structure
cat config.yaml
# 3. Update AGENTS.md with the exact YAML structure
# 4. Test all examples still work
node bin/html.js examples/html/tags-custom/*.html
```
### Modifying List Structure
**Current structure (from config.yaml):**
```yaml
ol:
color: ''
indicators:
'1':
color: blueBright
marker: '1'
decimal: '.'
I:
color: cyanBright
marker: I
decimal: '.'
A:
color: magentaBright
marker: A
decimal: '.'
i:
color: blueBright
marker: i
decimal: '.'
a:
color: cyanBright
marker: a
decimal: '.'
indent: ' '
ul:
color: ''
indicators:
disc:
color: redBright
marker: '•'
square:
color: yellowBright
marker: '▪'
circle:
color: cyanBright
marker: '◦'
indent: ' '
```
**Key functions in `lib/utils/list.js`:**
- `getListColor(listType, depth, customMarkers)` - Returns marker color for depth
- `getListMarker(markerType, customMarkers, depth)` - Returns marker symbol for depth
- `getListDecimal(depth, customMarkers)` - Returns decimal separator for depth (ordered lists only)
- `getOrderedListType(tagType, contextType, customMarkers)` - Determines list type with rotation
### Testing Changes
**Manual testing:**
```bash
# Test HTML rendering
node bin/html.js examples/html/tags-custom/lists.html
# Test Markdown rendering
node bin/markdown.js examples/markdown/full/gfm-features.md
# Test with custom config
node bin/html.js your-test-file.html
```
**Test file locations:**
- `examples/html/tags/` - Standard tag examples
- `examples/html/tags-custom/` - Custom attribute examples
- `/tmp/test-*.html` - Temporary test files
## Common Patterns
### Pattern 1: Simple Color Customization
```javascript
export const myTag = (tag, context) => {
const custom = getCustomAttributes(tag);
return blockTag(
(value) => {
const styledValue = applyCustomColor(
custom.color,
context.theme.myTag.color,
value,
chalkString
);
return styledValue;
}
)(tag, context);
};
```
### Pattern 2: Nested Configuration (like code blocks)
```javascript
export const pre = (tag, context) => {
const custom = getCustomAttributes(tag);
// Also check for attributes on child tag
const codeTag = tag.childNodes?.find(child => child.nodeName === 'code');
const codeCustom = codeTag ? getCustomAttributes(codeTag) : {};
const newContext = {
...context,
customCodeColor: custom.color || codeCustom.color,
customNumbersEnabled: custom.numbersEnabled ?? codeCustom.numbersEnabled,
customNumbersColor: custom.numbersColor || codeCustom.numbersColor,
customHighlightLines: custom.highlightLines || codeCustom.highlightLines,
customHighlightColor: custom.highlightColor || codeCustom.highlightColor,
customGutterEnabled: custom.gutterEnabled ?? codeCustom.gutterEnabled,
customGutterSeparatorMarker: custom.gutterSeparatorMarker || codeCustom.gutterSeparatorMarker,
customGutterSeparatorColor: custom.gutterSeparatorColor || codeCustom.gutterSeparatorColor,
customLangLabelEnabled: custom.langLabelEnabled ?? codeCustom.langLabelEnabled,
customLangLabelPosition: custom.langLabelPosition || codeCustom.langLabelPosition,
customLangLabelColor: custom.langLabelColor || codeCustom.langLabelColor,
customLangLabelPrefixMarker: custom.langLabelPrefixMarker || codeCustom.langLabelPrefixMarker,
customLangLabelPrefixColor: custom.langLabelPrefixColor || codeCustom.langLabelPrefixColor,
customLangLabelSuffixMarker: custom.langLabelSuffixMarker || codeCustom.langLabelSuffixMarker,
customLangLabelSuffixColor: custom.langLabelSuffixColor || codeCustom.langLabelSuffixColor,
};
return blockTag(...)(tag, newContext);
};
```
### Pattern 3: Border Elements
```javascript
export const myBorderElement = (tag, context) => {
const custom = getCustomAttributes(tag);
const borderColor = custom.border || context.theme.myElement.border.color;
const borderStyle = custom.borderStyle || context.theme.myElement.border.style;
const dimBorder = custom.borderDim !== null
? custom.borderDim
: context.theme.myElement.border.dim;
// Use in boxen() or similar
};
```