Skip to main content

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

Debian Mate Media Controls

This is another post which deals with issues surrounding the use of pulseaudio for text-to-speech and access tech such as the Orca screen-reader.

In the previous post I described how to switch speech-dispatcher over to ALSA and avoid the use of pulseaudio. Doing this will make the console accessible with speakup even when you are logged in to a graphical desktop.

But the default media controls in a Debian machine using the Mate desktop, at least at the time of writing with Debian Jessie, are for pulseaudio.

I have experienced issues with my Dell Latitude D630 where the headphone jack goes silent. I have never established why. This can be very annoying and happens at the most inopportune moments, usually in a room full of sighted folks who would very quickly try and lynch me if they had to listen to espeak through my PC speakers for more than five minutes.

This can be fixed by uninstalling a couple of packages and installing some alternatives.

The packages we are going to remove are:

  • `mate-media-pulse
  • mate-settings-daemon-pulse

The two packages we are going to install in their place are:

  • mate-media-gstreamer
  • mate-settings-daemon-gstreamer

But, beware! The first time I did this I made the mistake of purging the first two before I installed the new packages and it broke my installation. I then had to re-install Orca, Mate and lightdm.

So we are going to let apt-get make the decisions about what to install and what to remove.

Do the following:

$ sudo apt-get install mate-media-gstreamer
$ sudo apt-get install mate-settings-daemon-gstreamer

You will hear some stuff about removing one and replacing it with the other.

After this your sound controls in Mate should be much more usable and include the headphone jack if you have one.

I can't claim originality for this. The problem and the fix described was experienced by my fellow Linux and Raspberry Pi hacker Rill.