madblog

This project provides a minimal blogging platform based on Markdown files.

Demos

This project powers the following blogs:

• Platypush
• My personal blog

Installation

$ python setup.py install

Usage

# The application will listen on port 8000 and it will
# serve the current folder
$ madblog

usage: madblog [-h] [--config CONFIG] [--host HOST] [--port PORT] [--debug] [dir]

Serve a Markdown folder as a web blog.

The folder should have the following structure:

.
  -> config.yaml [recommended]
  -> markdown
    -> article-1.md
    -> article-2.md
    -> ...
  -> img [recommended]
    -> favicon.ico
    -> icon.png
    -> image-1.png
    -> image-2.png
    -> ...

positional arguments:
  dir              Base path for the blog (default: current directory)

options:
  -h, --help       show this help message and exit
  --config CONFIG  Path to a configuration file (default: config.yaml in the blog root directory)
  --host HOST      Bind host/address
  --port PORT      Bind port (default: 8000)
  --debug          Enable debug mode (default: False)

Configuration

See config.example.yaml for an example configuration file, and copy it to config.yaml in your blog root directory to customize your blog.

All the configuration options are also available as environment variables, with the prefix MADBLOG_.

For example, the title configuration option can be set through the MADBLOG_TITLE environment variable.

Markdown files

Articles are Markdown files stored under markdown. For an article to be correctly rendered, you need to start the Markdown file with the following metadata header:

[//]: # (title: Title of the article)
[//]: # (description: Short description of the content)
[//]: # (image: /img/some-header-image.png)
[//]: # (author: Author Name <email@author.me>)
[//]: # (published: 2022-01-01)

If no markdown folder exists in the base directory, then the base directory itself will be treated as a root for Markdown files.

Folders

You can organize Markdown files in folders. If multiple folders are present, pages on the home will be grouped by folders.

Images

Images are stored under img. You can reference them in your articles through the following syntax:

![image description](/img/image.png)

You can also drop your favicon.ico under this folder.

LaTeX support

LaTeX support is built-in as long as you have the latex executable installed on your server.

Syntax for inline LaTeX:

And we can therefore prove that \( c^2 = a^2 + b^2 \)

Syntax for LaTeX expression on a new line:

$$
c^2 = a^2 + b^2
$$

RSS syndacation

RSS feeds for the blog are provided under the /rss URL.

By default, the whole HTML-rendered content of an article is returned under rss.channel.item.description.

If you only want to include the short description of an article in the feed, use /rss?short instead.

If you want the short feed (i.e. without the fully rendered article as a description) to be always returned, then you can specify short_feed=true in your configuration.