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 sequences of articles into threads."
}

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">
As with the title I usually want to include the date in the article itself. To avoid repeating yourself you can add the class "date_created" to a span element and the date will be inserted automatically.
<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.