Mackerel is a minimal static site generator written in typed Python 3.6+.

Latest Version Build Status Coverage Status


This part of the documentation covers the installation of Mackerel.

pip install

To install Mackerel, simply run this command in your terminal of choice:

$ pip install mackerel

If you don't have pip installed, this pip installation guide can guide you through the process.

Get the Source Code

Mackerel is developed on GitHub, where the source code is available.

You can clone the public repository:

$ git clone

Once you have a copy of the repository you can install it:

$ cd mackerel
$ pip install -e .

Basic Usage

After succesfully installing mackerel you can use the mackerel cli to initialize a new site or build an existing one.

Start a new site

Mackerel's cli provides with an init command that generates a new site under the given directory name.

$ mackerel init ~/my_site

The mackerel directory structure looks like this:

├── .mackerelconfig  # The configuration file of this site
├── content  # The site's content
└── template  # The site's template

You can have a look at the generated .mackerelconfig file and content directory and alter them to your liking. For further documentation regarding the template development see the Template development section.

Build your site

The new site already contains some demo content and a template. The build command will build the site.

$ mackerel build ~/my_site

The static site will be generated inside the _build directory of the site.

You can use mackerel's development server to host the site.

$ mackerel develop ~/my_site

The development server automatically detects changes in the content and template folders and rebuilds the site.

Create a new page or post

Using your favorite editor, create a new .md file anywhere in the site's content directory. Make sure the new file has the .md file extension. The content file has two sections. The top section that contains metadata keys and values related to this document.

Title: New page
Author: John Doe
Date: December 31, 2099
Template: page.html
Custom_meta: Nyancat


And the main section that contains the actual content.


This is the main content of this document written in Markdown.


The .mackerelconfig file contains the configuration for the site

    OUTPUT_PATH = _build  # Sets the build output directory
    CONTENT_PATH = content  # Specifies the site's content directory
    TEMPLATE_PATH = template  # Specifies the site's template directory

[navigation]  # This section is used to define navigation menus for the template
    main =,  # The main navigation consists of the index and the about documents

[user]  # This section contains all the user / template site-wide settings
    title = Mackerel Example Site  # The site's title
    description = A beautiful narrative written with Mackerel. The story begins here.  # The site's description
    logo = img/logo.svg  # The path to the site's logo inside the content directory
    url = http://localhost:8000/  # The site's url (supports sub directories ex. /blog/)
    copyright = 2017 Paris Kolios  # Site-wide copyright string
    powered =  # Site-wide powered-by string

Template development

Currently the chosen template engine is Jinja2. When rendering the content files, Mackerel passes the following objects to the template:

  • document - the document that is currently being generated
  • ctx - the context object that contains the navigation & config objects
    • ctx.nav - the navigation object
    • ctx.cfg - the config parser object

Built With


Version 0.2


  • Fix an error in the packaging that caused mackerel init command to fail due to the lack of config.ini.


  • Rework the script to increase release automation.

Version 0.1

First preview release.


See the LICENSE file for details.