A Way of Using Include Directives in Markdown Posts and Pages
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...