Static Markdown

A static web server with markdown rendering feature.

It serves regular HTTP content (HTML, JS, CSS, images, etc), but when you're browsing a .md, .mdown or .markdown file, it's converted into HTML and rendered as a (hopefully) readable page.

IMPORTANT WARNING

This server is not recommended for production. It's a toy to serve static files and Markdown content, but there's no guarantee about security, performance, availability, etc.

Installation

via PyPI

Install this tool using pip to download it from PyPI. You may prefer to use a virtualenv, but you may also want to install "user-wide".

pip install static-markdown
pip install --user static-markdown

Using the source

We're advising you to use virtualenv to install this package. Clone this repository, and, inside your virtualenv, run the following:

pip install -e ./

Usage

Once it's installed, you can just change your current shell session to the designated directory and run the following:

cd /path/to/directory
serve-md

Alternatively, you can also run this command line from anywhere, but set the target path as a command argument:

serve-md /path/to/directory

Using these default option, you can now browse your "static website" by pointing your browser to: http://127.0.0.1:8080/.

Stop the server with Ctrl-C.

Options

usage: serve-md [-h] [-p PORT] [--markdown-template MARKDOWN_TEMPLATE]
                [--stylesheet STYLESHEET] [--version]
                [root]

positional arguments:
  root                  Path to serve statically

optional arguments:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  Port number (0-65535)
  --markdown-template MARKDOWN_TEMPLATE
                        Path to an alternate HTML template for Markdown files
  --stylesheet STYLESHEET
                        Path to a custom stylesheet
  --version             Return version and exit

Browsing

Let's consider the following path tree:

.
├── empty
├── images
│   └── knight.png
├── index.html
├── mdown
│   └── index.md
├── mdown-readme
│   └── README.md
└── subdir
    └── index.html

Here is a table describing the different pages rendered with the given URL in your browser

Indexes

When browsing a directory, serve-md will look after the following files, in that specific order: "index.html", "index.htm", "index.md", "README.md", "readme.md". The first one of them to be found will be served as the index page of the directory.

If none of them is found, serve-md will return a directory listing. If you're using the "Markdown template" feature, it'll be used when rendering this page.

HTTP Verbs

GET & HEAD verbs are implemented.

POST, PUT, DELETE will result into a 405 Method Not Allowed error.

Markdown templates

By default, Markdown files will be rendered as HTML using a minimal CSS. Using the --markdown-template option, you can use your own HTML template with a custom CSS to render generate the text/html. You can find various examples in the example-options directory in the source repository.

We've used various minimalist CSS frameworks for rendering and layout:

• miligram,
• mini css,
• Github Markdown CSS,

Custom styles

If the only thing you need is to customize styles, but not the structure of your HTML page, you can use the --stylesheet option to point at a CSS file.

Example:

serve-md /path/to/directory --stylesheet ~/my-style.css

Hack

1. Clone this repository.
2. Write tests.
3. Implement stuff.
4. Open a Pull Request.

Important: Each time you're modifying any line of the server's code, if you want to test your patch live, you HAVE to stop and restart the application.

Run automated tests

In a shell session, run tests with:

make test