Directives

Category.DocumentationToDo?

  • This page needs to be cleaned up for 2.0 release.
  • Where in the source are directives listed, what filename(s) and function(s)?
  • There should be a comprehensive enumeration of directives in documentation, even if some are left undocumented, for now.

Cross Reference:

PmWiki uses the markup sequence (:directive ...:) for a number of directives and text substitutions. Many of these replace the "double-bracket" directives that were used in PmWiki 1.0 and earlier versions. Here's a brief description of each.

(:title text:)

Sets a page's title to be something other than the name of the page. For example, the markup

    (:title Patrick's home page:)

uses "Patrick's home page" as the title of the page in the browser title bar (HTML <title> tag) and the title area of the page ($PageTitle variable). Note that apostrophes and other special characters can be used here.

If we want to allow the user to specify a page's title, yet keep the original WikiWord for the crumbstrail as an unaltered variable in the template, how can this be done? like a subtitle directive instead of title, or some var that retains the title after the title directive alters it.

Use $Name in the template for the breadcrumbs instead of $Title. --Pm?

(:keywords word, ...:)

Sets page keywords in an HTML <meta name='keywords' content='word, ...' /> tag.

(:description A page about ...:)

Sets page description in an HTML <meta name='description' content='A page about...' /> tag.

(:comment This won't be displayed:)

Allows comments to be included in the page markup without them being visible in the displayed page. This may be useful for providing editing guidance to new users, among other uses.

(:include PageName:) and (:include PageName#start#end:)

Includes the contents of another page into the text of the current page. The second form of the include is used to include only the portion of the page between the #start and #end anchors. #start and #end can be numeric, in which case they refer to line numbers within the page, so that (:include RecentChanges#1#10:) grabs only the first ten lines of the RecentChanges? file.
In PmWiki 2, one can specify a range of lines to be used in the
(:include:) directive, thus:

(from Pm email)

(:include SomePage :) - include all of SomePage
(:include SomePage lines=10 :) - include lines 1-10 of SomePage
(:include SomePage lines=1..10 :) - include lines 1-10 of SomePage
(:include SomePage lines=6..10 :) - include lines 6-10 of SomePage
(:include SomePage lines=6.. :) - include lines 6 to end of SomePage
(:include SomePage lines=6..6:) - include only line 6 of SomePage

(:noheader:), (:nofooter:), (:notitle:), (:nogroupheader:), (:nofootheader:), etc.

These directives disable the header, footer, and page title portions of a page's layout (if the page's skin allows it).

(:(no)spacewikiwords:)

Turns on (off) automatic spacing of bare WikiWords within the page text. When on, WikiWord will be displayed as "Wiki Word".

(:(no)linkwikiwords:)

Turns on (off) automatic linking of bare WikiWords to pages of the same name.

(:if cond param:)

The (:if cond param:) syntax allows portions of the markup text to be conditionally processed (up to the next (:if:)) depending on administrator-defined conditions. The predefined conditions are "true", "false", "group", and "name". For example,
(:if group PmWiki:)This text displays only in the PmWiki group(:if:)
For more details, see ConditionalMarkup.

(:pagelist group=xxx fmt=yyy list=zzz:)

The (:pagelist ..:) syntax allows to include a bulleted list of pagenames which are within the specified group. The group and pagenames are displayed as links.

group=xxx
optional, xxx = name of group, which pages should be included in the list

Q: can you specify pages as well, e.g via regex or matching name-prefix: Group\.PREF.* = all pages of group "Group" starting with "PREF"
A: No, just groups and not pages. There may be a new option added at some point that allows specifying fullnames by regex. Plus there's always the list=zzz option below which does allow arbitrary lists.

fmt=yyy
optional, yyy =
bygroup
default, level 1 list entries for each group with level 2 list entries for each page of a group
simple
one line per page, using full pagename: "* groupname.pagename", no group headers
group
list just groups: "* groupname"
see also
Cookbook:DictIndex

list=zzz
optional, zzz =
normal
don't include special pages like RecentChanges, GroupHeader and GroupFooter in the list

You can do
(:pagelist:) to get a list of all pages,
(:pagelist group=PmWiki:) to get a list of all pages in the PmWiki group,
(:pagelist group= -PmWiki -PmWikiDe:) to get a list of all pages except those in the PmWiki and PmWikiDe? group (the blank before the first '-' is mandatory),
(:pagelist group={$Group}:) to get a list of all pages in the current group,
(:pagelist group={$Group} list=normal:) to get a list of all pages in the current group except GroupHeader, GroupFooter, RecentChanges etc.,
(:pagelist fmt=group :) to get a list of all groups,
(:pagelist fmt=group -{$Group} :) to get a list of all groups exept the current one.

from mailings:

For RecentPages, I just put the following in my local/config.php:
(There must be two spaces between the wikilink and the following text -> Copy&Paste from the source, not html view.)

$RCTime = strftime('%b %d %H:%M',$Now);
$RecentChangesFmt['Main.RecentPages'] = ':[[$FullName]]: $RCTime';

(:searchbox:)

Shows a search box at this position.

(:searchresults group=xxx fmt=yyy list=zzz text:)

For usage of group, fmt and list, see the (:pagelist:) directive above.

(:markup:) ... (:markupend:)

Can be used for markup examples, showing first the markup and then the result of the markup. see PmWiki.TextFormattingRules for examples.

<< InterMap | PmWiki.DocumentationIndex | Include other pages? >>