darekmeco / consolemd

render markdown to the console (not just highlight it)

ConsoleMD

ConsoleMD renders markdown to the console.

Python 3

Due to the inexorable tides, ConsoleMD is now Python3 only. If things happen to work in Python2 then super great, but that is no longer a requirement.

Installation

It's highly recommended to install ConsoleMD inside a Python3 virtual environment.

# activate your python venv
pip install consolemd

# you probably want to make consolemd more accessible so...
cd ~/bin
ln -s ~/path/to/venv/bin/consolemd consolemd

Development

If you'd like to hack on ConsoleMD and/or run some mediocre tests, then please do the following:

git clone https://github.com/kneufeld/consolemd.git
cd consolemd

# make a python3 virtual environment and activate it

pip install -e .[test]
python setup.py test    # this will install some extra deps and run tests

Usage

You can treat consolemd pretty much like you would less or pygmentize.

consolemd --help
consolemd README.md
cat README.md | consolemd

You can change the colors consolemd uses via -s or the environment variable CONSOLEMD_STYLE=name.

If your terminal doesn't support true color (16 million colors) then run consolemd with --no-true-color or set environment variable CONSOLEMD_TRUECOL=0.

If you like really long lines that wrap at terminal edge then use --no-soft-wrap or set CONSOLEMD_WRAP=0.

To specify a max line width, then add -w N to the command line or export variable CONSOLEMD_WIDTH or MANWIDTH. Note that this feature is pretty hacky and lines with internal formatting will likely end up longer than the desired width.

A current at-time-of-writing list of pygment styles is the following:

abap algol algol_nu arduino autumn borland bw colorful default emacs
friendly fruity igor lovelace manni monokai murphy native pastie perldoc
rainbow_dash rrt sas stata tango trac vim vs xcode

consolemd uses native by default but monokai is also very nice.

Your terminal

iTerm2 under OSX is great and nicely supports true color. Urxvt under Linux only pretends to be true color and doesn't do it very well.

If you have strange color issues then running with --no-true-color should be the first thing you try. If that fixes your problem then make sure to add CONSOLEMD_TRUECOL=0 to your .bashrc.

See this gist for more info.

Italics, OSX, and you

For some reason Apple has disabled italics in the their terminfo files so you have to do a little patching to enable them. This is irrespective of which terminal program you use but may depend on what $TERM is set to.

Anyhow, based on this excellent post here's the tl;dr on enabling italics in OSX.

infocmp xterm-256color > /tmp/xterm-256color.terminfo
printf '\tsitm=\\E[3m, ritm=\\E[23m,\n' >> /tmp/xterm-256color.terminfo
tic /tmp/xterm-256color.terminfo

Note, the printf line above may not work quite right so edit /tmp/xterm-256color.terminfo and manually append sitm=\E[3m, ritm=\E[23m, to the end of the file.

Regardless, restart your terminal program of choice and italics should work. Test with:

echo `tput sitm`italics`tput ritm`

Why not just use pygments?

Because pygments highlights the markdown but doesn't strip out the control characters. Also, ConsoleMD uses CommonMark to parse the markdown instead of the lousy one in pygments (I'm allowed to say that since I'm the guy that wrote it).

Also, ConsoleMD uses some parts of pygments internally, and uses pygments to highlight code blocks.

CommonMark

Over the last few years there's been work on standardizing markdown with an official spec, that work happens at CommonMark.org.

The python implementation of the specification that I used is called CommonMark-py.

Github has recently (March 2017) converted all internal markdown to use a CommonMark parser, an interesting article can be found here.

Bugs?

Probably. There are lots of corner cases and it's not always clear what the proper output should even be. For instance, an executive decision was made to show url links as a list at the end of the document.

Unfortunately commonmark-py isn't very easy to use as a library so if any node types got missed then chaos may ensue. Please open a bug (or even better a pull request) so that consolemd can get patched up.

Unicode is always fun: ȧƈƈḗƞŧḗḓ ŧḗẋŧ ƒǿř ŧḗşŧīƞɠ

Contributing

If you help out in any way make sure you add your name to CONTRIBUTORS.md.

Example