Table of Contents

catlist Plugin

Compatible with DokuWiki

  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes
  • 2014-09-29 "Hrun" yes

plugin List pages and namespaces recursively in nested lists

Last updated on
2017-09-28
Provides
Syntax

:!: 20/05/2017 : If the configuration option fnencode is set to safe and you encounter white page/errors when logged out on pages where catlist is used, please email-me, there is a workaround :!:

Description

This plugin lists pages and namespaces recursively as a multilevelled list. You can exclude pages, namespaces and their elements with regex. There are multiple options to personalize headlines and links. Elements can be sorted and put in columns. New pages can be quickly created in a given namespace with Add page... buttons.

Screenshots

Example page here.
On the right, another example sidebar using Bootstrap, visible here.

Example using columns:

Syntax

Legend: [needed], (optional)

<catlist (namespace:) -option1 -option2...>

If namespace is not provided, the namespace of current page is used by default.
Relative (.:ns) and parent (ns1:..:ns2) namespaces can be used.

Options

Display options
[Default] -displayList Display with <ul> and <li>. Render is like on the first screenshots above.
-displayLine Display pages and namespaces into a single line. The content of namespaces are warped with [ and ]. Warning there is some display bugs with it.
-noNSInBold Don't display namespaces and head in bold (with <strong>)
-columns:[0-∞] Split the list into a certain number of columns. Uses the modern CSS features column-count. [Default 0]
Exclude options (can be used multiple time)
-exclude:{page1 ns1: page2 …} Exclude a list of pages/namespaces based on exact ids relative to the listed namespace (: cannot be ignored on namespaces id). Not implemented yet.
-exclupage(:“regex”) Exclude pages that match with regex if provided; otherwise exclude all pages
-excluns(:“regex”) Exclude namespaces that match with regex if provided; otherwise exclude all namespaces
-exclunsall(:“regex”) Exclude all content of subnamespaces that match with regex if provided; otherwise don't show content of subnamespaces
-exclunspages(:“regex”) Exclude pages of subnamespaces that match with regex if provided; otherwise exclude all pages of subnamespaces
-exclunsns(:“regex”) Exclude subnamespaces of subnamespaces that match with regex if provided; otherwise exclude all subnamespaces of subnamespaces
Note : don't add delimiters to regex, the delimiter is /
[Default] -excludeOnID Exclusion based on page IDs (namespace:subnamespace:page)
-excludeOnName Exclusion based on name, without namespaces (page)
-excludeOnTitle Exclusion based on the first title of the page (The Page)
-maxDepth:depth Don't recurse deeper than depth
Headline
-noHead Don't display headline
-smallHead Display headline into a simple <span>, not into a title
-noLinkStartHead Don't add link to the start page of listed namespace
-h[1-5] Display headline into a title of the specified level [Default -h1]
-titleHead:“Title Replace startpage title of listed namespace by specified Title
Namespace heads
-noNSHeadTitle Don't use the title of start pages for namespace heads. Imply -nsLinks:none.
-nsLinks:
none|auto|force
Namespace links : disable, automatically detect the start page, or force links even if the start page doesn't exist. ACLs always prevails. [Default auto]
Create page buttons options (takes into account user rights)
-noAddPageButton Don't display Add page… button for listed namespace
-addPageButtonEach Display Add page… button for each namespace
Default : shows an Add page… button only for listed namespace. If you want Add page… buttons only for subnamespaces, use both options.
Sort options
-sortAscending Ascending Sort (alphabetically, by ID)
-sortDescending Descending Sort

Global options

default_sort Default sort order. none (filesystem sorting, by default), ascending, descending
nocache Disable the cache on pages where catlist is used
hide_index Don't show index pages, namely pages which are used as main page (title and link) for a namespace in catlist. Enabled by default.
index_priority Priority order of pages used as index pages. Combination of start, inside and outside. [Default start,outside]
Example with the namespace foo:bar::
startfoo:bar:<start>
outsidefoo:bar
insidefoo:bar:bar

To illustrate index_priority : if DokuWiki internal link would use index_priority, the default value would be start,inside,outside.

It is recommended to use the nocache global option or to add the NOCACHE directive if Add page… buttons are used, in order to force rescan of the namespace after creating a page.

Tips

You want to exclude all page in listed namespace (mynamespace) except mypage1 and mypage2 but you don't want to exclude pages in subnamespaces. It's a little bit hard in regex… I will simplify things like this but in the meantime, here is the solution :

-excluPage:"mynamespace:[^:]*(?<!mypage1|mypage2)$"

You can stylize the columns of the -columns: option by a small CSS code :

<html><style>
	.catlist_columns {
		-webkit-column-rule: 1px solid #BBB;
		   -moz-column-rule: 1px solid #BBB;
		        column-rule: 1px solid #BBB;
	}
</style></html>

Here are the CSS classes you can use to modify the appearance :

Installation

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Alternatively, install from these links

Development

Change Log

Git repo : http://satanas.net.xif.fr:1234/gitw/?p=catlist.git (rarely reachable)

Known Bugs and Issues

ToDo/Wish List

Languages

Discussion

Please send me an e-mail at xcodexif [at] xif [dot] fr