Threader Usage

by Richard Taylor : 2019-01-27

When you run the threader in a top-level directory it looks for sub-directories that appear to be threads. Then it processes each thread and adds them all to a top-level index.

There are just 3 requirements to make a directory appear in the threader index.

1. A thread.json file in the directory
2. A file that has a title in the head element
3. A meta element with the creation date of the article

Lets look at each of those.

1. Config file

A thread is configured with a simple JSON file like this:

{
  "name": "Article Threader",
  "description": "A python module to link articles together."
}

The "name" and "description" fields are used in the index. Easy.

2. Title

The title is used in the index and also in the "previous" and "next" links described below. Because I usually have an h1 element that also contains the title, this can also be automaticaly populated by the threader. Just add the class "title".

<h1 class="title"></h1>

3. Creation Date

The threader uses the creation date to determine the ordering of articles in a thread. There is no standard for specifying this, but a common approach is to use a meta element like this:

<meta name="date.created" content="2019-01-27">

<span class="date_created"></span>

4. Previous and Next

As I said above, there are only 3 requirements for a thread article, so this part is optional. Without it you can still have threaded articles and an index.

If you want to have links in an article to the immediately preceeding and/or following articles in the series then you can do that with a span element that has either the "previous_article" or the "next_article" class.

<span class="previous_article"></span>
<span class="next_article"></span>

The threader will insert anchor elements into these spans which point to the right article and have the article's title as the anchor text. For the first and last article in a series there is obviously no link to insert so the text "This is the first article" or "This is the latest article" is used instead.

So if you change the title of an article (in the head element) then all you have to do is re-run the threader and all the links will be updated in all the neighbouring pages.

5. RSS Description

Another optional feature is the ability to add a description to a page.

<meta name="description" content="A short description.">

If present this will be added to the RSS feed inside a description tag. Many RSS readers will display this along with the title in the user's feed. It is definitely recommended if your title is very short or open to multiple interpretations.