Home of the opto isolated, bus powered, DMX512 interface with both in and out universes. Cheap and simple to build. USBDMX logo

authors, admins (intermediate) PmWiki comes with two directives for generating lists of pages -- (:pagelist:) and (:searchresults:). The primary difference between the two is that searchresults: generates the "Results of search for ..." and "### pages found out of ### searched" messages around the results -- otherwise they're basically the same.

Basic syntax

  • (:pagelist:) without any arguments shows a bulleted list of all pages, as links, ordered alphabetically and in groups.
  • (:pagelist group=abc fmt=def list=ghi order=jkl argument1 argument2 etc:) shows a pagelist according to the parameters supplied. Parameters are optional.


Any argument supplied within (:pagelist:) that isn't in the form 'key=value' is treated as text that either must (or must not) exist in the page text. Thus

    (:pagelist trail=PmWiki.DocumentationIndex list=normal apple -pie:)

lists all "normal" pages listed in the DocumentationIndex trail that contain the word "apple" but not "pie".

group= and name=

The "group=" and "name=" parameters limit results to pages in a specific group or with a specific name:

    # All pages in the Pmwiki group:
    (:pagelist group=PmWiki :)
    # All pages except those in the PmWiki or Site groups:
    (:pagelist group=-PmWiki,-Site :)
    # All RecentChanges pages
    (:pagelist name=RecentChanges :)
    # All pages except RecentChanges
    (:pagelist name=-RecentChanges :)


Name and group parameters can contain wildcard characters that display only pages matching a given pattern:

  • An asterisk (*) represents zero or more characters
  • A question mark represents exactly one character


    # All pages in any group beginning with "PmWiki"
    (:pagelist group=PmWiki* :)
    # All pages in any group beginning with "PmWiki", except for Chinese
    (:pagelist group=PmWiki*,-PmWikiZh* :)
    # All pages in the PmCal group with names starting with "2005":
    (:pagelist name=PmCal.2005* :)


The "trail=" option obtains the list of pages to be displayed from a WikiTrail:

    # Display pages in the documentation by modification time
    (:pagelist trail=PmWiki.DocumentationIndex order=-time:)
    # Display five most recently changed pages
    (:pagelist trail=RecentChanges count=5:)


The "list=" option allows a search to include or exclude pages according to predefined patterns set by the administrator. PmWiki predefines "list=normal", which excludes things like AllRecentChanges, RecentChanges, GroupHeader, GroupFooter, and the like from being displayed in the list results. Wiki administrators can define custom lists via the $SearchPatterns array (see Cookbook:SearchResults).


The "fmt=" option determines how the resulting list should be displayed. PmWiki predefines several formats:

  • fmt=#bygroup - Display pages alphabetically within groups
  • fmt=#simple - Display a simple ordered list of pages
  • fmt=#title - Display a list of pages by page title. Use "order=title" to have them sorted by title (default is to order by page name).
  • fmt=#group - Display the groups of the pages in the list
  • fmt=#include - Display the contents of each page in the list (note, this could take a very long time for long lists!)

Custom pagelist formats can be defined using pagelist templates and referenced by the fmt= option. (PmWiki's default templates are in Site.PageListTemplates.) There are several ways to indicate which template to use:

  • fmt=#custom uses the #custom section from Site.PageListTemplates (sections are denoted by [[#custom]] anchors.
  • fmt=MyTemplatePage#custom uses a custom format from page MyTemplatePage from its #custom section.
  • fmt=custom uses custom format which is defined in a cookbook script as custom.

Cookbook:PagelistTemplateSamples has many examples of custom pagelist formats. In addition, the Cookbook:Cookbook has other recipes for special fmt= options, in cluding fmt=dictindex (alphabetical index) and fmt=forum (forum postings).


The "link=" option implements "backlinks" -- i.e., it returns a list of pages with a link to the target. It's especially useful for category pages and finding related pages.

    # all pages with a link to PmWiki.DocumentationIndex
    (:pagelist link=PmWiki.DocumentationIndex:)
    # all pages with links to the current page
    (:pagelist link={$FullName}:)
    # all pages in the "Skins" category
    (:pagelist link=Category.Skins:)


The "count=" option limits the pagelist to a specific number of pages.

    # A simple bullet list of ten most recently modified pages
    (:pagelist trail=Site.AllRecentChanges count=10 fmt=#simple:)


The "order=" option allows the pages in the list to be sorted according to different criteria. Use a minus sign to indicate a reverse sort. Multiple sorting criteria can be specified using a comma:

  • order=name - alphabetically by name
  • order=-name - reverse alphabetical listing
  • order=title - sorted by title
  • order=-time - most recently changed pages first
  • order=ctime - time of page creation
  • order=size - sort by page size
  • order=group,title - sort by title within groups
  • order=random - shuffle the pages into random sequence


Include the contents of a random page from the Banners group:

    (:pagelist group=Banners order=random count=1 fmt=#include list=normal:)

Display a simple list of the last ten recently changed pages

    (:pagelist trail=Site.AllRecentChanges count=10 fmt=#simple:)

See Also

<< Conditional markup | Documentation Index | Page variables >>