THIS PLUGIN IS NO LONGER MAINTAINED If you would like to take over as the maintainer please contact me.

VERY IMPORTANT: SubjectIndex ONLY works with the new WeatherWax release of DokuWiki and higher.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Please report any bugs or problems on GitHub using the link above. Thanks!

NEWS: 2013-11-21—The newest version offers a new simpler syntax for Entries, however the old syntax will continue to work for backwards compatibility. See syntax table below for details. There are also 3 new options: showcount, hidejump, and regex, plus a ~~nosubjectindex~~ directive for pages. In addition the subjectindex markup can be spread over multiple lines for clarity.

Internally the plugin has been completely rewritten to make it easier to maintain, more reliable, and quicker to use.

Latest version:

• Merge pull request #21 from splitbrain-forks/php7-signature (2016-01-26 08:33)
• Adjust method signatures to match parent (2016-01-24 13:29)
• Update plugin.info.txt (2014-05-25 18:00)
• Anchor links now work correctly again! (2014-05-04 17:59)
• Bugfixes; new ~~nosubjectindex~~ directive (2013-11-22 12:26)
• Major refactoring; new Entry syntax (2013-11-21 17:22)
• Fixed errors on snippet creation (2013-10-18 18:32)
• Ensure 100% div width (2013-07-07 14:35)
• Fixed: external border was missing (2013-04-17 19:49)
• New label option; fixed verse tag bug (2013-04-10 19:59)

“Structured Hierarchical Tagging”: Create A-Z book-style subject indexes for your wiki, grouping together related topics and ideas, and make better sense of your wiki content!

Can also be used for normal-style tagging (hash-tagging), and also compiling bible verses. Can be extended by plugins to support other consistent reference formats.

Add a subject index entry¹⁾ anywhere you like on your wiki pages, in-line or below the text. The plugin will automatically collect and sort these entries into a book style A-Z hierarchical index. You can then show these indexes on any page in your wiki, by A-Z, or in a manual order. For example by default A-Z indices are listed by first letter, then by the various headings, finally by the description and page link.

This plugin can also be used for simple tagging. However it generates a much more useful, readable index table, instead of a tag-cloud. The result is rather like thumbing through the A-Z subject listing at the end of a good reference book: it allows you to get a clear overview of the main topics and see relationships between pages.

NOTE: this markup can be spread across multiple lines which often helps when writing/understanding a complicated SubjectIndex list. Any whitespace between the options will simply be ignored. E.g.

{{subjectindex>
    section=1;
    cols=3;
    proper;
    showcount;
    hidejump;
    border=both
}}

To use this plugin there are 2 basic things you need to do:

• Create index Entries or Tags on your wiki pages: place them anywhere you want, as often as needed.⁵⁾

  e.g. {{entry>1;Something/About/Nothing}}    #this_is_a_tag

• Create pages containing the Subject Index mark-up to show the index for a specific Section, i.e. An A-Z index with links to each page.

  e.g. {{subjectindex>section=1;cols=3;proper;abstract;default}}

Behind the scenes the plugin collects all the different Entries as your browse your wiki and stores them in a hidden Index divided into Sections. This then allows you to list any Section as Subject Index list on a page. rather like the Index at the back of a decent reference book. You can of course have more that one Subject Index list one on a page. For example, use it to create a bibliography, a chronology, a tag list, a list of topical references, etc… The system is really flexible!

As you add a new entry you can specify which Section number (0+) the entry belongs to. However the plugin also needs to know ahead of time which page in your wiki these Entries should link to… so you also have the option to set a default target page for each Section in the index.

An example may help: if you put the {{subjectindex>section=2;default...}} markup on a page then all Entries belonging to section 2 will link automatically to this page. The plugin will warn you if you try to create an Entry without first setting up a default page.

{{entry>section;heading/subheading/entry;display text}}

• section : the entry will be added to this section of the subject index. Section is a number, from 0 upwards
• heading : the main heading that will be shown on the subject index display page. The first letter is used for A-Z headings.
• subheading : additional sub-headings below the main one above (can be more than one). Use this to create a hierarchy within the subject index as needed.
• entry : the actual entry text; a meaningful description of what this entry is about.
• display text : what should be visible on the page: can be the Entry's text (default), different text, just a star, or nothing at all!

#tag #multi_word_tag

All international characters are accepted, however you cannot use spaces⁶⁾. However, you can use an underscore (_) instead and it will be converted into a space when the tag is displayed.

