MUP: a Markup Previewer
MUP is a markup previewer. It supports multiple markup formats. You can use it to read markup text, but it is also useful when writing markup text to check how your work looks, thanks to its refresh-as-you-save feature.
Features
- Supports multiple markup formats, easy to extend
- Automatically refreshes itself when the document is modified, tries to retain the position in the document after refreshing
- Skips metadata headers, such as those used by static blog generators like Jekyll
- Supports gzipped documents, useful to read documentation shipped with Debian packages
- Comes with a wrapper for man pages
Supported Formats
MUP supports Markdown and reStructuredText using Python modules.
It also supports the following formats using external converters:
- Markdown
- GitHub Flavored Markdown
- Ronn
- Man pages
- Asciidoc
- Mediawiki
External converters are command line tools which are invoked by MUP to convert input files. To be used as an external converter, the tool must accept markup on stdin and produce HTML on stdout.
Usage
Start MUP like this:
mup markup_file
To read a man page with mup:
mupman ls
Or:
mupman 5 crontab
Requirements
MUP requires Python 3 and the following Python modules:
It can make use of other Python modules and external tools to render various markup formats.
Markdown
For Markdown you need to install one of these:
- Python Markdown module
- Pandoc
- CommonMark
- Gruber Markdown
- Python Requests module: to render Markdown using GitHub Rest API (slow but accurate)
GitHub Flavored Markdown (GFM)
For GitHub Flavored Markdown (Markdown which takes newlines into account) you need to install one of these:
reStructuredText
For reStructuredText you need to install the docutils Python module.
Man pages
For man pages you need to install Groff (but it is already installed on most Linux distributions).
Ronn
For Ronn you need to install Ronn.
Asciidoc
For Asciidoc you need to install Asciidoc.
Mediawiki
For Mediawiki you need to install Pandoc.
Installation
Run ./setup.py install
as root.
Editing files
You can edit the current file by clicking on the menu button then select "Open with Editor". This will open the file in the configured editor.
To configure which editor should be used, edit ~/.config/mup/mup.yaml
and add
the following content:
editor: name-of-your-editor
Note: for now you cannot define arguments for the editor. If you need arguments you will have to write a wrapper shell script.
Defining a new Converter
To declare the foo2html
command as a converter for .foo or .foobar files,
create a foo.yaml
file in /usr/share/mup/converters
or in
~/.local/share/mup/converters
with the following content:
name: Foo
cmd: foo2html
matches: ["*.foo", "*.foobar"]
If MUP can find the foo2html
binary, it will use it whenever it tries to open
a .foo file.
Other optional keys:
args
: Arguments to pass to the commandfull
: Set to true if the command creates a complete HTML document, not just an HTML snippet (defaults to false)online
: Set to true if the converter uses an online service. Those are slower than offline ones and are thus not selected by defaultreference
: Set to true if the converter is the reference implementation for the format it handles. A reference converter will be selected by default if available
Contributing
MUP is managed using the lightweight project management policy.
Get the code from https://github.com/agateau/mup
then file pull requests
against the dev
branch.
Author
Aurélien Gâteau
License
BSD