Mirrors/miller
1
0
Fork 0
mirror of https://github.com/johnkerl/miller.git synced 2026-07-17 16:38:54 +00:00
Code Issues Projects Releases Wiki Activity
miller/docs/src/output-colorization.md
John Kerl e0ed7e469c
Publish an epub of the docs on Read the Docs (#1835) (#2166) 
* Publish an epub of the docs on Read the Docs (#1835)

Read the Docs' built-in formats support (the existing formats: all in
.readthedocs.yaml) only produces epub/PDF for Sphinx projects, and is a
silent no-op for MkDocs ones. Instead, per RTD's documented
build-customization path, generate the epub ourselves in a post_build
job and place it in $READTHEDOCS_OUTPUT/epub/, which RTD then publishes
on the project Downloads page and in the docs flyout menu.

The epub itself is built by the new docs/build-epub.sh: it takes the
committed, generated Markdown pages in docs/src in mkdocs.yml nav
order, strips the HTML-only quicklinks header from each page, and runs
pandoc (installed on RTD via build.apt_packages). Locally, `make -C
docs epub` does the same for anyone with pandoc installed; nothing here
is part of `make dev` or any default build path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix misrender

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-07 14:55:36 -04:00

3.5 KiB
Raw Blame History

Quick links:   Flags   Verbs   Functions   Glossary   Release docs
# Output colorization

As of version 6.0.0, Miller supports output colorization. This includes colors per se, as well as bold, underline, and/or reverse. As of version 6.1.0, the default is bold+underline for keys -- this works well as a default regardless of your terminal's color settings -- with further customization options as described below:

pix/colorization.png

Things having colors

  • Keys in CSV header lines, JSON keys, etc
  • Values in CSV data lines, JSON scalar values, etc
  • "PASS" and "FAIL" in regression-test output
  • Some online-help strings

Rules for colorization

  • By default, colorize output only if writing to stdout and stdout is a TTY.

    • Example: color: mlr --csv cat foo.csv
    • Example: no color: mlr --csv cat foo.csv > bar.csv
    • Example: no color: mlr --csv cat foo.csv | less

  • NIDX output format (plain text, Unix-style, with implicitly positionally indexed fields) is not colored. This is because in other formats, keys are one color and values are another. For NIDX, all output is values.

Mechanisms for colorization

  • Miller uses ANSI escape sequences only.
  • Doesn't try to check to see whether the terminal is capable of 256-color ANSI vs 16-color ANSI. Note that if colors are in the range 0..15 then 16-color ANSI escapes are used, so this is in the user's control.

How you can control colorization

  • Suppression/unsuppression:

    • export MLR_NO_COLOR=true or export NO_COLOR=true means Miller won't color even when it normally would.
    • export MLR_ALWAYS_COLOR=true means Miller will color even when it normally would not. For example, you might want to use this when piping mlr output to less -r.
    • Command-line flags --no-color or -M, --always-color or -C.
    • On Windows, replace export with set

  • Color choices can be specified by using environment variables or command-line flags, with values 0..255:

    • export MLR_KEY_COLOR=208
    • export MLR_VALUE_COLOR=33
    • On Windows, replace export with set
    • Likewise for MLR_PASS_COLOR, MLR_FAIL_COLOR, MLR_HELP_COLOR, MLR_REPL_PS1_COLOR, and MLR_REPL_PS2_COLOR.
    • Command-line flags --key-color 208, --value-color 33, etc., and likewise for --pass-color, --fail-color, --repl-ps1-color, --repl-ps2-color, and --help-color.
    • This is particularly useful if your terminal's background color clashes with current settings.

If environment-variable settings and command-line flags are both provided, the latter take precedence.

How to see available color codes

Use mlr --list-color-names to see available names, like orchid. Colors can also be specified using numbers in the range 0..255, like 170: please see mlr --list-color-codes. You can also use bold, underline, and/or reverse. Additionally, combinations of all of these can be joined with a -, like red-bold, bold-170, bold-underline, etc.

pix/colorization2.png