custom-highlight

Customize the color of highlighted text (==text== syntax) and add user attribution labels ([name=Someone] syntax) in pandoc documents.

By default, pandoc converts ==highlighted text== to HTML's  element or LaTeX's \hl command. This filter allows you to customize the highlight color through metadata.

Installation

Quick Install (Global)

Install the filter globally so you can use it from any directory:

macOS and Linux:

# Find your pandoc data directory
pandoc --version | grep "User data directory"

# Create filters directory if it doesn't exist
mkdir -p ~/.local/share/pandoc/filters

# Download the filter
curl -o ~/.local/share/pandoc/filters/custom-highlight.lua \
  https://raw.githubusercontent.com/Carthaca/pandoc-hedgedoc-enhance/main/custom-highlight.lua

# Now you can use it without specifying the path
pandoc --lua-filter custom-highlight.lua input.md -o output.html

Windows (PowerShell):

# Create filters directory
New-Item -ItemType Directory -Force -Path "$env:APPDATA\pandoc\filters"

# Download the filter
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Carthaca/pandoc-hedgedoc-enhance/main/custom-highlight.lua" `
  -OutFile "$env:APPDATA\pandoc\filters\custom-highlight.lua"

# Now you can use it without specifying the path
pandoc --lua-filter custom-highlight.lua input.md -o output.html

Local Install (Per Project)

For project-specific usage:

# Download to your project directory
curl -O https://raw.githubusercontent.com/Carthaca/pandoc-hedgedoc-enhance/main/custom-highlight.lua

# Use with full or relative path
pandoc --lua-filter ./custom-highlight.lua input.md -o output.html

Clone from GitHub

# Clone the entire repository (includes tests and examples)
git clone https://github.com/Carthaca/pandoc-hedgedoc-enhance.git
cd pandoc-hedgedoc-enhance

# Use the filter
pandoc --lua-filter custom-highlight.lua examples/example-names.md -o output.html

Usage

Enable the mark extension and apply the filter:

pandoc --from markdown+mark --lua-filter custom-highlight.lua \
  input.md -o output.html

Verify Installation:

Test that the filter is working:

# Create a test file
echo -e "---\nhighlight-color: 'orange'\n---\n\nTest ==highlight== and [name=Alice]" > test.md

# Generate HTML
pandoc --from markdown+mark --lua-filter custom-highlight.lua --standalone test.md -o test.html

# Check output (should show orange background and name label)
open test.html  # macOS
# or: xdg-open test.html  # Linux
# or: start test.html  # Windows

Configuration

Configure colors through metadata in your markdown document:

---
# Custom Highlight Filter Configuration
# Use with: pandoc --from markdown+mark --lua-filter custom-highlight.lua

# Highlight colors (use color names or hex values)
highlight-color: 'orange'                    # Background color for ==text==
highlight-background-color: 'lightyellow'    # Optional: override background
highlight-text-color: 'darkblue'             # Optional: text color inside highlights

# Name label configuration
name-label-emoji: false                      # Set to 'true' for email-friendly mode

# Note: Font Awesome CSS is automatically included unless emoji mode is enabled
---

Options

highlight-color: The highlight color (hex format or color name). Default: #ffff00 (yellow)
highlight-background-color: Background color for the highlight. If not set, uses highlight-color. This allows you to set different colors for HTML and LaTeX outputs.
highlight-text-color: Text color inside the highlight (optional). Useful for dark highlights where you need light text.

Supported color names:

Basic: black, white, red, green, blue, yellow, cyan, magenta, orange, purple, pink, brown, gray/grey
Light variants: lightred, lightgreen, lightblue, lightyellow, lightcyan, lightmagenta, lightorange, lightpurple, lightpink, lightgray/lightgrey
Dark variants: darkred, darkgreen, darkblue, darkyellow, darkcyan, darkmagenta, darkorange, darkpurple, darkpink, darkgray/darkgrey

