NAME

App::Greple::md - Greple module for Markdown syntax highlighting

SYNOPSIS

greple -Mmd file.md

greple -Mmd --mode=dark -- file.md

greple -Mmd --base-color=Crimson -- file.md

greple -Mmd --cm h1=RD -- file.md

greple -Mmd --no-table -- file.md

greple -Mmd --fold -- file.md

greple -Mmd -- --fold file.md

greple -Mmd --refill -- file.md

DESCRIPTION

App::Greple::md is a greple module for viewing Markdown files in the terminal with syntax highlighting.

It colorizes headings, bold, italic, strikethrough, inline code, fenced code blocks, HTML comments, blockquotes, horizontal rules, links, and images. Tables are formatted with aligned columns and optional Unicode box-drawing borders. Long lines in list items can be folded with proper indentation. Links become clickable via OSC 8 terminal hyperlinks in supported terminals.

Nested elements are handled with cumulative coloring: for example, a link inside a heading retains both its link color and the heading background color.

For a complete Markdown viewing experience with line folding, multi-column output, and themes, see App::mdee, which uses this module as its highlighting engine.

Control characters and escape sequences in the file, which could change the title or the clipboard or clear the screen, are removed before anything else, and so are not shown. Colors stay.

COMMAND OPTIONS

The following options are defined as greple command options (specified after --).

--fold

Enable text folding for list items, definition lists, block quotes and the paragraphs joined by --refill. Long lines are wrapped with proper indentation using ansifold(1) via Greple::tee; the continuation lines of a block quote start with the quote marker again. Code blocks, HTML comments, and tables are excluded from folding. The fold width is controlled by the fold_width config parameter (default: 80), and the run-in and run-out widths for line breaking (kinsoku) by fold_runin and fold_runout (default: 4, as in ansifold).

greple -Mmd -- --fold file.md
greple -Mmd::config(fold_width=60) -- --fold file.md

Supported list markers: *, -, 1., 1), #., #).

The module option --fold (before --) enables the same folding through the config.

MODULE OPTIONS

Module options are specified before -- to separate them from greple's own options:

greple -Mmd --mode=dark --cm h1=RD -- file.md

-m MODE, --mode=MODE

Set color mode. Available modes are light (default) and dark.

greple -Mmd -m dark -- file.md

-B COLOR, --base-color=COLOR

Override the base color used for headings, bold, links, and other elements. Accepts a named color (e.g., Crimson, DarkCyan) or a Term::ANSIColor::Concise color spec.

greple -Mmd -B Crimson -- file.md

--[no-]colorize

Enable or disable syntax highlighting. Enabled by default. When disabled, no color is applied to Markdown elements.

greple -Mmd --no-colorize -- file.md

--[no-]fold

Enable or disable text folding (config fold). Disabled by default. When enabled, long lines in list items, definition lists, block quotes and the paragraphs joined by --refill are wrapped with proper indentation. The fold width is controlled by the fold_width config parameter (default: 80).

greple -Mmd --fold -- file.md
greple -Mmd::config(fold=1,fold_width=60) file.md

The greple command option of the same name, --fold after --, folds the same lines once without setting the config.

--[no-]refill

Join the lines of paragraphs into one line each (see "Paragraph Refill"). Disabled by default.

--[no-]table

Enable or disable table formatting. When enabled (default), Markdown tables (3 or more consecutive pipe-delimited rows) are formatted with aligned columns using App::ansicolumn.

greple -Mmd --no-table -- file.md

--[no-]rule

Enable or disable Unicode box-drawing characters for table borders. When enabled (default), ASCII pipe characters (|) are replaced with vertical lines (│), and separator row dashes become horizontal rules (─) with corner pieces (├, ┤, ┼).

greple -Mmd --no-rule -- file.md

--colormap LABEL=SPEC, --cm LABEL=SPEC

Override the color for a specific element. LABEL is one of the color labels listed in "COLOR LABELS". SPEC follows Term::ANSIColor::Concise format and supports sub{...} function specs via Getopt::EX::Colormap.

greple -Mmd --cm h1=RD -- file.md
greple -Mmd --cm bold='${base}D' -- file.md

greple has an option of the same name. Before --, --cm belongs to this module and takes the labels above. After --, or when there is no --, it is the option of greple, which colors the matched text and its own labels such as FILE, and complains about the labels of this module:

greple -Mmd --cm h1=RD -- --cm B -E foo file.md  # h1 is red, foo blue
greple -Mmd --cm h1=RD file.md                   # h1: Unknown label

--heading-markup[=STEPS], --hm[=STEPS]

Control inline markup processing inside headings. By default, headings are rendered with uniform heading color without processing bold, italic, strikethrough, or inline code inside them. Links are always processed as OSC 8 hyperlinks regardless of this option.

Without an argument, all inline formatting becomes visible within headings using cumulative coloring. With an argument, only the specified steps are processed inside headings. Steps are separated by colons.

Available steps: inline_code, horizontal_rules, bold, italic, strike.

greple -Mmd --hm -- file.md                  # all markup
greple -Mmd --hm=bold -- file.md              # bold only
greple -Mmd --hm=bold:italic -- file.md       # bold and italic

--hashed LEVEL=VALUE

Append closing hashes to headings. For example, ### Title becomes ### Title ###. Set per heading level:

greple -Mmd --hashed h3=1 --hashed h4=1 -- file.md

--show LABEL[=VALUE]

Control which elements are highlighted. This is useful for focusing on specific elements or disabling unwanted highlighting.

greple -Mmd --show bold=0 -- file.md          # disable bold
greple -Mmd --show all= --show h1 -- file.md  # only h1

--show LABEL=0 or --show LABEL= disables the label. --show LABEL or --show LABEL=1 enables it. all is a special key that sets all labels at once.

Controllable labels: bold, italic, strike, code_inline, header (h1-h6), horizontal_rule, blockquote.

The following elements are always processed and cannot be disabled: comment, code_block (code_mark, code_info), link, image, image_link. Use --cm LABEL= to remove their color without disabling processing.

CONFIGURATION

Module parameters can also be set using the config() function in the -M declaration:

greple -Mmd::config(mode=dark,base_color=Crimson) file.md

Nested hash parameters use dot notation:

greple -Mmd::config(hashed.h3=1,hashed.h4=1) file.md

Available parameters:

mode            light or dark (default: light)
base_color      base color override
colorize        syntax highlighting (default: 1)
fold            text folding (default: 0)
fold_width      fold width in columns (default: 80)
fold_runin      run-in width in folded lines (default: 4)
fold_runout     run-out width in folded lines (default: 4)
refill          join the lines of paragraphs (default: 0)
refill_parser   cmark (the CommonMark module), mdperl (Markdown::Perl)
                or pandoc (default: the first that is there, in
                that order)
table           table formatting (default: 1)
table_trim      trim cell whitespace (default: 1)
table_width     table width in columns; cells of over-wide
                columns are wrapped (default: 0 = off)
table_cell      per-column widths passed to ansicolumn --cell,
                colon separated (e.g. 0:10:<20)
table_wrap_mark string put at the start of continuation lines
                of wrapped cells (default: none)
table_cell_mark string put at the start of the first line of
                every body cell in a column that has a wrapped
                cell (default: none)
table_runin     run-in width in wrapped cells (default: 2)
table_runout    run-out width in wrapped cells (default: 2)
table_boundary  fold boundary in wrapped cells (default: word)
table_linebreak line break mode in wrapped cells: none, runin,
                runout or all (default: all)
table_style     lattice: column separators (default; pipe is
                another name); 3line: columns separated by spaces,
                a rule above and below the table and per column
                below the header; simple: columns separated by
                spaces, a rule per column below the header and
                below the table
rule            box-drawing characters (default: 1)
osc8            OSC 8 hyperlinks (default: 1)
heading_markup  inline markup in headings (default: 0)
                0=off, 1/all=all, or colon-separated steps
cjk_friendly    markdown-cjk-friendly rules for * and **
                emphasis (default: 0)
