One of the goals for Niko­la, my stat­ic site/blog gen­er­a­tor is that it should be easy to ex­tend. For ex­am­ple, to­day I added sup­port for two markup­s: tex­tile and Cre­oleWi­ki.

Since Niko­la al­ready sup­port­ed HTM­L, re­Struc­tured­Text and Mark­down, adding a cou­ple more is not very dif­fi­cult. Here's how:

1. Cre­ate a .plug­in file like this one:

[Core]
Name = textile
Module = compile_textile

[Documentation]
Author = Roberto Alsina
Version = 0.1
Website = http://nikola.ralsina.me
Description = Compile Textile into HTML

Then you need to cre­ate a python mod­ule called (in this case) com­pile_­tex­tile.py

That file is boil­er­plate plus two meth­od­s, com­pile_html and cre­ate_­post

The com­pile_html method takes two ar­gu­ments, one file from which it reads the markup, and one to write HTM­L. Ex­am­ple:

def compile_html(self, source, dest):
    if textile is None:
        raise Exception('To build this site, you need to install the "textile" package.')
    try:
        os.makedirs(os.path.dirname(dest))
    except:
        pass
    with codecs.open(dest, "w+", "utf8") as out_file:
        with codecs.open(source, "r", "utf8") as in_file:
            data = in_file.read()
        output = textile(data, head_offset=1)
        out_file.write(output)

Make sure to use ut­f8 ev­ery­here.

The cre­ate_­post func­tion is used to cre­ate a new, emp­ty, post with some meta­da­ta in it. Ex­am­ple:

def create_post(self, path, onefile=False, title="", slug="", date="", tags=""):
    with codecs.open(path, "wb+", "utf8") as fd:
        if onefile:
            fd.write('<notextile>  <!--\n')
            fd.write('.. title: %s\n' % title)
            fd.write('.. slug: %s\n' % slug)
            fd.write('.. date: %s\n' % date)
            fd.write('.. tags: %s\n' % tags)
            fd.write('.. link: \n')
            fd.write('.. description: \n')
            fd.write('--></notextile>\n\n')
        fd.write("\nWrite your post here.")

The meta­da­ta has to be in the form ".. field­name: field­val­ue" and usu­al­ly needs to be wrapped in a com­ment so that it's not shown in the out­put.

The one­file pa­ram­e­ter means you have to write that meta­da­ta in the post. If it's False, you don't.

In some rare cas­es (Cre­ole, I am look­ing at you) com­ments are not sup­port­ed and you should raise an ex­cep­tion if one­file is True.

And that's it, markup sup­port is fair­ly easy to add as long as there is a python im­ple­men­ta­tion of a func­tion to con­vert markup in­to htm­l.