DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:subjectindex

subjectindex plugin

Compatible with DokuWiki

  • 2013-12-08 "Binky" unknown
  • 2013-05-10 "Weatherwax" yes
  • 2012-10-13 "Adora Belle" unknown
  • 2012-01-25 "Angua" unknown

plugin Hierarchical structured tagging: create A-Z subject index pages for your wiki by adding subject entries|tags anywhere in your wiki.

Last updated on
2013-11-21
Provides
Syntax, Action
Repository
Source
Conflicts with
dw2pdf

Similar to tag

Tagged with index, links, navigation, tags

Download and Installation

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

Download and install the plugin using the Plugin Manager using the URL given above. 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:

Overview

“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.

Syntax and Usage

Add a subject index entry1) 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.

All Syntax Options

Add a new index entry, tag or verse

Default Entry Syntax (Section 0 by default)
{{entry>section;headings;display*}} 2)
e.g. {{entry>0;Home/Gardening/Bonsai Trees;Growing Bonsai Trees*}}
Understanding the options:
Syntax Description Example
[section] Which index section to add the entry to (number starting from 0). 0 = default index {{entry>2;...}}
heading(s) The new heading(s) to be created in the index: 1 or more words/phrases separated by ”/” Nature/Butterflies/Monarch
[display] What should be shown on the page, as follows:
User-defined text . . . ;text}}
User-defined text + star(*) . . . ;text*}}
No text '-' (completely hidden) . . . ;-}}
No text '-' but show star(*) . . . ;-*}}
Use entry text + star(*) . . . ;*}}
Use entry text . . . ;}}
Use entry text (default) . . . }}
[..] Optional
Tags Entry Syntax (Section 1)
#tag
e.g. #home, #work #two_words
Tags cannot contain spaces, however you can use the underscore instead (“_”) and it will be replaced by a space when displayed
All international characters are accepted
Tags automatically go into section no. 1
Bible Verse Syntax (Section 2)
1Cor 15:58; Psalms 89:18
If a verse reference is matched it will automatically be added to section no. 2
Bible book abbreviations are also supported.

Adding a Subject Index list to a page

{{subjectindex>abstract;border;cols=?;section=?;proper;title;noAtoZ;default;showorder;showcount;hidejump;regex=?}}
e.g. {{subjectindex>section=1;border=inside;title;cols=3}}
Understanding the various options:
Syntax Description Example Default
abstract Show an snippet of the page content as a tool-tip {{subjectindex>abstract}} no
border Show a border around or inside the index table: options are inside, outside, both, or none border=inside
border=both
none
cols Divide the list into columns. Either column count (no unit ⇒ cols=3) or column width (with unit ⇒ cols=10em). cols=3 1
section Which index section to display (0-9)3) section=1 0
proper Use proper-case for wiki page names and entries {{subjectindex>proper}} no
title Use title (First heading) instead of page name for displaying links {{subjectindex>title}} no
noAtoZ4) Do not show the A-Z main headings: some indexes do not need it (they might be number based for example) {{subjectindex>noAtoZ}}
showorder Show the manually inserted list numbers in the index page. {{subjectindex>showorder}} no
default This page becomes the default target for all index links in this section {{subjectindex>default}} no
showcount Show the number of index links displayed, at the bottom of the table hide
hidejump Hide the jump-to-top symbol at the bottom of the list show
regex Filter the list of index links by a regular expression, for finer control of what is displayed
Great for power users!

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
}}

Understanding How It Works

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.5)
  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.

The finer details of adding entries and tags

  {{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 spaces6). 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 link7)

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

Manually sorting the Subject Index list

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.

Notes on creating a Subject Index list

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…!).
  • noAtoZ : 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)

Complete Example

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.

Prevent Indexing of Page

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.

Configuration

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

subjectindex_display_sep The character(s) used between the entry text parts when displaying ' → '

Discussion

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.

FAQ

Nothing yet!

1) i.e. based on actual content not just the page name
2) You can still use the old syntax too, for backwards compatibility: {{entry>section/heading|display}}
3) see section above in this table
4) noatoz is fine too
5) No need to put them at the bottom of the page…
6) Otherwise the plugin cannot recognise when the tag name has finished and other text has begun
7) the page link will point to the page that is the default target for entries in section 2
plugin/subjectindex.txt · Last modified: 2013/11/22 12:36 by 41.204.96.215