You can also use hex colors (e.g., #ff9900) or any CSS color value.

Examples

Basic usage with default yellow:

This is ==highlighted text== in the document.

Custom orange highlight:

---
highlight-color: 'orange'
---

This is ==highlighted in orange== now.

Or using hex:

---
highlight-color: '#ff9900'
---

Dark highlight with light text:

---
highlight-background-color: '#2c3e50'
highlight-text-color: '#ffffff'
---

This is ==dark highlighted text== with white text.

Text color only (no background):

---
highlight-color: 'none'
highlight-text-color: 'red'
---

This ==red text== has no background highlighting.

You can use none or transparent for highlight-color or highlight-background-color to disable the background and only apply text color.

User Attribution Labels

The filter also supports HedgeDoc-style user attribution labels using the [name=Username] syntax. This is useful for collaborative documents where you want to track who wrote or contributed specific sections.

Basic Usage

[name=Alice] suggested this change.

The proposal was drafted by [name=Bob].

Output Formats

HTML: Renders as  Username
- Uses Font Awesome icon (requires Font Awesome CSS)
- Small text with user icon
LaTeX: Renders as {\small \faUser\ Username}
- Uses fontawesome5 package (must be included in preamble)
- Small text with user icon
Other formats: Renders as 👤 Username (Unicode emoji)

Example Document

# Meeting Notes

## Discussion

[name=Sarah Chen] opened the meeting by reviewing Q2 goals.

[name=李明] presented the technical architecture proposal.

[name=José García] shared the new wireframes.

## Action Items

- Schedule follow-up ([name=Sarah Chen])
- Complete documentation ([name=李明])

Format-Specific Requirements

For HTML output (default):

The filter automatically includes Font Awesome CSS from CDN. No manual setup required!

If you prefer to provide your own Font Awesome CSS or use a different CDN, you can add it to your document's header-includes and the filter will respect it.

For HTML output (email-friendly):

Set name-label-emoji: true in metadata to use emoji instead of Font Awesome
Font Awesome CSS is automatically disabled in emoji mode
No external dependencies required
Recommended for HTML emails where external CSS won't work
```
---
name-label-emoji: true
---
```

For LaTeX output:

The filter automatically includes \usepackage{fontawesome5} in the preamble
No manual setup required!
The fontawesome5 package must be installed in your LaTeX distribution (included in most modern distributions)

Supported Formats

Highlighting (`==text==`)

HTML: Adds inline styles to  elements
LaTeX: Uses \colorbox with RGB colors
Other formats: Uses default pandoc behavior

Name Labels (`[name=...]`)

HTML (default): Font Awesome icon + small text (requires Font Awesome CSS)
HTML (emoji mode): Unicode emoji 👤 + small text (set name-label-emoji: true)
LaTeX: fontawesome5 \faUser icon + small text
Other formats: Unicode emoji 👤 + name

Requirements

For Highlighting

Pandoc with mark extension enabled (markdown+mark)
For LaTeX output: xcolor package (usually included in standard LaTeX distributions)

For Name Labels

For HTML output: Font Awesome CSS (automatically included) or set name-label-emoji: true for emoji mode
For LaTeX output: fontawesome5 package (automatically included by the filter)

Complete Usage Examples

Example 1: Basic document with highlights and names

Input (document.md):

---
highlight-color: 'orange'
header-includes: |
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
---

# Project Notes

[name=Alice] suggested we ==highlight important sections== in orange.

Key points from [name=Bob]:
- Use the new ==API endpoints==
- Test ==edge cases== thoroughly

Generate HTML:

pandoc --from markdown+mark \
  --lua-filter custom-highlight.lua \
  --standalone \
  document.md -o output.html

Example 2: Email-friendly HTML

Input (email.md):

---
highlight-color: 'lightyellow'
highlight-text-color: 'darkblue'
name-label-emoji: true
---

# Status Update

[name=Team Lead] The ==milestone was completed== on time!

Next steps by [name=Developer]:
- Deploy to staging
- Run integration tests

Generate email-compatible HTML:

pandoc --from markdown+mark \
  --lua-filter custom-highlight.lua \
  --standalone \
  email.md -o email.html

Example 3: Using pandoc command-line options

No metadata needed - pure command line:

pandoc input.md \
  --from markdown+mark \
  --lua-filter custom-highlight.lua \
  --standalone \
  --metadata highlight-color='lightgreen' \
  --metadata highlight-text-color='darkgreen' \
  -H <(echo '<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">') \
  -o output.html

Troubleshooting

Filter not found

Error: Filter custom-highlight.lua not found

Solutions:

Check the file path: Make sure the filter file exists

ls -l custom-highlight.lua
# or if installed globally:
ls -l ~/.local/share/pandoc/filters/custom-highlight.lua  # Linux/macOS
ls "$env:APPDATA\pandoc\filters\custom-highlight.lua"  # Windows

Use absolute path:

pandoc --lua-filter /full/path/to/custom-highlight.lua input.md -o output.html

Verify pandoc data directory:
```
pandoc --version | grep "User data"
```

Highlights not working

Problem: ==text== appears as literal text, not highlighted

Solution: Enable the mark extension:

pandoc --from markdown+mark --lua-filter custom-highlight.lua input.md -o output.html
#                    ^^^^^ Don't forget this!

Font Awesome icons not showing

Problem: Name labels show [i class="fa fa-user"] instead of icons

Solutions:

Use standalone mode:

pandoc --lua-filter custom-highlight.lua --standalone input.md -o output.html
#                                        ^^^^^^^^^^^

Or use emoji mode:
```
---
name-label-emoji: true
---
```

LaTeX compilation errors

Error: Undefined control sequence \faUser

Solution: Make sure fontawesome5 package is installed:

# Check if installed
tlmgr info fontawesome5

# Install if missing (TeX Live)
tlmgr install fontawesome5

# Or (MiKTeX)
mpm --install fontawesome5

Colors not appearing in PDF

Problem: Highlights work in HTML but not in PDF

Solution: Make sure to use markdown+mark when generating PDF:

pandoc --from markdown+mark --lua-filter custom-highlight.lua input.md -o output.pdf

Getting Help

Check examples: See the examples/ directory
Run tests: cd tests && ./test-name-labels.sh
Open an issue: https://github.com/Carthaca/pandoc-hedgedoc-enhance/issues

License

Apache License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
examples		examples
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
custom-highlight.lua		custom-highlight.lua

Folders and files

Latest commit

History

Repository files navigation

custom-highlight

Installation

Quick Install (Global)

Local Install (Per Project)

Clone from GitHub

Usage

Configuration

Options

Examples

Basic usage with default yellow:

Custom orange highlight:

Dark highlight with light text:

Text color only (no background):

User Attribution Labels

Basic Usage

Output Formats

Example Document

Format-Specific Requirements

Supported Formats

Highlighting (==text==)

Name Labels ([name=...])

Requirements

For Highlighting

For Name Labels

Complete Usage Examples

Example 1: Basic document with highlights and names

Example 2: Email-friendly HTML

Example 3: Using pandoc command-line options

Troubleshooting

Filter not found

Highlights not working

Font Awesome icons not showing

LaTeX compilation errors

Colors not appearing in PDF

Getting Help

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors

Uh oh!

Languages

Highlighting (`==text==`)

Name Labels (`[name=...]`)