tdryer / panserver

A simple HTTP server to view rendered Markdown documents, which automatically refresh.

Panserver

Panserver is a very simple HTTP server written in Python 3 to view rendered Markdown documents. It is not intended to be used as web-facing server. Instead it is a helper to view Markdown locally. For rendering pandoc is employed, which must be installed. The Python library bottle must be installed as well.

Features include:

• table of contents
• automatic refresh
• inline math
• rendering of inline dot and plantuml diagrams

Quick Start

Run the command

python panserver.py [-a] [-b] path

where path is the path to the directory of your document(s).

Now open http://localhost:8080/ in a browser (which is done automatically if you specified the -b option). You will find an index of all Markdown documents in the directory. Click on a link to view the rendered documents. If -a was specified, the view will auto-refresh when you save the Markdown file!

Usage

Command line (given python is Python 3):

python panserver.py [-a] [-b] [-r] [-p port] [path]

This starts a local http server. The Markdown conversion utility pandoc must installed and available on the path. The python library bottle must be installed and available as well. No further dependencies or files are required; except for the mentioned dependencies, panserver.py is self-contained.

Hit Ctrl-c to stop the server.

Path

A path to the to the document directory. If no path is specified the current working directory is used. All files (not only Markdown documents) in the directory and all its subdirectories will be available through the server! This in necessary to allow you to link images (or scripts and stylesheets etc) in your documents.

Auto-refresh: -a

Specifying this option makes Panserver include a small script into the generated HTML. The script will constantly poll the server and refresh the page when the corresponding Markdown source file has been updated.

Open browser: -b

If you specify this option, Panserver will open its index page in your standard web browser.

Allow remote connections: -r

Specify this flag if you want to access the server from a different machine.

Port: -p number

You can set the port Panserver should listen to with this option. The default is 8080.

Behaviour

When you start Panserver it will act as an HTTP server (on the given port). On the same machine it will be available in a web browser as http://localhost:8080/ (substitute 8080 with correct port if you specified it explicitly).

Beware that access is not necessarily restricted to the same machine! Unless -r is specified, Panserver will try restrict itself to local connections but there is no guarantee. All files (not only Markdown documents) in the document directory and all its subdirectories will be available through the server to whomever has access to the port on that machine!

Index page

The index page is available at address / (that is http://localhost:8080/ normally). It will list all markdown files in the document directory.

Markdown views

The address /view/<some_path>, where <some_path> or <some_path>.md is a path relative to the document directory to a Markdown file, is a Markdown view page. It will display the output of pandoc for the given Markdown file plus some minimal styling.

You can view the markdown files in different formats. These can accessed through the menu at the top of the standard view of markdown documents. The alternative views are:

• export: Ideal for saving the output. Like the standard view but without the menu and auto-refresh script.
• simple: Remove the default styling and the menu.
• inline: Remove the default styling, the menu, and the HTML skeleton around the output. This is for inclusion into existing HTML documents.

The default format features a table of contents (floating on the left on large enough displays). It can be toggled via the top menu. Clicking a links jumps to the corresponding part of the document.

Integrated diagram processing

A markdown document can contain integrated diagrams. These are markdown code sections annotated with the corresponding tool name. Panserver extracts the code sections, processes the code with the given tool (which must be installed and on the path). Then the generated image in inserted in place of the code. So markdown that looks like this:

``` dot
digraph {
    rankdir=LR;
    A -> B;
}
```

is converted inline into this:

Current supported tools are:

• dot: Graphviz graph diagrams
• plantuml: variety of UML diagrams

Other files

The address /view/<some_path>, where <somepath> is a path relative to the document directory to a non-Markdown file, will serve the file like a normal HTTP server would.