Eyes-free Linux Ninja! (markdown)

How to Generate a Table of Contents in a Kramdown Document

Mike — Sat, 01 Apr 2017 20:15:59 GMT

Here's how to generate a table of contents in kramdown.



# Heading
{:.no_toc} 

## Table of Contents
{:.no_toc}

* TOC 
{:toc}

Introduction

The kramdown gem converts a kramdown file into html. It generates the id tags for each heading and uses them to generate a table of contents for a document. This becomes obvious if you take a file written in kramdown and convert it to html.

kramdown input-file.md > output-file.html

The ids are put on the generated html for all headings.

How To Automatically Generate A Table of Contents

Typically, you will want to have a numbered list for your table of contents or a bulleted list of entries. This is done by either writing 1. TOC or * TOC at the place in your file where you want the table of contents to be located. Underneath this line, specify the table of contents itself:



{:toc}

You can have either a numbered list of items or a bulleted list, in the normal way for lists:



1. TOC 
{:toc} 

* TOC 
{:toc}

If you do not want a heading to be included in the table of contents, put:



`{:.no_toc}

Underneath the entry you want to exclude from the table of contents, often your top-level heading.

Notes

I have noticed that there is either a bug or an accidental omission in the generation of the toc. For example,, given headings like this:



# First level one heading
## First level two heading 
## Second level two heading 
## Third level two heading
# Second level one heading

I would expect the second level one heading to be a member of the list of level one headings, but it is left hanging in between two lists of second level headings, and is a member of no list. This bug makes sub-lists and then a return to a lower level further down impossible.

So you will need to have all headings which go to make up a table of contents the same level.

A bit annoying but it beats constantly scrolling up and down a document as you write it to try to remember the order of the headings and their names.

Nikola plugin for kramdown

Mike — Thu, 04 Feb 2016 17:44:49 GMT

I’m not surprised that markdown has become so successful and ubiquitous. But one of the things I think it lacks is syntax for creating tables.

For this reason, I have been using a txt2tags plugin for a while. My sites all have a lot of tabular data, both as a function of the nature of the sites and also because I just like tables.

But I recently discovered kramdown.

kramdown has a super-set of markdown syntax, including simple, but powerful table-creation syntax.

So I’ve written a plugin for Nikola along the lines of the txt2tags plugin to compile HTML posts and pages from kramdown files. For which I have started using the .kd extension.

This post is written in kramdown.

So this post is somewhat by way of a test of my kramdown plugin for Nikola.

Third-level Heading

The above heading is marked with two hash characters and in the same way that markdown posts have their heading demoted by one level I have done the same with kramdown.

Here is a table of silly data:

Date	Weather	Activity
01-Feb-2016	Rain	Stayed in
02-Feb-2016	Dry and cloudy	Stayed in again
03-Feb-2016	Cold, -4C	Had to go out for most of the day
04-Feb-2016	Even colder than yesterday	Stayed in and wrote a kramdown plugin for Nikola

Lists

Lists are the same as in markdown

unordered list item one
Unordered list item two

Links

The links in the above text are all done like references are done in markdown, with the actual URI of each link at the bottom of the text file.

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

Emacs markdown-mode

Mike — Tue, 26 May 2015 00:23:08 GMT

Emacs (and hence Emacspeak) has an extension for writing and manipulating markdown files. I use markdown for writing the posts and pages for this site and others.

Nikola can be used with a number of different document compilers, that is, programs or plugins that can take documents authored in one kind of plain-text mark-up and convert it to another.

One of the best of these is markdown. Using markdown it is possible to write realy quite complex content, without the need to add the HTML or other complex mark-up tags that can make it difficult to see the wood for the trees.

Emacs has a major-mode for handling these files. I have published a page that contains tables of all the Emacs key-bindings for markdown-mode.