blib/lib/App/mdee.pm

filter: Statementstmt 100% 2 / 2 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 100% 2 / 2 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« blib/lib/App/Greple/md/widen.pm ↑ Summary
1 package App::mdee;
2  
3 # DO NOT EDIT this file manually.
4 # POD documentation is appended from script/mdee at release time.
5 # See minil.toml for details.
6  
7 1 our $VERSION = "1.23";
8  
9 1 1;
10 =encoding utf-8
11  
12 =head1 NAME
13  
14 mdee - em·dee, Markdown Easy on the Eyes
15  
16 =head1 SYNOPSIS
17  
18 mdee [ options ] file ...
19  
20 -h --help show help
21 --version show version
22 -d --debug debug level (repeatable)
23 -x --[no-]trace trace mode (set -x)
24 -n --dryrun dry-run mode
25 -s --style=# output style (nup/pager/cat/filter/raw)
26 -f --filter shortcut for --style=filter
27 -p --plain shortcut for --style=pager
28 --[no-]fold line folding (default: on)
29 -r --[no-]refill join paragraph lines (default: off)
30 --[no-]table table formatting (default: on)
31 --[no-]trim trim cell spaces (default: on)
32 --[no-]nup nup paged output (default: on)
33 -V --parallel show files side by side
34 -L --[no-]lateral all pages in one row, scrolled sideways
35 --[no-]rule use Unicode rules for tables (default: on)
36 --ts --table-style=# table style: lattice, 3line or simple (default: lattice)
37 --cat-v visualize whitespace via cat-v
38 -w --width=# output width (default: terminal width)
39 --fold-width=# fold width (default: pane width - 3 - run-in)
40 --runin=# run-in width for line breaking (default: 4)
41 --runout=# run-out width for line breaking (default: 4)
42 --runlen=# set both run-in and run-out
43 --boundary=# fold boundary: word, space or none (default: word)
44 -t --theme=#[,#,...] color theme(s) (default: hashed,nomark,markcell,doubleline)
45 -m --mode=# light or dark (default: light)
46 -B --base-color=# override base color of theme
47 (e.g., Ivory, #780043, (120,0,67))
48 --config=KEY=VALUE set config parameter (e.g., h1=RD, FILE=...)
49 --cm --colormap=L=SPEC override color for element (e.g., h1=RD)
50 --hm --heading-markup=# enable markup in headings (all/bold/...)
51 --show=# set field visibility (e.g., italic=1)
52 -C --pane=#[,#] number of columns, and rows
53 -R --row=# number of rows
54 -G --grid=# grid layout (e.g., 2x3)
55 -P --page=# page height in lines
56 -S --pane-width=# pane width (default: 85)
57 --bs --border-style=# border style
58 --[no-]page-number page number on border (default: on)
59 --[no-]filename file name label (default: on)
60 --[no-]pager[=#] pager command
61 -T --device=# output device: tty, pdf, or a paper for PDF
62 (e.g., a4, a4p, a3l)
63 -o --output=FILE output file (PDF when it ends with .pdf)
64  
65 =head1 VERSION
66  
67 Version 1.23
68  
69 =cut
70 =head1 DESCRIPTION
71  
72 B<em·dee> (command: C<mdee>) is a terminal-based multi-column
73 Markdown text viewer with syntax highlighting, particularly
74 useful for reading documents generated by LLMs.
75  
76 =begin html
77  
78 <p><img width="1000" src="https://raw.githubusercontent.com/tecolicom/App-mdee/main/images/3-column.png">
79  
80 =end html
81  
82 It presents Markdown content in a clean, readable form: syntax
83 highlighting distinguishes document structure, line folding wraps
84 long list items, and tables are aligned with proper column
85 formatting. By default, markup characters (C<**>, C<`>,
86 C<[>...C<]>, etc.) are hidden so that the text reads naturally,
87 while color and styling preserve the structural information.
88 Closing hashes are appended to h3-h6 headers to make heading
89 levels visually distinct. On terminals supporting OSC 8, links
90 remain clickable.
91  
92 Use C<--no-theme> to display the original Markdown source with
93 markup characters intact.
94  
95 The same view is printed to PDF with C<-o file.pdf>. See
96 L</Printing to PDF>.
97  
98 =head2 Concept
99  
100 B<em·dee> began as a viewer for Markdown I<text>, not as a Markdown
101 renderer. The idea was to show a C<.md> file as it is written, line
102 for line, only made easier on the eyes with color: the Markdown is
103 not interpreted or reformatted. Some formatting has been added since
104 because it made the text more readable: tables are aligned, long
105 list items are folded, the default themes hide markup characters,
106 and closing hashes are appended to lower-level headings. With
107 C<--refill>, the lines that a Markdown parser has found to be
108 one paragraph are joined as well. Everything else is still the
109 source text. This is why backslash escapes such as C<\*> are shown
110 as written, and why C<--no-theme> gives back the original file, in
111 color.
112  
113 For full Markdown rendering, many other viewers are available, such
114 as C<glow> and C<mdcat>. Combine them with L<nup(1)|App::nup> for
115 similar paged output (e.g., C<nup glow README.md>, C<nup mdcat README.md>).
116  
117 The pipeline combines L<greple(1)|App::Greple> for colorization and
118 L<nup(1)|App::nup> for multi-column paged output.
119  
120 The following elements are highlighted. Elements marked with
121 C<--show> can be individually disabled via the C<--show> option.
122 Others are always processed for structural integrity.
123  
124 --show bold (**bold**, __bold__)
125 --show italic (*italic*, _italic_)
126 --show strike (~~strike~~)
127 --show code_inline (`code`)
128 --show header, h1-h6 (# heading)
129 --show horizontal_rule (---, ***, ___)
130 --show blockquote (> quote)
131 always code_mark (``` or ~~~)
132 code_block
133 code_info
134 always meta_mark (--- or +++ at the top)
135 meta_block
136 always comment (<!-- ... -->)
137 always link ([text](url))
138 image (![text])
139 image_link (![text](url))
140  
141 Tables and list item folding are controlled by C<--table> and
142 C<--fold> options, not by C<--show>.
143  
144 The code in a fenced code block is shown in the colors of its
145 language (C<```perl>), when L<Text::ANSI::Highlight> and the command
146 of its highlighter, C<pandoc> by default, are installed.
147 C<--config highlight=gnu> uses C<source-highlight>, and
148 C<--config highlight=0> turns it off. See
149 L<App::Greple::md/"Syntax Highlight of Code">.
150  
151 =head2 Multi-column Layout and Pagination
152  
153 By default, B<mdee> calculates the number of display columns by
154 dividing the output width (the terminal width unless C<--width>
155 is given) by the pane width (default 85 characters). This determines how the output is laid out and
156 paginated.
157  
158 When two or more columns fit, L<nup(1)|App::nup> arranges output
159 in multi-column layout with page-by-page pagination — content is
160 split into terminal-height pages viewed through a pager.
161  
162 When only one column fits, B<mdee> still uses nup for formatting
163 (borders, document layout) but disables page-by-page splitting,
164 so the content scrolls continuously in the pager. This avoids
165 wasted space from page breaks on narrow terminals while
166 maintaining the same visual appearance.
167  
168 To force page-by-page pagination even in single-column layout,
169 specify C<--nup> explicitly. The C<--pane-width> (C<-S>) option
170 adjusts the column width used for this calculation, and
171 C<--pane> (C<-C>) sets the number of columns directly. The
172 C<--width> (C<-w>) option replaces the terminal width in this
173 calculation and limits the output to that width.
174  
175 With two or more files, C<--parallel> shows the files side by side,
176 one pane per file, instead of one after another. Each file is
177 folded to its pane width, and the panes scroll together in the
178 pager. The screen shows as many files as fit, as many as the pages
179 of a single file, and the files that do not fit in one row continue
180 on the next, or on the right with C<--lateral>; C<--pane> (C<-C>)
181 sets the number of panes.
182  
183 Use C<-p> (C<--style=pager>) for a simpler view without nup
184 formatting — highlighted output is piped directly through a
185 pager. Use C<-f> (C<--style=filter>) to write highlighted
186 output to stdout without a pager, suitable for piping into
187 other commands.
188  
189 =head2 Printing to PDF
190  
191 B<mdee> prints the document to PDF when the output file ends with
192 C<.pdf>, or when a paper is given as the device with C<-T>.
193  
194 mdee -o README.pdf README.md # A4 in landscape
195 mdee -T a4p -o README.pdf README.md # A4 in portrait
196 mdee -T a3 README.md > README.pdf # A3, to the standard output
197  
198 The paper takes the place of the terminal. The number of columns is
199 the width of the paper in characters divided by the pane width, and
200 the text is folded for it, in the same way as on the terminal: A4 in
201 landscape is 206 characters wide and has two panes, and A4 in
202 portrait is 100 characters wide and has one. C<-C> and C<-S> work
203 as on the terminal. The mode is C<light> unless C<--mode> is given,
204 because the paper is white.
205  
206 A paper is given by its name, with the letter C<p> or C<l> for
207 portrait or landscape, and the margin in millimeters after C<:m>.
208 The default is landscape with a margin of 5 mm.
209  
210 mdee -T a4p:m10 -o README.pdf README.md
211  
212 A sheet has 60 lines. The rows of C<-C> divide the sheet, and the
213 size of the characters is kept: C<-C2,2> gives four pages of 30
214 lines on a sheet. C<-P> sets the lines of a page instead, and the
215 characters become smaller or larger to put the pages on the sheet:
216 C<-C2,2 -P60> prints four pages of 60 lines on a sheet in half the
217 size, as a printer does for 4-up.
218  
219 mdee -C2,2 -o README.pdf README.md
220 mdee -C2,2 -P60 -o README.pdf README.md
221  
222 L<nup(1)|App::nup> and
223 L<ansi2pdf(1)|https://github.com/tecolicom/App-ansi2pdf> make the
224 PDF, so C<ansi2pdf> has to be installed, and the output style has to
225 be C<nup>, which is the default. See C<-T> and C<-o> in
226 L</Output Options>.
227  
228 =head1 INSTALLATION
229  
230 =head2 Homebrew
231  
232 Use L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap>:
233  
234 brew tap tecolicom/tap
235 brew install app-mdee
236  
237 =head2 CPAN
238  
239 cpanm -n App::mdee
240  
241 =head1 OPTIONS
242  
243 =head2 General Options
244  
245 =over 4
246  
247 =item B<-h>, B<--help>
248  
249 Show help message.
250  
251 =item B<--version>
252  
253 Show version.
254  
255 =item B<-d>, B<--debug>
256  
257 Set debug level. Can be repeated for increasing verbosity.
258  
259 =over 4
260  
261 =item C<-d>
262  
263 Show theme values (C<theme_light[]>/C<theme_dark[]>, C<md_config[]>)
264 and pipeline stage names.
265  
266 =item C<-dd>
267  
268 Above, plus full command lines for each pipeline stage.
269  
270 =back
271  
272 =item B<-x>, B<--trace>, B<--no-trace>
273  
274 Enable or disable shell trace mode (C<set -x>). Useful for
275 debugging script execution. Can be toggled: C<-x --no-x> enables
276 then disables tracing.
277  
278 =item B<-n>, B<--dryrun>
279  
280 Dry-run mode. Print the commands that would be run, one pipeline
281 stage per line joined with C<|>, without running them. Arguments
282 are quoted so that the output can be pasted into a shell. The
283 environment that B<mdee> sets (C<LESS>, C<LESSANSIENDCHARS>) is not
284 shown. With C<-d>, the stage names are printed to stderr as well.
285  
286 =back
287  
288 =head2 Processing Options
289  
290 =over 4
291  
292 =item B<-s> I<STYLE>, B<--style>=I<STYLE>
293  
294 Set the output style. Default is C<nup>. Available styles:
295  
296 =over 4
297  
298 =item C<nup> - Full pipeline: fold + table + nup paged output (default)
299  
300 =item C<pager> - Fold + table, output to pager (C<$PAGER> or C<less>)
301  
302 =item C<cat> - Fold + table, output to stdout
303  
304 =item C<filter> - Table only (no fold, no nup), suitable for piping
305  
306 =item C<raw> - Highlight only (no fold, no table, no nup)
307  
308 =back
309  
310 The style sets the initial state of C<--fold>, C<--table>, and
311 C<--nup> options. Subsequent options can override individual
312 settings:
313  
314 mdee -s filter --fold file.md # filter + fold
315 mdee -p --no-fold file.md # pager without fold
316  
317 =item B<-f>, B<--filter>
318  
319 Shortcut for C<--style=filter>. Reads from stdin (or files) and
320 outputs highlighted Markdown to stdout. Disables line folding and
321 nup paged output, but keeps table formatting enabled. Useful for
322 piping Markdown content through mdee for syntax highlighting.
323  
324 =item B<-p>, B<--plain>
325  
326 Shortcut for C<--style=pager>. Enables fold and table formatting,
327 outputs through a pager (C<$PAGER> or C<less>) instead of nup.
328  
329 =item B<--[no-]fold>
330  
331 Enable or disable line folding for list items, definition lists,
332 block quotes and, with C<--refill>, paragraphs. When enabled, long
333 lines are wrapped with proper indentation using
334 L<ansifold(1)|App::ansifold>: the continuation lines of a list item
335 are indented under its text, those of a block quote start with the
336 quote marker again. Default is enabled.
337  
338 Supported list markers: C<*>, C<+>, C<->, C<1.>, C<1)>, C<#.>, C<#)>.
339 The C<#.> and C<#)> forms are the auto-numbered lists of Pandoc's
340 Markdown.
341  
342 =item B<-r>, B<--[no-]refill>
343  
344 Join the lines of each paragraph into one line. Default is disabled;
345 C<default[refill]=1> in the configuration file enables it.
346  
347 What a paragraph is, a Markdown parser decides: a run of lines at the
348 top level, in a block quote, in a list item or in a definition body.
349 Those lines are joined in the original text. Headings, tables, code
350 blocks, front matter and everything else stay as written. A hard
351 line break (two or more spaces or a backslash at the end of a line)
352 is kept.
353  
354 Lines are joined with one space, or with nothing after a fullwidth
355 punctuation character and between two characters of a script that is
356 written without spaces, as L<ansifold(1)|App::ansifold> does. When
357 fold is enabled, the joined paragraphs are folded to the fold width
358 like list items; otherwise each is one long line.
359  
360 The parser is L<Markdown::Perl>, which is installed with B<mdee>, or
361 the L<CommonMark> module (an interface to libcmark) when it is there,
362 which is faster. C<--config refill_parser=pandoc> uses pandoc 2.11.3
363 or later instead.
364  
365 Front matter at the top of the file, TOML between C<+++> lines or
366 YAML between C<---> lines (or ended by C<...>), is left as it is
367 and shown as a code block; C<--config front_matter=0> takes its lines
368 as Markdown.
369  
370 =item B<--[no-]table>
371  
372 Enable or disable table formatting. When enabled, Markdown tables
373 are formatted using L<ansicolumn(1)|App::ansicolumn> for aligned column display.
374 Column alignment specified in the separator line (C<:---> for left,
375 C<:---:> for center, C<---:> for right) is respected.
376 A C<< <br> >> (or C<< <br/> >>, C<< <br /> >>) in a cell breaks the
377 cell into lines after it; one in a code span, or escaped as
378 C<< \<br> >>, does not. The default theme C<nomark> hides the
379 C<< <br> >>, and C<--no-theme> shows it.
380 Default is enabled.
381  
382 When folding is enabled, a table wider than the table width is fit
383 into that width. The table width is the fold width; with nup, when
384 the fold width is not given, it is the fold width plus the run-in
385 width but one (81 for a pane of 85), because the lines of a table are
386 sent to nup to be kept intact, not folded (see C<--intact> of
387 L<ansicolumn(1)|App::ansicolumn>); C<--cat-v> does not do it, and
388 the table width is the fold width there. Columns that fit keep
389 their width, and the cells of over-wide columns are wrapped. A
390 table that already fits is not changed. Use C<--config
391 table_width=0> to disable wrapping, or C<--config table_width=N> to
392 use a different width. Per-column
393 widths can be given with C<--config table_cell=SPEC>, where SPEC
394 is a colon-separated list passed to ansicolumn's C<--cell> option
395 (for example C<0:10> fixes the second column at 10 columns, and
396 C<< '<30' >> caps every column at 30). Marks can be put at the
397 start of cell lines, in place of the cell's leading space so that
398 column widths do not change. C<--config table_cell_mark=STRING>
399 marks the first line of every body cell in a column that has a
400 wrapped cell; the header row and columns that fit are left alone.
401 The default theme C<markcell> sets it to C<‣> (U+2023).
402 C<--config table_wrap_mark=STRING> marks the second and later
403 lines of a wrapped cell, so that they are not read as new rows;
404 the theme C<markwrap> sets it to C<›> (U+203A). Without these
405 themes no mark is used.
406  
407 =item B<--[no-]trim>
408  
409 Trim whitespace from table cell content before formatting.
410 This is useful when the source table is pre-formatted with
411 aligned spacing, which would otherwise prevent column alignment
412 directives from working correctly. Default is enabled.
413  
414 =item B<--[no-]nup>
415  
416 Enable or disable L<nup(1)|App::nup> for multi-column paged output.
417 When disabled, output goes directly to stdout without formatting.
418 Default is enabled. When explicitly specified, forces nup's
419 native pagination even in single-column layout (which normally
420 uses the pager instead).
421  
422 =item B<--[no-]rule>
423  
424 Enable or disable Unicode rule characters for table borders.
425 When enabled, ASCII pipe characters (C<|>) are replaced with
426 Unicode box-drawing characters (C<│>, C<├>, C<┤>, C<┼>) and
427 dashes (C<->) in separator lines are replaced with horizontal
428 rules (C<─>). Default is enabled.
429  
430 =item B<--table-style>=I<STYLE>, B<--ts> I<STYLE>
431  
432 Select how tables are drawn. C<lattice> (default) keeps a separator
433 between the columns, C<│> or C<|> depending on C<--rule>. C<pipe> is
434 another name of it, kept for compatibility:
435  
436 Left │ Center │ Right │ Default
437 ──────┼────────┼───────┼─────────
438 a │ b │ c │ d
439  
440 C<3line> separates the columns by spaces only and draws three rules: a
441 rule the width of the table above and below it, and a rule per column
442 below the header.
443  
444 ─────────────────────────────────
445 Left Center Right Default
446 ────── ──────── ─────── ─────────
447 a b c d
448 ─────────────────────────────────
449  
450 C<simple> also separates the columns by spaces only, and draws the
451 rule per column below the header and below the table.
452  
453 Left Center Right Default
454 ────── ──────── ─────── ─────────
455 a b c d
456 ────── ──────── ─────── ─────────
457  
458 The rules are drawn with C<-> with C<--no-rule>.
459  
460 =item B<--cat-v>
461  
462 Pass the output through L<cat-v(1)|App::cat::v> to visualize
463 whitespace and special characters. Spaces are shown as C<·>
464 and other invisible characters are made visible. Newline
465 visualization is disabled by default.
466  
467 =item B<-w> I<N>, B<--width>=I<N>
468  
469 Set the output width in characters. Default is the terminal
470 width. With nup, this width is used in place of the terminal
471 width to calculate the number of columns, and it is passed to
472 L<ansicolumn(1)|App::ansicolumn> so that the panes fit into it:
473  
474 mdee -w 170 file.md # two 85-column panes on a wide terminal
475 mdee -V -w 170 a.md b.md # two files in 85 columns each
476  
477 Without nup (C<--style=cat>, C<pager>, C<filter>, or C<--no-nup>),
478 the text itself is the output, so this is the fold width.
479  
480 =item B<--fold-width>=I<N>
481  
482 Set the fold width for text wrapping directly. Default is the
483 pane width (output width divided by the number of columns) minus
484 3 for borders and padding and the run-in width (see C<--runin>),
485 which gives 78 when pane-width is 85.
486 Only effective when C<--fold> is enabled. Tables are fit into the
487 same width when it is given; otherwise, with nup, into this width
488 plus the run-in width but one (see C<--table>).
489  
490 =item B<--runin>=I<N>, B<--runout>=I<N>, B<--runlen>=I<N>
491  
492 Set the run-in and run-out widths that L<ansicolumn(1)|App::ansicolumn>
493 uses for line breaking (kinsoku) when nup folds the panes.
494 C<--runlen> sets both; options given later override earlier ones.
495 Default is 4. A run-in character may go past the fold width, so
496 ansicolumn keeps the run-in width free at the end of the pane, and
497 the default fold width is made narrower by the same amount. These
498 values are given to nup, and they take precedence over the values
499 in F<~/.ansicolumnrc>. The same values are given to the md module
500 as C<fold_runin> and C<fold_runout>, so that the lines it folds run
501 in by the width kept free, not more.
502  
503 =item B<--boundary>=C<word>|C<space>|C<none>
504  
505 Set where L<ansicolumn(1)|App::ansicolumn> may break a line when nup
506 folds the panes, as its C<--boundary> option: C<word> (default) does
507 not break inside an alphanumeric word, C<space> not inside a sequence
508 of non-space characters, and C<none> breaks anywhere. Lists, tables
509 and the paragraphs joined by C<--refill> are folded by the md module
510 at word boundaries, and this option keeps the other paragraphs, which
511 are folded by nup, in step with them. The value is given to nup,
512 which gives it to ansicolumn after F<~/.ansicolumnrc>, so it takes
513 precedence over the value there.
514  
515 =back
516  
517 =head2 Theme Options
518  
519 B<em·dee> supports color themes for customizing syntax highlighting.
520 Themes define colors for various Markdown elements (headers, code blocks,
521 bold text, etc.).
522  
523 =over 4
524  
525 =item B<-t> I<NAME>, B<--theme>=I<NAME>[,I<NAME>,...]
526  
527 Select color themes. The default is C<hashed,nomark,markcell,doubleline>,
528 which appends closing hashes to h3-h6 headers, hides markup
529 characters for a clean reading experience, marks the rows of
530 tables whose cells are wrapped, and gives h4 a double underline.
531  
532 Themes specified with C<--theme> are added to the default, not
533 replacing it (C<default[theme]> in the configuration file replaces
534 it). Multiple themes can be specified as comma-separated names or
535 by repeating the option. Each theme is applied in order as a
536 transformation, and when two themes set the same value the later
537 one wins:
538  
539 mdee --theme=warm file.md # the default themes + warm
540 mdee --no-theme --theme=warm # warm only (clear default first)
541 mdee --no-theme file.md # no theme (show all markup)
542  
543 Use C<--no-theme> to clear the default theme. It can be combined
544 with C<--theme> to start fresh.
545  
546 See L</THEMES> for the themes that come with B<mdee> and how to
547 write one.
548  
549 Use C<-d> to dump current theme values in sourceable format.
550  
551 =item B<-m> I<MODE>, B<--mode>=I<MODE>
552  
553 Select light or dark mode. Default is C<light>.
554  
555 If the terminal supports background color detection (via
556 L<Getopt::EX::termcolor>), the mode is automatically selected based on
557 terminal luminance.
558 When the environment variable C<TERM_LUMINANCE> is set (0 to 100, as
559 L<Getopt::EX::termcolor> uses it), its value is taken instead and the
560 terminal is not asked; below 50 is dark.
561  
562 Each theme has light and dark variants optimized for different terminal
563 backgrounds. The built-in C<default> theme uses RoyalBlue as the base
564 color with automatic luminance adjustment:
565  
566 =over 4
567  
568 =item C<light> - RoyalBlue with luminance 25 (dark text for light backgrounds)
569  
570 =item C<dark> - RoyalBlue with luminance 80 (bright text for dark backgrounds)
571  
572 =back
573  
574 =item B<-B> I<COLOR>, B<--base-color>=I<COLOR>
575  
576 Override the theme's base color. The base color determines the overall
577 color scheme because all heading colors (h1, h2, h3, etc.) are derived
578 from it by adjusting luminance. For example, h2 might be C<${base}+y20>
579 (base color with luminance increased by 20).
580  
581 B<Simple color name> - luminance is adjusted automatically:
582  
583 When you specify just a color name (without C<E<lt>E<gt>> brackets or
584 other syntax), the default luminance adjustment is applied based on
585 the current mode:
586  
587 -B RoyalBlue # becomes <RoyalBlue>=y25 in light mode
588 # becomes <RoyalBlue>=y80 in dark mode
589  
590 This makes it easy to try different colors without worrying about
591 luminance values. The default adjustments (C<=y25> for light, C<=y80>
592 for dark) are designed to provide good contrast against typical terminal
593 backgrounds.
594  
595 B<Full color specification> - used exactly as specified:
596  
597 If you include C<E<lt>E<gt>> brackets, luminance modifiers, or use RGB
598 notation, the value is used as-is without any automatic adjustment:
599  
600 -B '<Ivory>' # original color, no adjustment
601 -B '<Ivory>=y50' # explicit luminance 50
602 -B '#780043' # burgundy in hex
603 -B '(120,0,67)' # same color in RGB decimal
604  
605 B<Customizing the default adjustment>:
606  
607 The automatic luminance adjustment values can be customized with the
608 C<--adjust> option:
609  
610 --adjust light='=y30' # use =y30 instead of =y25 for light mode
611 --adjust dark='=y70' # use =y70 instead of =y80 for dark mode
612  
613 B<Note>: Basic ANSI color codes (C<R>, C<G>, C<B>, etc.) cannot be used
614 because heading variations require luminance adjustment, which only works
615 with full color specifications (X11 names, RGB hex, or RGB decimal).
616  
617 =item B<--config>=I<KEY>=I<VALUE>
618  
619 Set config parameters from the command line. Parameters are
620 passed to the L<App::Greple::md> module via
621 L<Getopt::EX::Config>. Theme keys recognized by mdee (C<base>,
622 C<FILE>, C<FILE_FORMAT>) are consumed locally and applied to both
623 light and dark themes; all other parameters are forwarded to the
624 md module.
625  
626 Color labels (C<h1>, C<bold>, C<italic>, etc.) are accepted as
627 config parameters and override default colors. The C<${base}>
628 placeholder can be used and will be expanded at runtime.
629  
630 mdee --config h1=RD # red h1
631 mdee --config bold=GD --config italic=YI # green bold, yellow italic
632 mdee --config h1='L25D/R;E' # custom h1 with background
633 mdee --config FILE='L25D/R;E' # red file label
634 mdee --config FILE_FORMAT=%s: # simple format
635 mdee --config hashed.h3=1 # enable h3 closing hashes
636 mdee --config cjk_friendly=1 # see LIMITATIONS, Emphasis
637  
638 Theme keys consumed by mdee:
639  
640 =over 4
641  
642 =item C<base> - Base color (equivalent to C<--base-color>)
643  
644 =item C<FILE> - Color spec for file label (default: C<L25D/${base};E> for light, C<L00D/${base};E> for dark). This is passed to greple's C<FILE> label and cannot be set via C<--cm>.
645  
646 =item C<FILE_FORMAT> - Format string for file label passed to greple's C<--format FILE=> (default: C<\n %s\n\n>). Cannot be set via C<--cm>.
647  
648 =back
649  
650 All other keys are passed to the md module as config parameters.
651 See L</Highlight Options> for the list of available color labels.
652 The md module also accepts operational parameters such as
653 C<table_trim>, C<table_width>, C<table_cell>, C<rule>, C<osc8>,
654 C<tick_open>, C<tick_close>, etc.
655  
656 =back
657  
658 =head2 Highlight Options
659  
660 =over 4
661  
662 =item B<--colormap>=I<LABEL>=I<SPEC>, B<--cm> I<LABEL>=I<SPEC>
663  
664 Override the color for a specific element. I<LABEL> is one of the
665 color labels listed below. I<SPEC> follows
666 L<Term::ANSIColor::Concise> format.
667  
668 --colormap h1=RD # red bold headings
669 --colormap code_block=/L20;E # dark background for code blocks
670 --colormap bold='${base}D' # base color bold
671  
672 This option is passed to the L<App::Greple::md> module, as a module
673 option before C<--> in the B<greple> command line (see it with C<-n>).
674 It is not the C<--cm> option of B<greple>, so C<FILE> and C<FILE_FORMAT>
675 are set by C<--config> instead.
676  
677 Available labels:
678  
679 h1 - h6 Heading levels 1 through 6
680 bold Bold (**text** or __text__)
681 italic Italic (*text* or _text_)
682 strike Strikethrough (~~text~~)
683 emphasis_mark Emphasis markers (**, *, __, _, ~~)
684 bold_mark Bold markers only (overrides emphasis_mark)
685 italic_mark Italic markers only (overrides emphasis_mark)
686 strike_mark Strike markers only (overrides emphasis_mark)
687 link Inline links [text](url)
688 image Images ![alt](url)
689 image_link Image links [![alt](img)](url)
690 link_mark Link/image brackets (overrides emphasis_mark)
691 br_mark <br> breaking a table cell (overrides emphasis_mark)
692 blockquote Blockquote marker (>)
693 horizontal_rule Horizontal rules (---, ***, ___)
694 comment HTML comments (<!-- ... -->)
695 code_mark Code block delimiters (``` and ~~~)
696 code_tick Inline code backtick markers
697 code_info Fenced code block info string
698 code_block Fenced code block body
699 code_inline Inline code body
700 meta_mark Front matter delimiter lines
701 meta_block Front matter body
702  
703 This option can be specified multiple times. Color labels can
704 also be set via C<--config>. When both are
705 specified, C<--cm> takes priority over C<--config>.
706  
707 =item B<--heading-markup>=I<STEPS>, B<--hm> I<STEPS>
708  
709 Control inline markup processing inside headings. By default,
710 headings are rendered with uniform heading color without processing
711 bold, italic, strikethrough, or inline code inside them. Links
712 are always processed as OSC 8 hyperlinks regardless of this option.
713  
714 Use C<all> or C<1> to enable all inline formatting within headings
715 using cumulative coloring. To select specific steps, list them
716 separated by colons.
717  
718 Available steps: C<inline_code>, C<horizontal_rules>, C<bold>,
719 C<italic>, C<strike>.
720  
721 mdee --hm all file.md # all markup
722 mdee --hm bold file.md # bold only
723 mdee --hm bold:italic file.md # bold and italic
724  
725 =item B<--show>=I<FIELD>[=I<VALUE>],...
726  
727 Control field visibility for highlighting. Empty value or C<0> disables
728 the field; any other value (including C<1>) enables it.
729  
730 --show italic # enable italic
731 --show bold=0 # disable bold
732 --show all # enable all fields
733 --show all= --show bold # disable all, then enable only bold
734  
735 Multiple fields can be specified with commas or by repeating the option.
736 The special field C<all> affects all fields and is processed first.
737  
738 See L</DESCRIPTION> for the list of available fields and
739 elements that are always active.
740 All controllable fields are enabled by default.
741  
742 =back
743  
744 =head2 Layout Options (passed to nup)
745  
746 =over 4
747  
748 =item B<-V>, B<--parallel>
749  
750 Show two or more files side by side, one pane per file, instead of
751 one after another. The screen shows as many files as fit, as many
752 as the pages of a single file, but not more than there are, and the
753 rest continue below; C<--pane> gives the number. Ignored with a
754 single file.
755  
756 With C<--lateral>, the rest go on to the right in one row instead,
757 and are scrolled sideways, a file at a time:
758  
759 mdee -LV *.md
760 mdee -LVC3 *.md
761  
762 =item B<-L>, B<--[no-]lateral>
763  
764 Put all the pages in one row, given to L<nup(1)|App::nup> as its
765 C<--lateral>. The screen shows as many pages as without it, and
766 space and C<b> of C<less> move by the screen as usual, while C<h> and
767 C<l> move by one page; see L<nup(1)|App::nup> for the keys and the
768 build of C<less> that keeps the pages at the edge of the screen. A
769 single pane goes to nup as well, so that the pages can be shifted one
770 by one. It cannot be used with C<--width>,
771 and nup refuses it with rows (C<-C2,2>, C<-R>, C<-G>) and PDF output.
772 With C<--parallel>, the files go on to the right in the same way,
773 each file a column scrolled up and down as usual; see C<--parallel>.
774 C<default[lateral]=1> in the configuration file makes it the default;
775 the default is left out where the option cannot be used, and
776 C<default[width]> is not used with it.
777  
778 =item B<-C> I<C>[,I<R>], B<--pane>=I<C>[,I<R>]
779  
780 Set the number of columns (panes). The number of rows may follow
781 after a comma: C<-C2,2> is 2 columns and 2 rows on a page, the same
782 as C<-C2 -R2>. When not specified (or 0),
783 the number of columns is calculated from the output width
784 (C<--width>, default terminal width) and C<--pane-width>. If only 1 column fits, nup formatting (borders
785 etc.) is preserved but pagination is handled by the pager instead.
786 Use C<--nup> to force nup's native pagination even in single column.
787  
788 =item B<-R> I<N>, B<--row>=I<N>
789  
790 Set the number of rows. C<-C> takes it as well, as C<-C2,2>.
791  
792 =item B<-G> I<CxR>, B<--grid>=I<CxR>
793  
794 Set grid layout. For example, C<-G2x3> creates 2 columns and 3 rows.
795 The text is folded for the number of columns of C<-C>, which this
796 option does not tell to mdee, so C<-C2,3> is better.
797  
798 =item B<-P> I<N>, B<--page>=I<N>
799  
800 Set the page height in lines.
801  
802 =item B<-S> I<N>, B<--pane-width>=I<N>
803  
804 Set the pane width in characters. Default is 85. This value is
805 used to calculate the number of columns from the output width,
806 and the default fold width. It has no effect when the number of
807 columns is given by C<--pane> or C<--parallel>.
808  
809 =item B<--bs>=I<STYLE>, B<--border-style>=I<STYLE>
810  
811 Set the border style.
812  
813 =item B<-->[B<no->]B<page-number>
814  
815 Show page number on the bottom border of each column. Enabled by
816 default. Use C<--no-page-number> to disable.
817  
818 =item B<-->[B<no->]B<filename>
819  
820 Show the file name label at the top of each file. Enabled by
821 default. Use C<--no-filename> to hide it, for example when files are
822 shown side by side with C<--parallel> and the panes should start with
823 the text. The label format and color are set by the C<FILE_FORMAT>
824 and C<FILE> theme keys (see C<--config>).
825  
826 =back
827  
828 =head2 Output Options
829  
830 =over 4
831  
832 =item B<--[no-]pager>[=I<COMMAND>]
833  
834 Set the pager command. Use C<--pager=less> to specify a pager,
835 or C<--no-pager> to disable paging.
836  
837 =item B<-T> I<DEVICE>, B<--device>=I<DEVICE>
838  
839 Set the device to show the output on, which is given to
840 L<nup(1)|App::nup>. The default is C<tty>, the terminal. Any other
841 device is a paper, and the output is printed to PDF by
842 L<ansi2pdf(1)|https://github.com/tecolicom/App-ansi2pdf>: C<a4> is A4
843 in landscape, C<a4p> is A4 in portrait and C<a3l> is A3 in landscape.
844 The device C<pdf> is the default paper, A4.
845  
846 mdee -T a4 README.md > README.pdf
847 mdee -T a4p -o README.pdf README.md
848  
849 The paper takes the place of the terminal, as described in
850 L</Printing to PDF>, and the pager is not used.
851  
852 This requires the nup style, and C<ansi2pdf>
853 0.1.3 or later for PDF (0.1.4 or later for the margin).
854  
855 =item B<-o> I<FILE>, B<--output>=I<FILE>
856  
857 Write the output to I<FILE>, which is given to L<nup(1)|App::nup>.
858 When the name ends with C<.pdf>, the output is PDF without C<-T> as
859 well. Otherwise, what is shown on the terminal is written to the
860 file as it is.
861  
862 mdee -o README.pdf README.md
863  
864 =back
865  
866 =head1 THEMES
867  
868 A theme changes how the document looks: the colors, the marks that
869 are shown or hidden, and the decoration of headings and tables.
870 Themes are chosen with C<--theme> (see L</Theme Options>), and each
871 is applied in order as a transformation of the default.
872  
873 =head2 Built-in Themes
874  
875 =over 4
876  
877 =item C<hashed> (default)
878  
879 Append closing hashes to h3-h6 headers.
880  
881 =item C<nomark> (default)
882  
883 Hide emphasis markers (C<**>, C<*>, C<__>, C<_>, C<~~>),
884 inline code backticks, link brackets (C<[>, C<]>), and the
885 C<< <br> >> that breaks a table cell into lines.
886 Content text keeps its formatting (bold, italic,
887 strikethrough, code, clickable links) but the surrounding
888 markers are not displayed. Table marks (C<markcell>,
889 C<markwrap>) are independent of this theme.
890  
891 =item C<doubleline> (default)
892  
893 Give h4 headers a double underline, which is C<ESC[4:2m>, in the
894 terminals known to take it, decided by environment variables: iTerm2,
895 Ghostty, cmux, VS Code, WezTerm, kitty, Alacritty, Konsole, Windows
896 Terminal and terminals based on VTE 0.52 or later. Elsewhere, inside
897 B<tmux> and B<screen>, and where the variables do not reach, as through
898 B<ssh>, this theme does nothing and h4 has a single underline, the same
899 as h5. Many terminals do not take the sequence: it becomes a background color in Terminal.app and
900 rxvt-unicode, and the Linux console and mosh drop the whole sequence
901 with its color.
902  
903 =item C<warm>
904  
905 Change base color to Coral.
906  
907 =item C<fatchap>
908  
909 Add decorative border lines (C<#>) above and below h1 headings,
910 using C<=+> to append a text transformation while preserving the
911 original heading color.
912  
913 With C<--refill>, the added lines are not counted, so paragraphs below
914 the h1 headings may not be folded properly by this module. The text
915 itself does not change. For this reason, this theme turns off
916 C<default[refill]> in the configuration file; C<--refill> given on the
917 command line still works.
918  
919 =item C<widen>
920  
921 Give circled digits and the wastebasket (U+1F5D1) a column of their
922 own, by adding a no-break space after them, for terminals that draw
923 them over two columns on top of the next character, as on macOS.
924 This gives the function of L<App::Greple::md::widen> to the C<--begin>
925 option of the md module.
926  
927 The characters are listed in the array C<widen_chars> of the theme, as
928 code points and ranges in hexadecimal. Add more in F<config.sh>:
929  
930 widen_chars+=(3248-324F) # circled numbers on black squares
931  
932 =item C<markcell> (default)
933  
934 In a table that has wrapped cells, mark the first line of every
935 body cell in the wrapped columns with C<‣> (U+2023), so that the
936 rows read like a bulleted list and the continuation lines stand
937 apart. The header row, columns that fit, and tables that fit are
938 not marked. Sets C<table_cell_mark>; C<nomark> does not affect it.
939 To use another character, set it in the configuration file or in a
940 theme of your own:
941  
942 md_config+=(table_cell_mark=∙) # U+2219
943  
944 =item C<markwrap>
945  
946 Mark the second and later lines of a wrapped table cell with C<›>
947 (U+203A). Sets C<table_wrap_mark>. It can be combined with
948 C<markcell>.
949  
950 =back
951  
952 =head2 Theme Files
953  
954 Theme files are searched in the following order:
955  
956 =over 4
957  
958 =item 1. User theme directory: C<${XDG_CONFIG_HOME:-~/.config}/mdee/theme/NAME.sh>
959  
960 =item 2. Share theme directory: installed with the distribution under C<auto/share/dist/App-mdee/theme/>
961  
962 =back
963  
964 Theme files are Bash scripts that can modify C<theme_light[]>,
965 C<theme_dark[]>, C<md_config[]>, and/or C<pass_md[]>:
966  
967 # theme/warm.sh — change base color
968 theme_light[base]='<Coral>=y25'
969 theme_dark[base]='<Coral>=y80'
970  
971 # theme/hashed.sh — enable closing hashes on h3-h6
972 md_config+=(hashed.h3=1 hashed.h4=1 hashed.h5=1 hashed.h6=1)
973  
974 # theme/nomark.sh — hide markers and brackets
975 pass_md+=(--cm 'emphasis_mark=sub{""}')
976 pass_md+=(--cm 'code_tick=sub{""}')
977 pass_md+=(--cm 'link_mark=sub{""}')
978  
979 =head1 CONFIGURATION
980  
981 User configuration is loaded from:
982  
983 ${XDG_CONFIG_HOME:-~/.config}/mdee/config.sh
984  
985 This is a shell script that can set defaults and override colors:
986  
987 # ~/.config/mdee/config.sh
988 default[mode]='dark' # set default mode
989 default[theme]='warm' # set default theme(s)
990 default[style]='pager' # set default style
991 default[width]=170 # set default output width
992 default[fold_width]=80 # set default fold width
993 default[refill]=1 # join paragraph lines
994 default[lateral]=1 # all pages in one row
995 default[base_color]='DarkCyan' # set default base color
996  
997 The C<default> associative array supports the following keys:
998  
999 =over 4
1000  
1001 =item C<default[mode]> - Corresponds to C<--mode> (e.g., C<dark>, C<light>)
1002  
1003 =item C<default[theme]> - Corresponds to C<--theme> (e.g., C<warm>, C<warm,hashed>)
1004  
1005 =item C<default[style]> - Corresponds to C<--style> (e.g., C<pager>, C<cat>)
1006  
1007 =item C<default[width]> - Corresponds to C<--width> (e.g., C<170>)
1008  
1009 =item C<default[fold_width]> - Corresponds to C<--fold-width> (e.g., C<80>)
1010  
1011 =item C<default[refill]> - Corresponds to C<--refill> (C<1> to enable)
1012  
1013 =item C<default[lateral]> - Corresponds to C<--lateral> (C<1> to enable)
1014  
1015 =item C<default[pane_width]> - Corresponds to C<--pane-width> (e.g., C<100>)
1016  
1017 =item C<default[pane]> - Corresponds to C<--pane> (e.g., C<2> or C<2,2>)
1018  
1019 =item C<default[base_color]> - Corresponds to C<--base-color> (e.g., C<DarkCyan>)
1020  
1021 =back
1022  
1023 B<Overriding theme colors>
1024  
1025 Config.sh can modify theme variables directly, using the same
1026 mechanism as theme files:
1027  
1028 # Change base color for both modes
1029 theme_light[base]='<DarkCyan>=y25'
1030 theme_dark[base]='<DarkCyan>=y80'
1031  
1032 # Enable md module features
1033 md_config+=(hashed.h3=1 hashed.h4=1 hashed.h5=1 hashed.h6=1)
1034  
1035 # Use another character for the table cell mark
1036 md_config+=(table_cell_mark=∙)
1037  
1038 These settings take precedence over the default themes.
1039  
1040 Changing the base color automatically affects all derived colors
1041 (h1, h2, bold, etc.) because the md module expands C<${base}>
1042 references.
1043  
1044 Use C<-d> to dump current theme values in sourceable format.
1045  
1046 B<Color specification format>
1047  
1048 Color specifications use L<Term::ANSIColor::Concise> format.
1049 The C<FG/BG> notation specifies foreground and background colors
1050 (e.g., C<L25D/${base};E> means gray foreground on base-colored background).
1051 The C<${base}> string is expanded to the base color value after loading.
1052  
1053 To change the text before it is formatted, give a function to the
1054 C<--begin> option of the md module:
1055  
1056 pass_md+=(--begin 'sub{ s/\(C\)/\x{A9}/g }')
1057  
1058 =head1 EXAMPLES
1059  
1060 mdee README.md # view markdown file
1061 mdee -C2 document.md # 2-column view
1062 mdee -C2,2 manual.md # 2x2 grid (4-up)
1063 mdee -w170 file.md # two 85-column panes on a wide terminal
1064 mdee -V -w170 a.md b.md # two files in 85 columns each
1065 mdee --fold-width=60 a.md # narrower text within the pane
1066 mdee --no-pager file.md # without pager
1067 mdee --no-nup file.md # output to stdout without nup
1068 mdee --no-fold file.md # disable line folding
1069 mdee --no-table file.md # disable table formatting
1070 mdee -r file.md # join paragraph lines
1071  
1072 # PDF
1073 mdee -o file.pdf file.md # A4 in landscape
1074 mdee -T a4p -o file.pdf file.md # A4 in portrait
1075 mdee -T a4p -C1,2 -o file.pdf file.md # two pages on a sheet
1076  
1077 # Output styles
1078 mdee -s pager file.md # fold + table, output to pager
1079 mdee -s cat file.md # fold + table, output to stdout
1080 mdee -s filter file.md # table only, no fold/nup
1081 mdee -s raw file.md # highlight only
1082  
1083 # Style shortcuts
1084 mdee -p file.md # same as --style=pager
1085 cat file.md | mdee -f # highlight stdin (filter mode)
1086 mdee -f file.md # highlighted output to stdout
1087  
1088 # Override individual settings
1089 mdee -f --fold file.md # filter + fold
1090 mdee -p --no-fold file.md # pager without fold
1091  
1092 # Theme examples
1093 mdee --mode=dark file.md # use dark mode
1094 mdee --mode=light file.md # use light mode
1095 mdee -B Ivory file.md # override base color
1096 mdee --mode=dark -B '#780043' file.md # dark mode with burgundy
1097 mdee --theme=warm file.md # warm (Coral) base color
1098 mdee --no-theme file.md # show all markup characters
1099  
1100 =head1 DEPENDENCIES
1101  
1102 This command requires the following:
1103  
1104 =over 4
1105  
1106 =item * L<App::Greple> - pattern matching and highlighting
1107  
1108 =item * L<App::Greple::tee> - filter integration
1109  
1110 =item * L<App::ansifold> - ANSI-aware text folding
1111  
1112 =item * L<App::ansicolumn> - ANSI-aware column formatting
1113  
1114 =item * L<App::nup> - N-up multi-column paged output
1115  
1116 =item * L<App::ansiecho> - ANSI color output
1117  
1118 =item * L<Getopt::Long::Bash> - bash option parsing
1119  
1120 =item * L<Getopt::EX::termcolor> - terminal background detection
1121  
1122 =back
1123  
1124 The code in fenced code blocks is colored by
1125 L<Text::ANSI::Highlight>, with C<pandoc> 3.4 or later
1126 (C<brew install pandoc>), or with C<source-highlight> or
1127 C<skylighting>. Without the command, the code is shown as it is.
1128  
1129 C<--refill> finds the paragraphs with L<Markdown::Perl> (pure Perl,
1130 installed with this distribution). The L<CommonMark> module, which
1131 needs the libcmark C library (C<brew install cmark>, C<apt-get install
1132 libcmark-dev>) and is only recommended, is used when it is there
1133 because it is faster; L<pandoc|https://pandoc.org> 2.11.3 or later is
1134 a third choice.
1135  
1136 =head1 LIMITATIONS
1137  
1138 =head2 HTML Comments
1139  
1140 Only HTML comments starting at the beginning of a line are highlighted.
1141 Inline comments are not matched to avoid conflicts with inline code
1142 containing comment-like text (e.g., C<< `<!-->` >>).
1143  
1144 =head2 Emphasis
1145  
1146 Emphasis patterns (bold and italic) do not span multiple lines.
1147 Multi-line emphasis text is not supported.
1148  
1149 C<***bold italic***> and C<___bold italic___> are supported.
1150 Other nested forms (e.g., C<< **bold _italic_** >>) are not.
1151  
1152 C<*> and C<**> start and end emphasis as in CommonMark: a delimiter
1153 with a letter on one side and punctuation on the other does not
1154 count, so C<L*=50, a*=68> is not italic. CommonMark counts Unicode
1155 punctuation, and this rejects some emphasis in Japanese text,
1156 such as C<日本語の*「強調」*です> and C<日本語の**強調。**です>. mdee
1157 shows them as the commonmark and gfm readers of pandoc and zenn.dev
1158 do, with the markers and without emphasis, so that such text can be
1159 found before it is published.
1160  
1161 With C<cjk_friendly=1> (C<--config cjk_friendly=1>, or
1162 C<md_config+=(cjk_friendly=1)> in F<config.sh>), the rules of
1163 L<markdown-cjk-friendly|https://github.com/tats-u/markdown-cjk-friendly>
1164 are used instead: CJK punctuation does not count, and a CJK character
1165 on the other side is as good as a space, so these are emphasis. This
1166 is a proposal, not part of CommonMark; use it for text that is
1167 processed by an implementation of it.
1168  
1169 =head2 Block Quotes
1170  
1171 A block quote is recognized by its C<E<gt>> markers at the start of a
1172 line, after up to three spaces. Only the markers are colored, not the
1173 quoted text. Headings, lists and code blocks inside a quote are not
1174 recognized, so they get no color of their own, and a code block in a
1175 quote does not protect its contents from inline highlighting.
1176  
1177 A line without a marker that continues a quoted paragraph (a lazy
1178 continuation in CommonMark) is shown as an ordinary line, unless
1179 C<--refill> joins it to the quote.
1180  
1181 =head2 Links
1182  
1183 Link patterns do not span multiple lines. The link text and URL must
1184 be on the same line.
1185  
1186 Reference-style links (C<[text][ref]> with C<[ref]: url> elsewhere)
1187 are not supported.
1188  
1189 =head2 Paragraph Refill
1190  
1191 C<--refill> joins lines by the rules of Markdown, as the parser
1192 reads them. Lines of verse, addresses or lyrics that rely on the line
1193 breaks without a hard line break (two spaces or a backslash at the
1194 end of the line) are joined as well, and so are the lines of a
1195 display math block between C<$$> lines. Do not use C<--refill>
1196 for such documents.
1197  
1198 =head2 Table Alignment
1199  
1200 Column alignment assumes that cell content in the source is not
1201 pre-padded. If the source table is already formatted with aligned
1202 spacing (e.g., C<| c |>), the embedded spaces become part of
1203 the cell content and alignment directives in the separator line
1204 will not produce the expected result. This is by design: pre-formatted
1205 tables are assumed to be correctly aligned as-is.
1206  
1207 =head2 OSC 8 Hyperlinks
1208  
1209 Links are converted to OSC 8 terminal hyperlinks for clickable URLs:
1210  
1211 =over 4
1212  
1213 =item C<[text](url)> - C<[text]> links to url
1214  
1215 =item C<![alt](url)> - C<![alt]> links to url (image)
1216  
1217 =item C<[![alt](img)](url)> - C<!> links to img, C<[alt]> links to url
1218  
1219 =back
1220  
1221 This requires terminal support. Compatible terminals include iTerm2,
1222 Kitty, WezTerm, Ghostty, and recent versions of GNOME Terminal.
1223 Apple's default Terminal.app does not support OSC 8.
1224  
1225 When using C<less> as pager, version 566 or later is required with
1226 C<-R> option.
1227  
1228 For OSC 8 specification, see:
1229 L<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>
1230  
1231 =head2 Terminal Luminance
1232  
1233 Without C<--mode> or C<default[mode]>, B<mdee> asks the terminal for
1234 its background color (OSC 11) through L<Getopt::EX::termcolor> to
1235 choose between light and dark mode. Set C<TERM_LUMINANCE> to a value
1236 from 0 to 100 to give the answer yourself and skip the query, for
1237 example in scripts or tests, where a reply that arrives late would
1238 show up as terminal input.
1239  
1240 =head2 Less Environment Variables
1241  
1242 When C<less> is used as pager (either directly via C<--style=pager> or
1243 through C<nup>), the following environment variables affect behavior.
1244 B<mdee> sets defaults for these when they are not already defined:
1245  
1246 =over 4
1247  
1248 =item C<LESS>
1249  
1250 Default: C<-R>. The C<-R> option is required for ANSI color
1251 sequences to be displayed correctly.
1252  
1253 =item C<LESSANSIENDCHARS>
1254  
1255 Default: C<mK>. This tells C<less> to recognize ANSI sequences
1256 ending with C<m> (SGR color) and C<K> (erase line). The erase line
1257 sequence is used for background color rendering.
1258  
1259 =back
1260  
1261 If you already have these variables set in your environment, B<mdee>
1262 does not override them.
1263  
1264 =head1 SEE ALSO
1265  
1266 =over 4
1267  
1268 =item L<Implementation of em·dee|https://github.com/tecolicom/App-mdee/blob/main/IMPLEMENTATION.md>
1269  
1270 How the pipeline, the themes and the colors work inside.
1271  
1272 =item L<App::Greple::md>
1273  
1274 Greple module for Markdown syntax highlighting, table formatting,
1275 and text folding. Bundled with this distribution.
1276  
1277 =item L<greple>
1278  
1279 General-purpose extensible grep tool used for pattern matching.
1280  
1281 =item L<nup>
1282  
1283 Multi-column paged output formatter.
1284  
1285 =item L<ansi2pdf|https://github.com/tecolicom/App-ansi2pdf>
1286  
1287 Renders the output to PDF.
1288  
1289 =item L<ansifold|https://metacpan.org/dist/App-ansifold/view/script/ansifold>
1290  
1291 ANSI-aware text folding for line wrapping.
1292  
1293 =item L<ansicolumn>
1294  
1295 ANSI-aware column formatting for table alignment.
1296  
1297 =item L<CommonMark>, L<Markdown::Perl>, L<pandoc|https://pandoc.org>
1298  
1299 One of them finds the paragraphs for C<--refill>.
1300  
1301 =item L<CommonMark Spec 0.31.2, Emphasis and strong emphasis|https://spec.commonmark.org/0.31.2/#emphasis-and-strong-emphasis>
1302  
1303 The rules that C<*> and C<**> follow by default (see L</Emphasis>).
1304  
1305 =item L<CommonMark CJK-friendly Amendments|https://github.com/tats-u/markdown-cjk-friendly/blob/main/specification.md>
1306  
1307 The rules that C<cjk_friendly=1> follows. The proposal comes from
1308 L<commonmark-spec issue #650, Emphasis with CJK punctuation|https://github.com/commonmark/commonmark-spec/issues/650>,
1309 open since 2020.
1310  
1311 =item L<https://github.com/tecolicom/App-mdee>
1312  
1313 Repository and bug tracker.
1314  
1315 =back
1316  
1317 =head1 AUTHOR
1318  
1319 Kazumasa Utashiro
1320  
1321 =head1 LICENSE
1322  
1323 Copyright © 2026 Kazumasa Utashiro.
1324  
1325 This software is released under the MIT License.
1326 L<https://opensource.org/licenses/MIT>
1327  
1328 =cut
« blib/lib/App/Greple/md/widen.pm ↑ Summary