Automatic Table of Contents in my awkiawki

Automatic Table of Contents in my awkiawki
------------------------------------------

Last edited: $Date: 2016/08/13 15:40:00 $

> awkiawki is written in awk

## awkiawki is a great, very light weight wiki running fine on a
Raspberry Pi

I have become a great fan of Awkiawki.

It is very light weight, well written, easy and fun to hack.

My awkiakwi started as a personal wiki, as a replacement of my
vimwiki. It has become my personal knowledge base and I use it every
day.

Please see my other Awkiawki pages.

## A nice automatic table of contents in javascript with jQuery

I wanted to have a automatic table of contents on the h3 titles and
found this page: Automatic Table of Contents by Chris Coyier
https://css-tricks.com/automatic-table-of-contents/.

With some tweaking, this little piece javascript now automaticly
creates a table of contents on the pages of my personal wiki ;)

## Create uniq ID identifiers in h3 headers

This is how I create uniq identifiers in the h3 headers. In the file
parser.awk a counter gets added:

/^==[^=]/ { $0 = "<h3 id=\"h3-" h3count++ "\">" substr($0, 3) "</h3>"; close_tags(); print; next; }

(As you can see from this line, I use the vimwiki dialect of
Markdown, which uses three equalsigns (===) to indicate an h3
header, instead of three poundsigns (###). More on this, why I use
the vimwiki dialect, is in my other awkiawki-pages. See the link
above.)

In the BEGIN part of file the parser.awk this counter is initialized:

h3count = 1

With these to small modifications, the wiki creates h3 headers that
look like this:

<h3 id="h3-2"> Unplug</h3>

Every h3 gets an uniq ID, so the jQuery ToC script can create
references to them.

## Create the javascript that builds the ToC

I have added a few lines to the javascript from Chris Coyier (see
above). First, I put the code inside a
$(document).ready(function(){ }); block.

Second, I only let the nav-part be put into the html when there is
more then one h3 header on the page. My awkiawki does not have a
article-container in the html code, but it does use a id="content"
div-container. So the script references this div-container instead
of the article-container.

Here is the complete javascript code:

$(document).ready(function(){
var ToC =
"<nav role='navigation' class='table-of-contents'>" +
"<h2>On this page:</h2>" +
"<ul>";

var newLine, el, title, link, count;

count = 0;

$("#content h3").each(function() {

el = $(this);
title = el.text();
link = "#" + el.attr("id");

newLine =
"<li>" +
"<a href='" + link + "'>" +
title +
"</a>" +
"</li>";
count++;
ToC += newLine;

});

ToC +=
"</ul>" +
"</nav>";
if ( count > 1 ) {
$("#content").prepend(ToC);
}
});

## Add the javascript and jQuery to the html pages

The file index.cgi holds the code to create the outer part of the
html files. The file parser.awk generates the inner part of these
files.

So to get the javascript and the jQuery file loaded by the browser,
we have to add these into the header of the html file, so we have to
tweak index.cgi, by adding just two lines:

print "<script src=\"/jquery.js\"></script>"
print "<script src=\"/inserttoc.js\"></script>"

This will let the browser create a table of contents, based on the
h3-headers in the output of the current awkiawki page. (see above).

## Add some CSS code

I just copied the CSS code from Chris Coyier (see above).

This makes a nice grey block on the webpage, with the table of
contents inside. The entries in the table of contents are clickable
and refer to the corresponding h3 header.

For me, this works great.

## Impact on the wiki

The javascript file is a separate file, so it will be cached by the
browser. The only extra work the parser has to do, is to add the
id="..." and incremement the counter. The result is that the
automatic table of contents does not increase the load on the
webserver, and the awkiawki is still very light weight.

However, on longer pages, it is great to have the table of contents
in the upper right corner. The user sees what is more on the page
("below the fold") at a glance, without the need to scroll down.

The table of contents is build as links to the individual h3
headers, so the user can by just a single mouseclick jump to the
according part of the webpage.

So it has great impact on the useability without any additional load
on the server.

$Id: awkiawkiautotoc.txt,v 1.3 2016/08/13 15:40:00 matto Exp $