Ir al contenido principal

Ralsina.Me — El sitio web de Roberto Alsina

Adding Support for a Markup to Nikola

One of the goals for Niko­la, my sta­tic si­te/­blog ge­ne­ra­tor is that it should be ea­sy to ex­ten­d. For exam­ple, to­day I added su­pport for two ma­rkup­s: tex­ti­le and Creo­leWiki.

Sin­ce Niko­la al­ready su­pported HT­M­L, reS­truc­tu­re­dText and Ma­rk­do­wn, adding a cou­ple mo­re is not ve­ry di­ffi­cul­t. He­re's ho­w:

  1. Crea­­te a .plu­­gin fi­­le like this one:

Name = textile
Module = compile_textile

Author = Roberto Alsina
Version = 0.1
Website =
Description = Compile Textile into HTML

Then you need to crea­te a py­thon mo­du­le ca­lled (in this ca­se) com­pi­le_­tex­ti­le.­py

That fi­le is boi­ler­pla­te plus two me­tho­d­s, com­pi­le_ht­ml and crea­te_­post

The com­pi­le_ht­ml me­thod takes two ar­gu­men­ts, one fi­le from whi­ch it rea­ds the ma­rku­p, and one to wri­te HT­M­L. Exam­ple:

def compile_html(self, source, dest):
    if textile is None:
        raise Exception('To build this site, you need to install the "textile" package.')
    with, "w+", "utf8") as out_file:
        with, "r", "utf8") as in_file:
            data =
        output = textile(data, head_offset=1)

Make su­re to use utf8 eve­r­yhe­re.

The crea­te_­post func­tion is us­ed to crea­te a new, emp­ty, post wi­th so­me me­ta­da­ta in it. Exam­ple:

def create_post(self, path, onefile=False, title="", slug="", date="", tags=""):
    with, "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("\nWrite your post here.")

The me­ta­da­ta has to be in the form ".. field­na­me: fiel­d­va­lue" and usua­lly nee­ds to be wra­pped in a co­m­ment so that it's not sho­wn in the ou­tpu­t.

The one­fi­le pa­ra­me­ter means you ha­ve to wri­te that me­ta­da­ta in the pos­t. If it's Fal­se, you do­n'­t.

In so­me ra­re ca­ses (Creo­le, I am looking at you) co­m­men­ts are not su­pported and you should rai­se an ex­cep­tion if one­fi­le is True.

And tha­t's it, ma­rkup su­pport is fair­ly ea­sy to add as long as the­re is a py­thon im­ple­men­ta­tion of a func­tion to con­vert ma­rkup in­to ht­m­l.

schettino72 / 2013-01-11 02:10:

(lazy) question: Where should I put these files (if I dont have access to modify nikola source) ? Just dropping it in the same place as my blog will work? Can I put them in a different folder?

Roberto Alsina / 2013-01-11 13:18:

Put them in yoursite/plugins and it "Just Works ®" :-)

I could add support for a NIKOLAPLUGINPATH variable or something but there's probably no point.

Contents © 2000-2023 Roberto Alsina