Kirby Table of Contents

|

Introduction

For longer blog entries, it would be nice to be able to divide them into different sections and show a table of contents, such as done on this site. While Kirby, the CMS I am using for this site, allows to add different levels of headlines by adding one or multiple # in front of text, it does not automatically create anchors, which can be linked to. Additionally, there is no option to automatically create a table of contents of a page.

NOTE:

This is for Kirby 2. It might work for Kirby 1 as Kirbytext Extension Plugin, but I have not tested that.

Content

| Introduction
| Installation
| Usage
| | Headlines
| | Table of Contents
| Issues
| Download

Installation

To install the script, download it and simply place it in the site/tags folder within your Kirby installation.

Usage

Headlines

As I required the above functions, I implemented these myself, by using Kirby Tags, thus extending the underlying Markdown specification of Kirby. I added tags for different level headlines (e.g. l1, l2, ...), which automatically generate an anchor, with the same name as the text of the headline:

conventional: #Headline1
new: (L1: Headline1) *note: use small l1, had to use capital to avoid interpretation

conventional: ##Headline2
new: (L2: Headline2) *note: use small l2, had to use capital to avoid interpretation

conventional: ###Headline3
new: (L3: Headline3) *note: use small l3, had to use capital to avoid interpretation

conventional: ####Headline4
new: (L4: Headline4) *note: use small l4, had to use capital to avoid interpretation

conventional: #####Headline5
new: (L5: Headline5) *note: use small l5, had to use capital to avoid interpretation

conventional: ######Headline6
new: (L6: Headline6) *note: use small l6, had to use capital to avoid interpretation

Table of Contents

I created an additional tag, which allows to automatically create a table of contents, based on the above headline definitions:

(TOC: 6) *not: use small toc, had to use capital to avoid interpretation

The parameter given to the table of contents tag is the number of levels that shall be shown in the table. I do not always want to show a full table, but maybe only the first one, two or three levels. This can be accomplished by setting the parameter to the respective value.

Further, the script only selects headlines from level 2 onwards, as I am using level 1 headlines for pages or higher-level ordering.

Issues

The table of contents currently does not implement all special characters. If used in a headline, the link might not work.

In the future a nicer or adaptable design of the table of contents could be nice. For now, this needs to be adapted manually by replacing the "|" in the PHP code.

Download

The script is available on GitHub