Guide

Command Line Interface

To initialize a new site, create a site directory, cd into it, and run the init command:

$ malt init

To build an existing site, run the build command from the site directory or any of its subdirectories:

$ malt build

Use the malt --help flag to view the full command-line help text:

Usage: malt [FLAGS] [COMMAND]

  Malt is a static website generator. It transforms a directory of text
  files into a self-contained website.

Flags:
  --help            Print the application's help text and exit.
  --version         Print the application's version number and exit.

Commands:
  build             Build the current site.
  clear             Clear the output directory.
  init              Initialize a new site directory.
  serve             Run a web server on the site's output directory.
  watch             Monitor the site directory and rebuild on changes.

Command Help:
  help <command>    Print the specified command's help text and exit.

Run malt help <command> to view the help text for a specific command.

Site Structure

Initializing a new site creates the following directory structure:

site/
    site.py      # site configuration file
    ext/         # extensions directory for plugins
    inc/         # includes directory for menus, etc.
    lib/         # library directory for themes
    out/         # output directory for html files
    res/         # resources directory for static assets
    src/         # source directory for text files

The site.py site configuration file can be safely deleted if the site does not require custom settings; unused directories can likewise be deleted. (Note however that Malt requires the presence of either a site.py file or both src and out directories to identify a site's home directory.)

Static assets such as image files should be placed in the site's resources directory, res. The content of this directory is copied to the output directory each time the site is built.

Records

A record is a text file stored in a site's src directory. Malt searches the src directory for record files and generates a HTML page in the out directory for each one it finds. It can also generate a set of index pages for each directory of records.

Malt has builtin support for record files written in Markdown and Syntex. Files with a .md extension are rendered as Markdown, files with a .stx extension are rendered as Syntex. Malt can be extended via plugins to support other formats and extensions.

A record file can begin with a YAML header specifying metadata for the record:

---
title: My Important Document
author: John Doe
date: 2014-07-21
---

Record content begins here.

By default, a record's url slug is generated from its filename, but you can specify a custom slug in the header:

---
slug: my-custom-slug
---

Every record has a type, determined by its root type directory in the site's src directory:

src/
    pages/
        my-page.md     # this record is a page
    posts/
        my-post.md     # this record is a post

Malt has two builtin record types - pages and posts - but you can add as many custom types as you like simply by creating new type directories. Every type can have its own individual set of index and tag index pages.

You can determine the behaviour of your custom types (or alter the behaviour of the builtin types) in your site's configuration file. Assuming we'll be devoting a section of our site to sonnets, we may wish to create a custom type just for them. We can do this by adding a sonnets directory to our site's src directory.

src/
    sonnets/
        my-sonnet.md   # this record is a sonnet

New custom types behave, by default, like the builtin post type, but we can alter this behaviour by adding a dictionary of type settings to our configuration file:

sonnets = {                # type name corresponding to the type directory
    "title": "Sonnets",    # defaults to the titlecased type name
    "slug": "sonnets",     # defaults to the slugified type name
    "tag_slug": "tags",    # defaults to "tags"
    "indexed": True,       # build directory indexes for this type?
    "order_by": "date",    # order index entries by this attribute
    "reverse": True,       # display index entries in reverse order?
    "per_index": 10,       # number of entries per index page
    "per_tag_index": 10,   # number of entries per tag index page
    "homepage": False,     # use this type's index as the site homepage?
}

All the settings above are in fact defaults, and in practice we would only need to include those we wished to change.

Within a type directory, Malt will preserve any directory structure it finds, so you can use subdirectories to organise your record files by category or date. If the record type is indexed, Malt will generate an individual set of index pages for each subdirectory in the tree.

Record Attributes

Malt has builtin support for record metadata in YAML format; support for additional formats can be added via plugins.

Note that a record file's metadata keys are converted to lowercase and spaces are replaced by underscores so the YAML attribute:

---
Date of Birth: 1999-09-09
---

will be accessible in template files as record.date_of_birth.

All records have the following default attributes:

date

A default datetime stamp. If the record has a date attribute, this will be used. If not, the file creation time will be used if available (OSX, BSD, Windows), or else the time of the file's last metadata change (Linux).

ext

The record's file extension, e.g. md or stx.

html

The record's content, rendered into HTML.

slug

The record's url slug.

slugs

A list of output-path slugs.

src

The record's source filepath.

srcdir

The record's source directory.

text

The record's text content.

type

The record's type, determined by its parent type directory.

url

The record's URL.

Tags & Classes

Every record can be tagged and every record type supports its own individual set of tag index pages. To tag a record, simply add a tags attribute to its header followed by a comma-separated list of tags:

---
tags: foo, bar, baz
---

Records also support an optional classes attribute for styling:

---
classes: foo, bar, baz
---

Specified classes are added to the page's <body> element.

Malt generates page-relative urls and files with a .html extension by default, but you can customize this behaviour to suit your needs.

First, you can specify a root url in your site configuration file. Use an explicit domain, e.g. "http://example.com/", for absolute urls, or a single forward slash, "/", for site-relative urls.

root = "http://example.com/"

Second, you can specify a file extension in your site configuration file. You can choose an arbitrary file extension, e.g. ".html", or pass an empty string, "", to use no file extension at all. If you specify a single forward slash, "/", Malt will generate directory-style urls ending in a slash.

extension = ".html"

To link to files within your site from records or templates use site-relative urls prefixed by @root/, e.g.

@root/scripts/jquery.js

Malt will automatically rewrite these urls in the appropriate format.

Use two trailing slashes when linking to files generated by Malt itself - this tells Malt to rewrite the ending to suit your extension settings.

@root/posts/my-post//

Note that you should include the index slug when linking to directory or tag indexes:

@root/posts/index//

Linking to the homepage is a special case: a simple @root/ will always suffice.

Include Files

The includes directory, inc, is intended for snippets of content that can be reused on multiple pages throughout your site, e.g. menus or footer links. Source files placed in this folder will be parsed as Markdown or Syntex depending on their extension and the resulting HTML made available for inclusion in template files via the inc.<name> attribute.

For example, a menu can be constructed in either Markdown or Syntex using nested lists:

* [Home](@root/)
* [About](@root/about//)
* [Posts](@root/posts/index//)
    * [Cats](@root/posts/cats/index//)
    * [Dogs](@root/posts/dogs/index//)

If the menu above was contained in a file named menu.md then the rendered HTML would be available in templates via the inc.menu attribute. (Note that filenames are converted to lower case and spaces and hyphens are converted to underscores.)

Files with a .html/.js/.css/.txt extension will have their contents preserved as-is.

Markdown Options

Malt uses the Markdown package to render record files with a .md extension. You can add a dictionary of keyword arguments for the renderer to your site configuration file via a markdown attribute.

For example, to turn on the 'Markdown Extra' extension, add the following snippet to your malt.py file:

markdown = { 'extensions': ['markdown.extensions.extra'] }

See the Markdown package's documentation for details of its available options.

Jinja Options

Malt uses the Jinja2 package to render template files with a .jinja extension. You can add a dictionary of keyword arguments for the Jinja environment to your site configuration file via a jinja attribute.

Shortcode Options

Malt uses the Shortcodes package to process shortcodes in record files. You can add a dictionary of keyword arguments for the shortcode parser to your site configuration file via a shortcodes attribute.

Paging Options

Malt's bundled paging extension generates a customizable string of page navigation links for index pages. The links can be accessed in templates via the paging attribute.

Default settings can be overridden by including a paging dictionary in the site's configuration file containing one or more of the following options:

paging = {
    'first': 'First',  # text for link to first page
    'last': 'Last',    # text for link to last page
    'prev': 'Prev',    # text for link to previous page
    'next': 'Next',    # text for link to next page
    'delta': 2,        # number of neighbouring pages to include
    'multiples': 2,    # number of larger/smaller multiples to include
    'multiple': 10,    # multiplication factor
}

Only the options to be changed need to be specified.

Dependencies

Installing Malt via pip automatically installs the following required dependencies:

Installing via pip also automatically installs the following optional dependencies:

Malt will run without any of these optional dependencies installed but the associated functionality will not be available.