Adding Support for a Markup to Nikola
One of the goals for Nikola, my static site/blog generator is that it should be easy to extend. For example, today I added support for two markups: textile and CreoleWiki.
Since Nikola already supported HTML, reStructuredText and Markdown, adding a couple more is not very difficult. Here's how:
Create a .plugin 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 create a python module called (in this case) compile_textile.py
That file is boilerplate plus two methods, compile_html and create_post
The compile_html method takes two arguments, one file from which it reads the markup, and one to write HTML. Example:
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 utf8 everyhere.
The create_post function is used to create a new, empty, post with some metadata in it. Example:
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 metadata has to be in the form ".. fieldname: fieldvalue" and usually needs to be wrapped in a comment so that it's not shown in the output.
The onefile parameter means you have to write that metadata in the post. If it's False, you don't.
In some rare cases (Creole, I am looking at you) comments are not supported and you should raise an exception if onefile is True.
And that's it, markup support is fairly easy to add as long as there is a python implementation of a function to convert markup into html.
(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?
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.