tick_open       inline code open marker (default: `)
tick_close      inline code close marker (default: ´)
nofork          nofork+raw mode for code ref calls (default: 1)
hashed.h1-h6    closing hashes per level (default: 0)

Paragraph Refill

With refill=1, the lines of every paragraph, block quote, list item and definition are joined into one line before the text is colorized. Which lines belong together is decided by a Markdown parser (App::Greple::md::Blocks): the CommonMark module, an interface to libcmark, when it is installed, otherwise Markdown::Perl, which is pure Perl and always installed with this module, or pandoc (2.11.3 or later) run with the sourcepos extension; refill_parser chooses one. The module joins the lines of the original text and changes nothing else. Hard line breaks are kept, and so is the break before a list marker, a horizontal rule, a table row or a definition (: ). When folding is enabled, the joined lines are folded too.

greple -Mmd::config(refill=1) file.md
greple -Mmd::config(refill=1,refill_parser=pandoc) file.md

OSC 8 Hyperlinks

Links are converted to clickable OSC 8 terminal hyperlinks in supported terminals (iTerm2, Kitty, WezTerm, Ghostty, etc.). Disable with:

greple -Mmd::config(osc8=0) file.md

Settings of the User

The module runs ansifold and ansicolumn for folding and tables. They are run as functions in the greple process, or as separate processes with nofork=0, and either way they do not read the rc files of the user, ~/.ansifoldrc and ~/.ansicolumnrc: the module puts their names in the environment variable GETOPTEX_NO_USER_SETTINGS (see Getopt::EX::Long), so that the output does not change by the settings made for them on the command line.

COLOR LABELS

The following labels identify colorizable elements. Use them with --colormap (--cm) to customize colors or --show to control visibility. Default values are shown as light / dark. Colors follow Term::ANSIColor::Concise format.

Headings

LABEL   LIGHT                    DARK
h1      L25D/${base};E           L00D/${base};E
h2      L25D/${base}+y20;E       L00D/${base}-y15;E
h3      L25DN/${base}+y20        L00DN/${base}-y15
h4      ${base}UD                ${base}UD
h5      ${base}UD                ${base}UD
h6      ${base}D                 ${base}D

Inline Formatting

LABEL           LIGHT   DARK
bold            D
italic          I
strike          X
emphasis_mark   L18     L10
bold_mark       -       -
italic_mark     -       -
strike_mark     -       -

Emphasis markers (**, *, __, _, ~~) are colored with emphasis_mark, separately from the content text. bold_mark, italic_mark, strike_mark are undefined by default and fall back to emphasis_mark. Define them via --cm to override per type:

greple -Mmd --cm emphasis_mark=R -- file.md    # all markers red
greple -Mmd --cm bold_mark=G -- file.md        # bold markers green

* and ** start and end emphasis as in CommonMark: a delimiter next to a letter on one side and punctuation on the other does not count, so L*=50, a*=68 is not italic. In Japanese text this also rejects 日本語の*「強調」*です and 日本語の**強調。**です, as pandoc does. With cjk_friendly=1, the rules of markdown-cjk-friendly are used instead, and these are emphasis.

Code

LABEL        LIGHT              DARK
code_mark    L20                L10
code_tick    L15/L23            L15/L05
code_info    ${base_name}=y70   L10
code_block   /L23;E             /L05;E
code_inline  L00/L23            L25/L05

Inline code backticks are displayed as `content´ using code_tick color. Multi-backtick delimiters are collapsed to a single pair with optional surrounding spaces stripped (per CommonMark). The open/close markers can be customized via tick_open/tick_close config parameters.

Block Elements

LABEL            LIGHT / DARK
blockquote       ${base}
horizontal_rule  L15
comment          ${base}+r60

Links

LABEL        LIGHT / DARK
link         I
image        I
image_link   I
link_mark    -       -

link_mark colors the brackets ([, ]) around link and image text. Undefined by default, falls back to emphasis_mark. The ! prefix for images uses the image or image_link color. Hide brackets with --cm 'link_mark=sub{""}' (used by the nomark theme).

SEE ALSO

App::mdee

Markdown viewer command with line folding, table formatting, multi-column layout, and themes. Uses this module for syntax highlighting.

App::Greple

General-purpose extensible grep tool that hosts this module.

Term::ANSIColor::Concise

Concise ANSI color specification format used for color labels.

App::ansicolumn

ANSI-aware column formatting used for table alignment.

App::ansifold

ANSI-aware text folding used for line wrapping in list items.

App::Greple::md::Blocks

Finds the paragraphs for refill=1 with CommonMark, Markdown::Perl or pandoc.

CommonMark Spec 0.31.2, Emphasis and strong emphasis

The rules that * and ** follow by default.

CommonMark CJK-friendly Amendments

The rules that cjk_friendly=1 follows. The proposal comes from commonmark-spec issue #650, Emphasis with CJK punctuation, open since 2020.

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright 2025-2026 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm App::mdee

perl -MCPAN -e shell
install App::mdee