Eyes-free Linux Ninja! (Nikola)

A Way of Using Include Directives in Markdown Posts and Pages

Mike — Tue, 23 Jun 2015 12:52:50 GMT

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...

Nikola plugins

Mike — Tue, 26 May 2015 10:59:07 GMT

I have installed a couple of plugins to help with Nikola page and post authoring.

These plugins are:

orgmode
txt2tags

The `orgmode` Plugin

The orgmode plugin uses Emacs in batch mode to provide a means of authoring Nikola posts and stories in .org files for conversion into HTML.

To install it:

nikola plugin -i orgmode

You will get a directory under your Nikola site:

plugins/orgmode

In this directory there are a number of files.

Providing you have version 8.0 or above of Emacs orgmode installed you will not need to do anything with the init.el file.

Pay careful attention to the conf.py.sample file and add the code-fragments to the COMPILERS =, POSTS = and PAGES = entries in your conf.py.

Once that is working correctly then:

nikola new_post -f orgmode -t "post title"

Should create a post-title.org file in your ./posts directory which you can edit using Emacs or Emacspeak and get all the benefits of orgmode power.

The `txt2tags` Plugin

For this, first you will have to install txt2tags. On Debian or Ubuntu you can do this like this:

sudo apt-get install txt2tags

Now install the Nikola plugin:

nikola plugin -i txt2tags

Again you will need to edit your conf.py file and change the POSTS =, PAGES = andCOMPILERS =` entries.

You can see how to by looking at values for other file types.

Now doing this:

nikola new_post -f txt2tags -t "post title"

Will give you a post-title.t2t file in your posts directory.

Why did I install txt2tags?

Because one of the great things txt2tags does that markdown does not is tables. And another great thing, and what made me install it, is the ability to give include directives in txt2tags files.

If you put this string in your .t2t file:

%!include: filename.t2t

When the page is rendered, the file willbe included. It does not have to be a .t2t file that is included. But the parent file will be rendered with the txt2tags compiler.

It was using the txt2tags plugin and syntax that I created the pages that show tables of reference data such as markdown-mode commands for Emacs. By including files in txt2tags syntax that are converted to HTML tables on the fly.

Why not just embed the files? Well this way I can use all kinds of jiggery-pokery including sed and grep commands to generate the .t2t table files from Emacs key-bindings harvested automatically.

Very neat.

Eyes-free Linux Ninja! (Nikola)

A Way of Using Include Directives in Markdown Posts and Pages

Embedding include Directives in Markdown Posts and Pages

Nikola plugins

The orgmode Plugin

The txt2tags Plugin

Embedding `include` Directives in Markdown Posts and Pages

The `orgmode` Plugin

The `txt2tags` Plugin