Using an include directive with Markdown in Nikola Pages

I love markdown. I think it's the best thing since sliced-bread. The ability to write complex documents with a simple set of formatting syntax that can then be converted into a raft of other formats, possibly with pandoc is probably the single biggest boost to your productivity you could find if you write a lot of documentation.

Nikola uses markdown, among other flavours of document formatting such as restructured text and org-mode text (an Emacs major-mode). But my choice is usually markdown. One thing I thought it was lacking until somebody asked the question on the Nikola mailing list was an include directive similar to that in the C pre-processor.

What follows is a distillation of the ensuing posts and discussion from the list.

First install the markdown-include Python package:

sudo pip install markdown-include

Now modify your conf.py to add this, there is one commented out which looks similar:

MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra', 'markdown_include.include']

Embedding include Directives in Markdown Posts and Pages

To include a file in a Markdown post or page:

Note the path is relative to where markdown_include is being called from, not from the directory containing the post/page. So something like:

{!include/md/links.md!

Assuming you have include/md/* immediately underneath where your conf.py is, e.g. the root of your Nikola site.

To change the root of files you wish to include, in conf.py place the following:

from markdown_include.include import MarkdownInclude
my_include = MarkdownInclude(
    configs={'base_path':'/srv/content/'} # can also be relative path to conf.py
)
MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra', my_include]

I can't claim any originality for this as it was pulled directly from the Nikola email list. I'm putting it here because it's a subject that is very close to my heart, e.g. modularity. I've already installed the txt2tags plugin and I'm using t2t includes to pull-in tables of keyboard commands for such things as Emacs major-mode key-bindings.

This site seems to be veering slightly away from it's originally intended purpose of gathering into one place all kinds of stuff relating to accessibility on the Linux platform and becoming something of a personal blog and library archive for snippets of useful stuff.

Oh well, I guess it's my party...