MarkupServe is a simple web server that renders provides convenient access to a tree of documents written in your favorite markup language. I wrote it because I wanted an easy way to interact with a tree of Markdown files without having to keep rendering them over and over again.
With MarkupServe, you can navigate a hierarchy of directories containing markup-language files in the same way you would navigate through an Apache directory tree. When the server is asked to retrieve a document written in the markup language, it passes the document through the converter of your choice and returns the resulting HTML.
NOTE:: Markupserve has only been tested with Python 2. Pull requests that introduce Python 3 support are welcome, but I have no plans to introduce Python 3 compatibility any time soon.
Check out this repo and run
pip install -r requirements.txt
MarkupServe uses bottle for serving, jinja2 for templates and whoosh for indexing and search.
If you're running an older version of Python, you may also need to install
argparse.
MarkupServe comes with a renderer (md-renderer.py) that does Markdown rendering
and syntax highlighting for [GitHub-Flavored Markdown][gfm]-style fenced code
blocks. To use the renderer, install its dependencies by running
pip install -r requirements.renderer.txt
It uses misaka for parsing Markdown, houdini.py for HTML-escaping text and Pygments for syntax highlighting.
MarkupServe reads its configuration from a config file (it looks for
config.cfg by default). It requires that you define the following parameters
in the [markupserve] section:
document_root: the root directory from which to serve documentsport: the port on which the server itself runsindex_root: the root directory where MarkupServe's search indices will be stored.
Sections whose names begin with format: define markup formats that can be
converted. Each of these sections requires the following parameters:
binary: the converter program used to convert markup documents. This can be specified as a relative or absolute path, or you can give a binary in yourPATHsuffixes: a comma-delimited list of the file suffixes that MarkupServe should interpret as the suffixes of files written in the target markup language
Here's an example minimal configuration file (also in config.cfg.sample) that
defines two formatters for Markdown and org-mode:
[markupserve]
document_root = ~/Documents
port=8080
index_root = ~/.markupserve_index
[format:markdown]
suffixes = .md, .text, .mkd, .markdown
binary = ./md-renderer.py
[format:org-mode]
suffixes = .org
binary = ./org-renderer.rb
You can hack the CSS for files and directory listings by editing
static/file_style.css and static/dir_style.css, resp.
"Views" of directories can be configured on a per-directory basis by adding a
file named .markupserve_dir_config to a directory. A list of supported views
and information about their settings is given below.
If you have a bunch of files of the form
<common prefix><year>-<month>-<day><common suffix>
in a directory, you can organize them into a calendar by month and year. To do
this, create a .markupserve_dir_config file with the following contents:
[style]
name: calendar
file_prefix: <your common prefix here>
file_suffix: <your common suffix here>
For example, I've got a bunch of research logs in a folder called "Research
Logs". The logs are consistently named as "Research Log YYYY-MM-DD.md". In my
case, file_prefix is "Research Log " and file_suffix is ".md".
The icons used for file navigation are from The Crystal Project. The default CSS used to render files is iAWriterCSS, which is a condensed versions of the styles used in iA Writer.