view release on metacpan or  search on metacpan

lib/App/Greple/md.pm  view on Meta::CPAN

# -*- mode: perl; coding: utf-8 -*-
# vim: set fileencoding=utf-8 filetype=perl :
package App::Greple::md;

use 5.024;
use warnings;

our $VERSION = "0.9903";

=encoding utf-8

=head1 NAME

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

=head1 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 --foldlist -- file.md

    greple -Mmd -- --fold file.md

=head1 DESCRIPTION

B<App::Greple::md> is a L<greple|App::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 L<App::mdee>, which uses this
module as its highlighting engine.

=head1 COMMAND OPTIONS

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

=head2 B<--fold>

Enable text folding for list items and definition lists.  Long lines
are wrapped with proper indentation using L<ansifold(1)|App::ansifold>
via L<Greple::tee>.  Code blocks, HTML comments, and tables are
excluded from folding.  The fold width is controlled by the
C<foldwidth> config parameter (default: 80).

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

Supported list markers: C<*>, C<->, C<1.>, C<1)>, C<#.>, C<#)>.

The module option C<--foldlist> is a convenient alternative that
enables folding via config.

=head1 MODULE OPTIONS

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

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

=head2 B<-m> I<MODE>, B<--mode>=I<MODE>

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

    greple -Mmd -m dark -- file.md

=head2 B<-B> I<COLOR>, B<--base-color>=I<COLOR>

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

    greple -Mmd -B Crimson -- file.md

=head2 B<--[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

=head2 B<--[no-]foldlist>

Enable or disable text folding.  Disabled by default.  When
enabled, long lines in list items and definition lists are wrapped
with proper indentation.  The fold width is controlled by the
C<foldwidth> config parameter (default: 80).