view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

preserving ANSI colors.

Column alignment is parsed from the separator line: `:---` (left,
default), `:---:` (center), `---:` (right).  The `parse_separator()`
function extracts alignment markers and passes `--table-right` and
`--table-center` options to [ansicolumn(1)](https://metacpan.org/pod/App%3A%3Aansicolumn) (requires
version 1.53 or later).  Colons are stripped from the separator line
before further processing.

When `--rule` is enabled (default), ASCII pipe characters are replaced
with Unicode box-drawing characters (`│`, `├`, `┤`, `┼`, `─`).

### Output Stage

The final stage uses [nup(1)](https://metacpan.org/pod/App%3A%3Anup) to provide multi-column paged output.
Layout options (`--pane`, `--row`, `--grid`, `--page`) are passed
directly to nup.

## Theme System

**em·dee** implements a theme system where themes are transformations
applied to the built-in default theme.  Multiple themes can be
chained via `--theme=NAME1,NAME2,...`.

### Theme Structure

Color definitions are managed by the [App::Greple::md](https://metacpan.org/pod/App%3A%3AGreple%3A%3Amd) module.
The `theme_light` and `theme_dark` arrays contain only the base
color.  Theme files can modify the base color and pass configuration
to the md module via `md_config[]`:

    # theme/warm.sh — change base color
    theme_light[base]='<Coral>=y25'
    theme_dark[base]='<Coral>=y80'

    # theme/hashed.sh — enable closing hashes
    md_config+=(hashed.h3=1 hashed.h4=1 hashed.h5=1 hashed.h6=1)

The `md_config[]` entries are passed as config parameters to the
[App::Greple::md](https://metacpan.org/pod/App%3A%3AGreple%3A%3Amd) module.  Color labels (`h1`, `bold`, etc.)
can also be set as config parameters:

    # theme file or config.sh — override color label
    md_config+=(h1='L25D/R;E' bold=RD)

#### Base Color Expansion

The `${base}` placeholder in color values is expanded by the md
module.  The base color is determined by `--base-color` option
(default: RoyalBlue) with automatic luminance adjustment based on
mode (`=y25` for light, `=y80` for dark).

### Color Specifications

Colors are specified using [Term::ANSIColor::Concise](https://metacpan.org/pod/Term%3A%3AANSIColor%3A%3AConcise) format.
The `--colormap` (`--cm`) option maps colors to captured groups.  For example,
`L00D/${base};E` specifies gray foreground on base-colored background.

The color specification supports modifiers:

- `+y10` / `-y10`: Adjust luminance by percentage
- `=y50`: Set absolute luminance
- `D`: Bold, `U`: Underline, `E`: Erase line

### Terminal Mode Detection

**em·dee** uses [Getopt::EX::termcolor](https://metacpan.org/pod/Getopt%3A%3AEX%3A%3Atermcolor) to detect terminal background
luminance.  If luminance is below 50%, dark mode is automatically
selected.

# LIMITATIONS

## HTML Comments

Only HTML comments starting at the beginning of a line are highlighted.
Inline comments are not matched to avoid conflicts with inline code
containing comment-like text (e.g., `` `<!-->` ``).

## Emphasis

Emphasis patterns (bold and italic) do not span multiple lines.
Multi-line emphasis text is not supported.

`***bold italic***` and `___bold italic___` are supported.
Other nested forms (e.g., `**bold _italic_**`) are not.

## Links

Link patterns do not span multiple lines.  The link text and URL must
be on the same line.

Links inside other highlighted elements (such as headings or bold
text) are not processed.

Reference-style links (`[text][ref]` with `[ref]: url` elsewhere)
are not supported.

## Table Alignment

Column alignment assumes that cell content in the source is not
pre-padded.  If the source table is already formatted with aligned
spacing (e.g., `| c     |`), the embedded spaces become part of
the cell content and alignment directives in the separator line
will not produce the expected result.  This is by design: pre-formatted
tables are assumed to be correctly aligned as-is.

## OSC 8 Hyperlinks

Links are converted to OSC 8 terminal hyperlinks for clickable URLs:

- `[text](url)` - `[text]` links to url
- `![alt](url)` - `![alt]` links to url (image)
- `[![alt](img)](url)` - `!` links to img, `[alt]` links to url

This requires terminal support.  Compatible terminals include iTerm2,
Kitty, WezTerm, Ghostty, and recent versions of GNOME Terminal.
Apple's default Terminal.app does not support OSC 8.

When using `less` as pager, version 566 or later is required with
`-R` option.