mandown - mdn

Note: this repo was forked from: https://github.com/Titor8115/mandown

A man-page inspired Markdown pager written in C.

What is it

mandown (executable name: mdn) is a small (~250kB) self-contained markdown renderer and pager. It is designed to be an alternative to pagers like more(1) and less(1), although its functionality apart from the markdown support is a lot more limited.

What alternatives exist?

Standard less(1) can be configured with a preprocessor to handle rendering of markdown files into ANSI escape sequences which less can display. One suitable preprocessor is bat(1), which supports a more complete subset of markdown. Another option is pygmentize. Either of these may already be available via your distro's repos.

To do so create an executable ~/.config/lessfile similar to this example:

#!/usr/bin/env sh
#
case "1ドル" in
*.md|*.MD|*.markdown)
 bat --color always "1ドル" ;;
esac

Then set the environment variable LESSOPEN=|${HOME}/.config/lessfile %s and less will be able to display markdown files. Depending on your terminal settings it may be necessary to use the -R flag to colorize the output.

Configuration

mdn supports minimal user customization via the config file located in ~/.config/mdn/mdnrc. The file gets created via make install and looks like this:

# If you want Terminal Emulator handle mouse event
# turn off "use_mouse"
use_mouse = true;
# Indent controls where manual's content start for each line
indent = 7;
# Supported Keybinding: "mdn", "vim", "less"
control_scheme = "less";

Hint: if you want to be able to use the mouse inside the editor spawned via the v command you should set use_mouse = false in this file.

Sample Display

screenshot

Library dependency

Mandown requires libncurses(w), libxml2 and libconfig as compile-time dependencies.

Make sure you have them installed before compiling.

Debian

$ apt-get install libncursesw5-dev
$ apt-get install libxml2-dev
$ apt-get install libconfig-dev

Installation

Current version is still being developed for some HTML tags. However, it should work on most Markdown documents.

Homebrew

$ brew install mandown

The installed binary mdn would be at /usr/local/bin/

Local

$ git clone https://github.com/Titor8115/mandown.git
$ cd mandown
$ make install

To remove the binary, you can run the commands below, or remove manually.

$ cd mandown
$ make uninstall

If you just want to compile and test it.

$ cd mandown
$ make

Feel free to create an issue.

Usage

Check out the new sample

$ mdn sample.md

Mouse scrolling is supported! (if your terminal emulator allows)

Move Up: Up, k

Move Down: Down, j

Page Up: Space, PgUp, b

Page Down: Bksp, PgDn, f

Show href in hyperlink: Tab + Enter, or double click mouse 1

Edit current file in $EDITOR: v (currently only works in 'less'-mode)

Exit: q

To read detailed usage, run mdn -h

Embedding

Mandown can also be embedded in your own applications. To render a Markdown document in a C string:

#include "mandown.h"
char *str ="# Heading\n\nThis is some **BOLD** *italic* ***EMPHASIZED*** text.";
render_str(str, "md", "Test Title", NULL);

To render a Markdown document file:

#include "mandown.h"
FILE *fp = fopen("README.md", "r");
render_file(fp, "md", "Test file", NULL);

Static and shared libraries are available. Make sure you have installed the dependencies listed in Library dependency below, then assuming you installed Mandown under /usr/local:

# static build
gcc -o myprog -I/usr/local/include myprog.c /usr/local/lib/mandown.a -lncurses -lxml2 -lconfig

# shared build
gcc -o myprog -I/usr/local/include myprog.c -L/usr/local/lib -lmandown -lncurses -lxml2 -lconfig

tests

Known Limitations

• the less control mode implementation is rudimentary
• mdn is just not a very good pager, compared to less or bat
• markdown support is limited and unlikely to be expanded
• after editing a file mdn quits. It should instead re-read the changed file and return to paged output, like less does.