Categories are already implemented in PmWiki 2, and in most wikis they don't require any special code or markup, they're just a useful convention in Wiki pages. The idea is that every page that is in a given category should have a link to a shared category page.

Since PmWiki has WikiGroups?, I'll assume that category links go to the Category group. However, bear in mind that you can use any group or page naming scheme for this -- it's just a convention and doesn't require special programming support.

The key aspects of building a category are:

1. On every page that belongs to a category "XYZ", create a link on that page to [[Category/XYZ]] or [[Category.XYZ]].
2. Then, to see a list of all of the pages that belong to category XYZ, simply do a search to list all pages that have links to the Category.XYZ page.

PmWiki 2 makes this second step incredibly simple, since you can get easily generate a list of all pages with links to Category.XYZ by doing

    (:pagelist Category.XYZ:)

So, that's really all there is to categories. But wait, there's more!

As John Rankin pointed out in his excellent post, the above convention, combined with the fact that all of the category pages are in a single group, means that we can do much more. If we create a page called Category.GroupFooter, and put the following markup in that page

    (:pagelist Category.{$Name}:)

then every page in the Category group, even empty/non-existent ones, will display a list of pages that are in the category named by the page. For example, the Category.XYZ page display will automatically include Category.GroupFooter, and {$Name} in the GroupFooter will be replaced by the name of the current page (XYZ) to give us the (:pagelist Category.XYZ:) directive described above! So, we don't even need to write a bunch of (:pagelist Category.<Name>:) directives to create the page listings -- just creating a generic one in Category.GroupHeader or Category.GroupFooter will do it for all categories we might create.

So, what do we get? Every page belonging to Category.XYZ has a link to Category.XYZ, and following that link automatically displays a list of all pages in the XYZ category.

But that's not all...!

The Category.* pages can themselves be placed into categories! So, to follow John's excellent example, let's suppose we have the following film pages in the categories listed to the right:

 Film.SeanOfTheDead    [[Category/Horror]] [[Category/Comedy]] [[Category/2003]]
 Film.InMyFathersDen   [[Category/Drama]] [[Category/2004]]
 Film.TheCorporation   [[Category/Documentary]] [[Category/2003]]

Now then, we can create Category.Horror, Category.Comedy, Category.Drama, and Category.Documentary, and in each one of those pages we put [[Category/Genre]]. In Category.2003 and Category.2004, we put [[Category/Year]].

So, what happens when we display Category.Genre ? We see links to "Comedy", "Drama", "Documentary", and "Horror", because they're in the Genre category. When we click on one of those links, we see all of the films listed in one of those categories. Similarly, if we click on Category.Year, we see links to "2003" and "2004", each of which in turn displays the list of films for that year.

Finally, in Category.Genre and Category.Year we can put [[Category/Category]], which makes them "top-level" categories reachable from the Category.Category page. Voila, we now have an instant "hierarchy":

   Category.Category
       Category.Genre
           Category.Comedy
               Film.SeanOfTheDead
           Category.Drama
               Film.InMyFathersDen
           Category.Documentary
               Film.TheCorporation
           Category.Horror
               Film.SeanOfTheDead
       Category.Year
           Category.2003
               Film.SeanOfTheDead
               Film.TheCorporation
           Category.2004
               Film.InMyFathersDen

Note however that this isn't a "strict" hierarchy--i.e., any page or category can appear simultaneously in multiple categories. For example, Category.Documentary could be a member of both the Genre and top-level category listings.

Each category page can have content text before the generated list, e.g., to give a generic description of things in the category. (Or it can be empty, which works fine.)

And all of this works "out of the box" without any modifications to PmWiki 2.0! John goes a step further and proposes that we create a special markup for "Category", so that one can write things like [[!/Comedy]] and [[!/Genre]] instead of the longer [[Category/Comedy]] and [[Category/Genre]], but at the moment I'm leaving this as a (one-line!) local customization until it's widely adopted or we have a good standard markup for it. (TODO: add link to recipe)

  
    SDV($CategoryGroup,'Category');
    Markup('[[!','<links','/\[\[!([^\|\]]+?)\]\]/',
      "<span class='category'>[[$CategoryGroup/$1]]</span>");
  

Hope this helps.

TODO: add the text of John Rankins post too ?

samples (created in groups SampleCategory and SampleFilm):

• SampleCategory? - list of all amples categories used in the sample pages
• GroupFooter? - see text above
• SeanOfTheDead?
• InMyFathersDen?
• TheCorporation?