NOTE: behind the scenes tags are simply a short-cut for normal subject index entries, i.e. assuming the default settings you could also create a tag by typing: {{entry>1;tag}}

Some examples:

{{entry>books/fiction/writing novels;-}}
{{entry>1;book/binding;}}
{{entry>2;books/fiction/writing technical documentation;Writing Docs}}

The last example above would create a new subject index entry as follows:

• B
  • books
    • fiction
      • writing novels: page link⁷⁾

By default only the entry text displayed on the wiki page, but you can also show any text you like as described in the syntax table above.

Full examples:

{{entry>books/fiction/writing novels;-}}   => nothing visible at all (think: minus or a blank place-holder)
{{entry>books/fiction/writing novels}}     => entry text (default)
{{entry>books/fiction/writing novels;*}}   => full entry text + star symbol

What if you need to control the order of the entries in the index list? You'll be happy to know that there is a way to do this—a quite easy way in fact!

You can manually set the order of each entry by putting a number followed by a full-stop/period in front of any of the headings, subheadings, or entry text. An example shows this best:

{{entry>2.books/3.fiction/1.writing novels}}
{{entry>1.movies/1.comedy/3.Three Amigos}}
{{entry>3.animals/elephants}}

In the examples above the sorting order would normally be A-Z: animals ⇒ books ⇒ movies, but in this case the manually created list numbers will be respected instead: 1.movies ⇒ 2.books ⇒ 3.animals. The numbers within each level will be respected too.

By default the bullet numbers will not be displayed, but you can make them visible by using the showorder option as noted above in the table. This is mainly for troubleshooting the manual order you are creating.

Details of some of the options

• abstract : Show an abstract of a page's content as a tool-tip. This is based on the existing Dokuwiki page abstract and is plain-text only.
• cols=? : Number of columns on the index page, or the column width. See Syntax Table above: use a CSS unit after the number if you want to set the width, e.g. 10em, 60px, 20%, etc…
• proper : Use proper-case for wiki-page names and entries. This means First Letter Of Each Word In Capital Letters
• title : Use title (1st heading in the page) instead of name for links.
• default : Make this page the default target for all entries for this section (as defined in section=? above). Setting a page as default allows the two-way links to function correctly (the Entries need to know where the Subject Index pages are, and vica-versa…!).
• hideatoz : Remove the A-Z headings. This is useful when your index is number based for example, or you have your own key headings.
• regex : Use a regular expression to filter the list, e.g to find only entries containing the word “Music”you could add: regex=(?i)music (where (?i) means case-insensitive)

Imagine 3 different pages in your wiki, as listed below. The entries can be inserted anywhere you like on the page: beginning, end, in-line with other text, whatever you prefer.

building.txt

{{entry>Construction/Foundations}}
{{entry>Construction/Bricklaying}}
{{entry>Construction/Roofing}}
{{entry>Planning/Creating a BOQ}}

accounting.txt

{{entry>Banking/Opening an account}}
{{entry>Banking/Adding a 2nd holder}}
{{entry>Planning/Preparing a budget}}
{{entry>HR/Choosing the right people}}

subjects.txt

{{subjectindex>section=0;...}}

Would result in a list like this:

  B
      Banking
          Adding a 2nd holder  [[accounting.txt]]
          Opening an account  [[accounting.txt]]
  C
      Construction
          Bricklaying  [[building.txt]]
          Foundations  [[building.txt]]
          Roofing  [[building.txt]]
  H
      HR
          Choosing the right people  [[accounting.txt]]
  P
      Planning
          Creating a BOQ  [[building.txt]]
          Preparing a budget  [[accounting.txt]]

* [[...]] means a hyperlink to the actual page

As you can see the A-Z Subject listing is automatically built from the page Entries.

To prevent a page from being indexed by the SubjectIndex plugin just place the following anywhere on the page:

~~NOSUBJECTINDEX~~  OR  ~~nosubjectindex~~

It can be upper or lower case, it doesn't matter. This command stops any valid subject index entries on that page from being added to the index. This is useful especially when you need to add a help file about the plugin itself to your own wiki.

There is currently one setting that can be changed on the Dokuwiki configuration page:

If at all possible please use the issue tracker on GitHub for bugs, problems, suggestions, etc… Any useful points will be compiled and presented below for all to benefit.

Otherwise you can use the dedicated discussion page.

Nothing yet!