• View
• Edit
• History
• Attach
• Print

All pages of the documentation

Introduction

Basic PmWiki editing rules

The pages on this site are wiki-based pages, which means that pages can be created and edited by multiple authors. To edit a page, click the Edit link that exists somewhere on the page, usually in the header or footer. Some pages may be password-protected, depending on the system's security policies, but many systems allow open editing of pages.

PmWiki is not WYSIWYG - When editing a page, you see the markup text that describes the content of the page. The basic rules for page markup are simple:

1. Use a blank line to start a new paragraph more.
2. To make a list, start each line with # for numbered (ordered) lists or * for bulleted (unordered) lists more.
3. To make a heading, start a line with two or more ! marks; !! is a subheading, and !!! is a sub-subheading more.
4. To emphasize text, enclose it in 2 or 3 single quotes; ''text'' for italics or '''text''' for bold more.
5. To make a link to another page, enclose the page's name in double brackets; for example [[basic editing]] links to this page.
6. To make a link to another site, type its address, such as [[http://example.com/]]. Email links must have "mailto:" before such as mailto:xyz@example.com -> mailto:xyz [snail] example [period] com

If you want to experiment with editing a page, try it on the Wiki Sandbox. You can edit the Wiki Sandbox without affecting anything important on this site. On talk pages and discussions, it's courteous to sign your contribution; using ~~~ effectively 'signs' the name that you provide in the Author field on the Page Edit form.

Examples of common markups

The tables below demonstrate many of the common markups used to format pages. The left column shows what to write to achieve the effect, the right column shows the effect of the markup. More details are available from the text formatting rules and other documentation pages. An exhaustive list of default markup is available as the markup master index.

Paragraphs and line breaks

Consecutive lines
will be merged together
as part of the same paragraph.

One or more empty lines will start a new paragraph.

Two backslashes at the end of a line \\
force a line break.

Or use this markup: [[<<]] to force a break.

Further reading:

• text formatting rules for more information on linebreaks, indented or hanging paragraphs.
• wiki styles for centered or right justified paragraphs and "floating" text (boxes), borders and much more.

Lists

Start each line with # for numbered (ordered) lists or * for bulleted (unordered) lists:

* Bullet list
* Another item
** More asterisks produce sub-items
** etc.

# Numbered lists
# Another item
## more hashes produce sub-items

# List types
# can be mixed
** numbered list with unordered sub-list

Learn more about lists (including definition lists) and list styles.

Headings

Headings are useful for creating a "well-structured" page. They're not just for making big text.

!! Major Subheading
!!! Minor Subheading
!!!! And More
!!!!! Subheadings

Text Emphasis

To emphasize, enclose text in apostrophes (single-quote marks), not double-quotes.

''Emphasize'' (italics),
'''strong''' (bold), 
'''''very strong''''' (bold italics).

Links

To make a link to another page, enclose the page's name in double square brackets.

Practice editing in the [[wiki sandbox]]

Note that words are automatically capitalized in page titles. The link above links to the page WikiSandbox.

Text after a pipe (|) is used as the link text:

Practice editing in the
[[WikiSandbox | practice area]].

Endings become part of the link text, parentheses hide parts of the link name:

[[wiki sandbox]]es.

[[(wiki) sandbox]].

When linking to a page in a different WikiGroup, provide the group name, followed by a separator, and then the page name:

[[Main.Wiki Sandbox]] shows group + name

[[Main/Wiki Sandbox]] shows only name

Links to external sites

bare url:  http://www.pmwiki.org

link text: [[http://www.pmwiki.org | PmWiki home]]

Links as reference to external sites

bare url: http://www.pmwiki.org

link text: [[http://www.pmwiki.org | #]]

Colons make InterMap (also called InterWiki?) links to other wikis:

What's an [[Wikipedia:aardvark]], anyway?

Links to nonexistent pages? are displayed specially, to invite others to create the page.

PmWiki supports more link types and a lot of display options, see Links to learn more.

Preformatted text

Preformatted text is displayed using a monospace font and not generating linebreaks except where explicitly indicated in the markup.

Note that very long lines of preformatted text can cause the whole page to be wide.

For preformatted text with markup (e.g. emphasis) being processed, start each line with a space:

 Lines that begin with a space
 are formatted exactly as typed
 in a '''fixed-width''' font.

 Lines that begin with a space
 are formatted exactly as typed
 in a fixed-width font.

If you don't want Wiki markup to be processed, use [@ @]. Can also be used inline.

[@
Text escaped this way has
the HTML ''code'' style
@]

Text escaped this way has
the HTML ''code'' style

Escape sequence

If you don't want Wiki markup to be processed, but lines reformatted use [= =]. Can also be used inline.

[=
markup is ''not'' processed
but lines are reformatted
=]

Horizontal line

Four or more dashes at
the beginning of a line
----
produce a "horizontal rule"

Tables

Simple tables use double pipe characters to separate cells:

|| border=1
||! head 1 ||! head 2 ||! head 3 ||
|| cell 1  ||  cell 2 ||  cell 3 ||

See simple tables and advanced tables to learn more about the rich feature set of PmWiki tables.

Images

See Images

Character formatting

* @@Monospaced text@@
* Text with '^superscripts^'
* Text with '_subscripts_'
* deleted {-strikethrough-} text
* inserted {+underline+} text
* [+big+], [++bigger++] text
* [-small-], [--smaller--] text

Use WikiStyles to change the text color .

Page titles

The (:title:) directive sets the page's title to something other than its page name.

The name of this page is "{$Name}", and its title is "{$Title}".

Page Description

• The (:Description Page summary here:) directive sets the page description. The description is used by search engines, and can be displayed in search results and in page lists.

The summary description of this page is {$Description}.

CreatingNewPages

The first step to create a new page is to edit an existing page and add a link to the page you want to create.

You can see that the links to my new page? all have question marks after them. That's because my new page? hasn't been written yet. Clicking the link as second step will take you to an edit form where you could write and finally save the new page.

Another way to create a page: in your browser's address bar (where the page URL is), replace the name of the current page with the name of the page you wish to create, and hit Enter or do whatever you would normally do to go to a new location. PmWiki will then dutifully tell you that the page you entered doesn't exist, but you can click on the "Edit" link in order to create, edit, and save the new page.

The drawback to this method is that there are no links to your new page, so you're the only person who knows it exists. It will be an orphan, unread, unlinked, unloved. That's why adding a link to an existing page or to the SideBar is a better way to create a page.

Learn more:

• You can also organize related pages into groups, and link between pages in different groups.

Links

A key feature of wiki-based systems is the ease of creating hyper links (or short links) in the text of a document. PmWiki provides multiple mechanisms for creating such links.

Links to other pages in the wiki

To create an internal link to another page, simply enclose the name of the page inside double square brackets, as in [[wiki sandbox]] or [[installation]]. This results in links to wiki sandbox and installation, respectively.

PmWiki creates a link by using the text inside the double brackets. It does this by removing spaces between the words, and automatically capitalizing the first letter of each word following spaces or other punctuation (like ~). Thus [[Wiki Sandbox]], [[wiki sandbox]], and [[WikiSandbox]] all display differently but create the same link to the page titled WikiSandbox. Or in other words, PmWiki will automatically create the "link path name" using the page name in CamelCase?, but the "link text" will display in the format you have entered it.

Some PmWiki sites (default not) will recognize words written in CamelCase?, called a WikiWord, automatically as a link to a page of the same name.

Links with different link text

There are three ways to get a different link text:

1. Hide link text. Link text within (parentheses) will not be not displayed, so that [[(wiki) sandbox]] links to WikiSandbox but displays as sandbox. For addresses actually containing parentheses, use %28 and %29 http://www.example.com/linkwith%28parenthese%29.
2. Change link text. You can specify another link text after a vertical brace, as in [[WikiSandbox | a play area]], or you can use an arrow (->) to reverse the order of the link text and the target, as in [[a play area -> WikiSandbox]]. Both links displays as a play area.
3. Show page title instead of page name. The use of special characters in the page name is not a problem for PmWiki, but on some servers it may be better to use only plain A-Z letters for the page "name" (which is also a filename), and set the page "title" to the extended or international characters with the (:title PageTitle:) directive within the page. The page title can be shown instead of the page name with the [[PageName|+]] link markup, e.g. page BasicEditing contains the directive (:title Basic PmWiki editing rules:) with the result that a link written as [[BasicEditing|+]] will display as Basic PmWiki editing rules.
   Since PmWiki version 2.2.14 this works also for those technical pages that have an entry in the XLPage?, without the need to add the (:title PageTitleName:) directive within that page (for more details see Localization.Localization).

On top of above ways, a suffix can be added to the end of a link, which becomes part of the link text but not of the target page name.
Note: This feature does currently not work with the [[PageName|+]] markup.

[[(wiki) sandbox]],\\
[[(wiki) sandbox]]es\\
[[WikiSandbox|wiki sandbox]],\\
[[WikiSandbox|wiki sandbox]]es\\
[[BasicEditing|+]]

Links with tool tip

From version 2.2.14 PmWiki can show tooltip titles with the following format:

• External link: [[http://pmwiki.org"tool tip title" | external link ]]
• InterMap link: [[Wikipedia:Wiki"tool tip title"| InterMap link ]]
• Linked image: [[Attach:000962.png"tool tip title" | Attach: link]]
• Inline image: Attach:000962.png"tool tip title"

PmWiki does not support tool tip titles for internal links!

Links to nonexistent pages

Links to nonexistent pages? are displayed specially, to invite others to create the page. See Creating new pages to learn more.

Links to pages in other wiki groups

Links as written above are links between pages of the same group. To create a link to a page in another group, add the name of that other group together with a dot or slash as prefix to the page name. For example, links to Main/WikiSandbox could be written as:

* [[Main.WikiSandbox]]
* [[Main/WikiSandbox]]
* [[(Main.Wiki)Sandbox]]
* [[Main.WikiSandbox | link text]]
* [[Main.WikiSandbox | +]]

To link to the "default home page" of a group, the name of the page can be omitted:

* [[Main.]]
* [[Main/]]

See Wiki Group to learn more about PmWiki groups.

Category links

Categories are a way to organize and find related pages. The idea is that every page that falls into a particular subject area should have a link to a shared page containing links to other pages on that subject. These shared pages are created in the special group Category, and thus these subject areas are called "categories".

Adding a page to the category Subject is simple by adding the [[!Subject]] markup somewhere on that page. This will create a link to the page Category.Subject. So [[!Subject]] is a kind of link shortcut to the page Category.Subject. See Categories to learn more.

User page links

Similar is [[~Author]] a link shortcut to the page Author in the special group Profiles. PmWiki automatically creates this type of link for the current author, when it encounters three tilde characters (~) in a row (~~~) in the page text. The current author is the name found in the "Author" field, when you create or modify a page. The current date and time is appended when four tilde characters in a row are encountered (~~~~).

So, when the Author field contains "Author":
~~~ markup will be replaced by: Author
~~~~ markup will be replaced by: Author October 10, 2010, at 04:50 PM

Link shortcuts

[[PageName|#]] creates a reference link as shown below^[1].

Links to specific locations within a page -- "anchors"

To define a location, or bookmark, within a page to which you may jump directly, use the markup [[#name]]. This creates an "anchor" that uniquely identifies that location in the page. Then to have a link jump directly to that anchor, use one of

• [[#name|link text]] within the same page, or
• [[PageName#name]] or [[PageName#name|link text]] for a location on another page
• The form [[PageName(#name)]] may be useful for hiding the anchor text in a link.

For example, here's a link to the Intermaps section, below.

Notes:

• The anchor itself must begin with a letter, not a number.
• A link to an anchor must have the same capitalization as the anchor itself.
• Spaces are not allowed in an anchor: "[[#my anchor]]" won't work, "[[#myanchor]]" will.
• All anchor names in a page should be unique.

Links to actions

To link to a specific action for the current page use [[{$FullName}?action=actionname|linkname]].

Examples:

• [[{$FullName}?action=edit|Edit]] for editing
• [[{$FullName}?action=diff|differences]] for differences.

Links outside the wiki

Links to external sites (URLs)

Links to external sites simply begin with a prefix such as 'http:', 'ftp:', etc. Thus http://google.com/ and [[http://google.com/]] both link to Google. As with the above, an author can specify the link text by using the vertical brace or arrow syntax, as in [[http://google.com/ | Google]] and [[Google -> http://google.com]].

It is possible to set a "tooltip title" of the external link by adding it in quotes after the address:

[[http://www.pmwiki.org/"Home of PmWiki"|link]]

If the external link includes (parentheses), escape these using %28 for "(" and %29 for ")" :

[[http://en.wikipedia.org/wiki/Wiki_%28disambiguation%29 | link to "Wiki (disambiguation)" ]]

The recipe Cookbook:FixURL makes it easy to encode parentheses and other special characters in link addresses.

Links to intranet (local) files

Not all browsers will follow such links (some Internet Explorer versions reportedly follow them). You can link to a file system by including the prefix 'file:///'. So file:///S:\ProjPlan.mpp and [[Shared S drive->file:///S:\]] are both valid links. On a Windows file system you may want to use network locations (eg \\server1\rootdirectory\subdirectory) rather than drive letters which may not be consistent across all users. Not all browsers will follow such links.

See also Cookbook:DirList.

Link characteristics

Links as References

Links may also be specified as References, so the target appears as an anonymous numeric reference rather than a textual reference. The following markup is provided to produce sequential reference numbering within a PmWiki page:

Formatting the link as: [[http://google.com |#]] produces: [2] as the link.

Subsequent occurrence of the reference link format on the same page will be incremented automatically as per the following example: Entering [[http://pmwiki.com |#]] produces [3], [[#intermaps |#]] produces [4], and so on for further reference links.

Intermaps

Inter Map links are also supported (see Inter Map). In particular, the Path: InterMap entry can be used to create links using relative or absolute paths on the current site (e.g., Path:../../somedir/foo.html or Path:/dir/something.gif).

Links that open a new browser window

To have a link open in another window, use %newwin%...%%:

• %newwin% http://pmichaud.com %% produces http://pmichaud.com
• %newwin% [[http://google.com/ | Google]] %% produces Google
• %newwin% [[Main.WikiSandbox]] %% produces Main.WikiSandbox

You can also specify that links should open in a new window via the %target=_blank%...%% attribute:

The following link %target=_blank% http://pmichaud.com %%
will open in a new window.

Links that are not followed by robots

Prefix a link with %rel=nofollow% to advise robots and link checkers not to follow it.

Links and CSS Classes

PmWiki automatically gives classes to several types of links. Among other things, this enables you to format each type differently.

Note: This may be an incomplete list.

.selflink

A link to the current page. Useful in sidebars to show "you are here".

.wikilink

A link to another page within the wiki.

.urllink

A link to a page outside the wiki.

Notes

Note: The default behavior of "+" above can be overridden to display the spaced title, rather than simply the title by adding the following to config.php:

## [[target |+]] title links
Markup('[[|+', '<[[|',
  "/(?>\\[\\[([^|\\]]+))\\|\\s*\\+\\s*]]/e",
  "Keep(MakeLink(\$pagename, PSS('$1'),
                 PageVar(MakePageName(\$pagename,PSS('$1')), '\$Titlespaced')
                ),'L')");

%newwin% http://example.com/ %%

* mailto:myaddress@example.com
* [[mailto:myaddress@example.com]]
* [[mailto:myaddress@example.com | email me]]
* [[mailto:myaddress@example.com?subject=Some subject | email me]]

[[http://example.com/ | WikiWord]]
[[WikiWord -> http://example.com/]]

(:pagelist link=SomePage list=all:)   -- show all links to SomePage
(:pagelist link={$FullName} list=all:)  -- show all links to the current page

Images

To place an image into a page, enter the address (url) of the image into the markup text. Any alternate text (used for tooltips and for browsers that do not display images) is placed in double quotes immediately following the image url. A caption can follow separated by a vertical bar (|), and may include simple formatting

http://pmichaud.com/img/misc/pc.jpg"Paper clips" | [- %newwin% [[ Wikipedia:Paper_clips | Paper clips ]] are ''fun'' to work with. -]

Paper clips are fun to work with.

Images can also be specified as uploaded files (i.e., Attach:image.jpeg) and using InterMap links. By default PmWiki supports the following image types:

  gif jpg jpeg png

(See also Uploads and Notes below for image files that lack extensions.)

To create a link to an image (like http://pmichaud.com/img/misc/pc.jpg as opposed to displaying the image itself), use double brackets to mark the link, as in [[http://pmichaud.com/img/misc/pc.jpg]] or [[Attach:image.jpeg]].

To have an image link to another location, use the image as the link text as in

[[http://pmwiki.org/ | http://pmichaud.com/img/misc/pc.jpg"PmWiki"]]

or [[http://example.com|Attach:Groupname./image.jpeg]].

Captions

A caption can be added to an image using a vertical bar and the caption text.

http://pmichaud.com/img/misc/pc.jpg"Paper clips" | '''Figure 1'''

Figure 1

Normally, images are displayed "in line" with the surrounding text. Use %center% to center an image. Use %right% to right-align an image.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. %center%http://pmichaud.com/img/misc/pc.jpg"Paper clips"%%

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. %right% http://pmichaud.com/img/misc/gem.jpg%%

Floating images

To left or right-align an image with text wrapping around it, use the %lfloat% or %rfloat% wiki styles.

%lfloat text-align=center margin-top=5px margin-right=25px margin-bottom=5px margin-left=25px% http://pmichaud.com/img/misc/gem.jpg | '''Rock on!''' '''The image is left-aligned, with margins set; the caption is centered; the text wraps on the right side of the image.''' Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Rock on! The image is left-aligned, with margins set; the caption is centered; the text wraps on the right side of the image. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

The [[<<]] markup breaks floating text, and the text continues at the bottom of the image.

%lfloat% http://pmichaud.com/img/misc/gem.jpg '''The image is left-aligned, and the text wraps on the right side of the image. The text after the ''[@[[<<]]@]'' markup continues below the image.''' [[<<]] Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

The image is left-aligned, and the text wraps on the right side of the image. The text after the [[<<]] markup continues below the image. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Use the %lframe% or %rframe% styles to float an image and place a frame around the image and its caption. The frame can be formatted via wikistyles:

%rframe% http://pmichaud.com/img/misc/gem.jpg | '''Rock on!''' '''The image is right-aligned, and the text wraps on the left side of the image.''' Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. %cframe width=100px bgcolor=lightblue border='3px solid red' padding=20px% http://pmichaud.com/img/misc/gem.jpg Example to show failure to fully apply width setting:- %cframe width=50px bgcolor=lightblue border='3px solid red' padding=20px% http://pmichaud.com/img/misc/gem.jpg

Rock on! The image is right-aligned, and the text wraps on the left side of the image. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Example to show failure to fully apply width setting:-

Use %block rframe% to set off multiple images and caption text to be stacked vertically in a right-floating frame.

%block rframe width=300px%http://pmichaud.com/img/misc/gem.jpg\\ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\\\ http://pmichaud.com/img/misc/bubble.jpg\\ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.%% Text subsequent to the defined block wraps to the left of the frame. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Text subsequent to the defined block wraps to the left of the frame. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Resizing images

To resize an image via wikistyles, use %width=50px% or %height=50px% in front of an image. The %thumb% wikistyle is a helpful shortcut for %width=100px%.

%width=50px% http://pmichaud.com/img/misc/bubble.jpg \ %height=50px% http://pmichaud.com/img/misc/bubble.jpg \ %thumb% http://pmichaud.com/img/misc/bubble.jpg

Note: Resizing an image via wikistyles only affects how it is displayed in a browser; it does not reduce the transfer size of the image itself - hence resizing via wikistyles is not an acceptable method of generating a page-full of images, or 'gallery'.

If you want a resized image within a link, you have to specify the size before the link as well as close it off with a %%.

%width=60%[[http://pmwiki.org/ | http://pmichaud.com/img/misc/pc.jpg"PmWiki"]]%% \ %height=60%[[http://pmwiki.org/ | http://pmichaud.com/img/misc/pc.jpg"PmWiki"]]%% \

To open the link in new window, you place %newwin% before the size specification.

%newwin%[[http://pmwiki.org/ | http://pmichaud.com/img/misc/pc.jpg"PmWiki"]]%%

Resized images using %thumb% can also be floated with frames, as well as made into links.

%lframe thumb% [[http://pmichaud.com/img/misc/bubble.jpg | http://pmichaud.com/img/misc/bubble.jpg"Burst the bubble"]] | [-Bubble-] %lframe thumb% http://pmichaud.com/img/misc/pc.jpg"Clip the ticket" | [-Paper Clips-] %lframe thumb% [[DocumentationIndex | http://pmichaud.com/img/misc/gem.jpg"Visit the Documentation Index"]] | [[DocumentationIndex | [-Rock On-]]]

Bubble Paper Clips Rock On

Images as links

To use an image as a link specify an image instead of text in the link markup.

[[PmWiki/Links | http://pmichaud.com/img/2003/atc-1.gif"Information about wiki links"]]

Notes

• An image file that lacks a correct extension can be displayed by addition of a "false" extension to the URL. For example, if the url is http://example.com/script/tux, add a fake query string on the end with the desired extension (e.g., http://example.com/script/tux?format=.png). If query strings are unsuitable, a fragment identifier should work, e.g. http://example.com/script/tux#file.png.
• Relative width is possible by using percentages.

%width=10pct% http://pmichaud.com/img/misc/bubble.jpg \ %height=30pct% http://pmichaud.com/img/misc/bubble.jpg

• Flowing text is possible, like captions, within a frame

>>lframe width=130px<< %thumb width=130% [[http://pmichaud.com/img/misc/bubble.jpg | http://pmichaud.com/img/misc/bubble.jpg"Burst the bubble"]] | [--Long caption for an image like [[http://pmichaud.com/img/misc/bubble.jpg | the bubble]]. This is just to show some text flowing within the frame.--] >><<

Long caption for an image like the bubble. This is just to show some text flowing within the frame.

See also

• Cookbook:Images - adding image galleries, automatic thumbnails, background images and more.

Credits

The images on this page were obtained from http://flickr.com and are redistributed under a Creative Commons License.

DisableMarkup('img');
$ImgExtPattern = "$^";

TextFormattingRules

This page provides a more complete list of some of the markup sequences available in PmWiki. Note that it's easy to create and edit pages without using any of the markups below, but if you ever need them, they're here.

To experiment with the rules, please edit the Wiki Sandbox.

Paragraphs

To create paragraphs, simply enter text. Use a blank line to start a new paragraph.

Words on two lines in a row will wrap and fill as needed (the normal XHTML behavior). To turn off the automatic filling, use the (:linebreaks:) directive above the paragraph.

• Use \ (single backslash) at the end of a line to join the current line to the next one.
• Use \\ (two backslashes) at the end of a line to force a line break.
• Use \\\ (three backslashes) at the end of a line to force 2 line breaks.
• Use [[<<]] to force a line break that will clear floating elements.

Indented Paragraphs (Quotes)

Arrows (->) at the beginning of a paragraph can be used to produce an indented paragraph. More hyphens at the beginning (--->) produce larger indents.

->Four score and seven years ago our fathers placed upon this continent a new nation, conceived in liberty and dedicated to the proposition that all men are created equal.

Inverted Arrows (-<) at the beginning of a paragraph can be used to produce a paragraph with a hanging indent. Adding hyphens at the beginning (---<) causes all the text to indent.

-<Four score and seven years ago our fathers placed upon this continent a new nation, conceived in liberty and dedicated to the proposition that all men are created equal. 

--<Four score and seven years ago our fathers placed upon this continent a new nation, conceived in liberty and dedicated to the proposition that all men are created equal.  And that food would be good too.

Blocks of text to which (:linebreaks:) has been applied can be indented by preceding the first line of the block with indention arrows (->) and aligning subsequent lines under the first. An unindented line stops the block indentation. See Cookbook:Markup Tricks for an example.

Bulleted and Numbered Lists

Bullet lists are made by placing asterisks at the beginning of the line. Numbered lists are made by placing number-signs (#) at the beginning of the line. More asterisks/number-signs increases the level of bullet:

* First-level list item
** Second-level list item
### Order this
#### And this (optional)
### Then this
** Another second-level item
* A first-level item: cooking
## Prepare the experiment
### Unwrap the pop-tart
### Insert the pop-tart into the toaster
## Begin cooking the pop tart
## Stand back

# A list is terminated
by the first line that is not a list.
# Also terminate a list using the escape sequence [@[==]@]
[==]
# Continue a list item by lining
  up the text with leading whitespace.
# Use a forced linebreak \\
  to force a newline in your list item.

## Text between list items can cause numbering to restart
## %item value=3% this can be dealt with

Also see: PmWiki:ListStyles, Cookbook:WikiStylesPlus.

Definition Lists

Definition lists are made by placing colons at the left margin (and between each term and definition):

:term:definition of term

Whitespace Rules

Whitespace indentation in lists. Any line that begins with whitespace and aligns with a previous list item (whether bulleted, numbers or definitional) is considered to be "within" that list item. Text folds and wraps as normal, and the (:linebreaks:) directive is honored.

# First-level item\\
  Whitespace used to continue item on a new line
# Another first-level item
  # Whitespace combined with a single # to create a new item one level deeper

Otherwise, lines that begin with whitespace are treated as preformatted text, using a monospace font and not generating linebreaks except where explicitly indicated in the markup. Note to administrators: Starting with version 2.2.0-beta41, this feature can be modified using $EnableWSPre. (Another way to create preformatted text blocks is by using the [@...@] markup.)

Horizontal Line

Four or more dashes (----) at the beginning of a line produce a horizontal line.

Emphasis and character formatting

• Enclose text in doubled single-quotes (''text''), i.e., two apostrophes, for emphasis (usually italics)
• Enclose text in tripled single-quotes ('''text'''), i.e. three apostrophes, for strong (usually bold)
• Enclose text in five single-quotes ('''''text'''''), or triples within doubles (five apostrophes), for strong emphasis (usually bold italics)
• Enclose text in doubled at-signs (@@text@@) for monospace text
• Use [+large+] for large text, [++larger++] for larger, [-small-] for small text, and [--smaller--] for smaller.
• Emphasis can be used multiple times within a line, but cannot span across markup line boundaries (i.e., you can't put a paragraph break in the middle of bold text).
• '~italic~' and '*bold*' are available if enabled in config.php

Other styling

'+big+', '-small-', '^super^', '_sub_', 

{+insert or underscore+}, 

{-delete or strikethrough or strikeout-}

• `WikiWord WikiWord neutralisation

See also Wiki Styles for advanced text formatting options.

References

• Use words and phrases in double brackets (e.g., [[text formatting rules]]) to create links to other pages on this wiki.
• On some PmWiki installations, capitalized words joined together (e.g., WikiWords) can also be used to make references to other pages without needing the double-brackets.
• Precede URLs with "http:", "ftp:", "gopher:", "mailto:", or "news:" to create links automatically, as in http://www.pmichaud.com/toast.
• URLs ending with .gif, .jpg, or .png are displayed as images in the page
• Links with arbitrary text can be created as either [[target | text]] or [[text -> target]]. Text can be an image URL, in which case the image becomes the link to the remote url or WikiWord.
• Anchor targets within pages (#-links) can be created using [[#target]].

See Links for details.

Headings

Headings are made by placing an exclamation mark (!) at the left margin. More exclamation marks increase the level of heading. For example,

!! Level 2 Heading
!!! Level 3 Heading
!!!! Level 4 Heading
!!!!! Level 5 Heading

Note that level 1 heading is already used as page title (at least in the PmWiki skin), so you should start with level 2 headings to create well formed, search engine optimized web pages.

See Cookbook:Numbered Headers for numbered headings.

Escape sequence

Anything placed between [= and =] is not interpreted by PmWiki, but paragraphs are reformatted. This makes it possible to turn off special formatting interpretations and neutralise WikiWords that are not links (even easier is to use a tick ` in front, like `WikiWord).

For preformatted text blocks, use the [@...@] markup. It does neither reformat paragraphs nor process wiki markup:

[@
Code goes here like [[PmWiki.PmWiki]]
'$CurrentTime $[by] $AuthorLink:  [=$ChangeSummary=]'; #just some code
@]

Code goes here like [[PmWiki.PmWiki]]
'$CurrentTime $[by] $AuthorLink:  [=$ChangeSummary=]'; #just some code

The multiline [@...@] is a block markup, and in order to change the styling of these preformatted text blocks, you need to apply a "block" WikiStyle.

%block blue%[@ 
  The font color of 
  this text is blue
@]

 
  The font color of 
  this text is blue

It is also useful to use [= =] within other wiki structures, as this enables the inclusion of new lines in text values. The example below shows how to include a multi-line value in a hidden form field.

(:input hidden message "[=Line1
Line2=]":)

Comments

(:comment Some information:) can be very kind to subsequent authors, especially around complicated bits of markup.

Special Characters

When creating pages it's common to use commercial trademarks, copyright, umlaut, and other non-keyboard symbols. therefore it's important that you have the means to input these special characters.

ISO Standard codes

PmWiki supports the HTML special character listings by the w3c. W3C Page of Special Character codes ISO standard.

Here are some samples:

©  
¼  ¼
½  ½
®  µ  ¨

Æ  32°  Unïted Stätes  ¶  ¥Yen  PmWiki™

For a nice table with all available special characters, see List of Unicode characters at Wikipedia.

Other ways to do it:

Character Map

Find the "Character Map" utility in your computer's System Tools folder. Click the symbol you're interested in, and note the keystroke information at the bottom of the box. You execute these by holding "Alt" while keying the numbers on the numerical keypad of your keyboard (not the numbers across the top of the board).

Paste

• Use Word or another desktop application to create your text with the special characters that you want. Copy and paste the text to the wiki page you're editing or creating.
• Find an instance of a special character in an online document; copy and paste the character to your wiki page: ©

There's a list of special characters at PmWiki:SpecialCharactersList. There's another illustration at PmWiki:Characters

Tables

Tables are defined by enclosing cells with '||'. A cell with leading and trailing spaces is centered; a cell with leading spaces is right-aligned; all other cells are left-aligned. An empty cell will cause the previous cell to span multiple columns. (There is currently no mechanism for spanning multiple rows.) A line beginning with '||' specifies the table attributes for subsequent tables. A '!' as the first character in a cell provides emphasis that can be used to provide headings.

||border=1 width=50%
||!Table||!Heading||!Example||
||!Left   || Center || Right||
||A       ||!  a B   ||     C||
||        || single ||      ||
||        || multi span   ||||

See Table Directives for advanced tables.

Can't find it here?

See Markup Master Index.

Markup Master Index

This page contains the most frequently used wiki markup, briefly. Follow the links in each section to learn more.

Links

See Links

External links

Page links

See also WikiWord on how to enable WikiWord links.

WikiGroup links

See Links and Categories

InterMap links

See InterMap

Email links

Upload links

See Uploads and Images

Images

See Images and Uploads

Images as Images

Images as links

Start-of-line markup

See Text formatting rules

Lists

See List Styles, Wiki styles and Cookbook:Outline lists

Also

Headings

Paragraph blocks

Division blocks

See Block markup, Wiki styles and Page directives

Text markup

See Text formatting rules

Character format

Posting markup

Tables

Plain rows and columns of text

See Tables

Structured tables

See Table directives

Directives

Page directives

See Page directives

Display

See Page directives Group headers

Metadata

See Page directives, Comment markup, Page variables

Include

See Include other pages, Page text variables

Conditional markup

See Conditional markup

Pagelists

See Page lists

Other directives

See Page directives

Forms

See Forms

See also PmWiki Edit forms.

Wiki trails

See Wiki trails

Page variables

See Page variables, Page text variables, Page lists

Expressions

See Markup expressions

Uploads

PmWiki can be configured to allow authors to upload and store files and images (known as attaching them). These attachments may then be referenced from any page.

Attach: Syntax

To add or link to an attachment, an author edits a page to include the markup "Attach:" followed by a name of an attachment (e.g., "Attach:resume.pdf"). When the page is displayed, the Attach: markup becomes one of the following:

• A link to the named attachment (if uploaded, ie already in the upload directory)
• A link to a form whereby the author can specify a file to be uploaded and used as the new attachment (if not yet uploaded, ie not in the upload directory)
• If the attachment is an image file with an extension such as .gif, .jpeg, or .png, it is displayed as an image.

The behaviour of links can be modified to

• prevent an image attachment from displaying as an image, place it in double brackets (e.g., [[Attach:image.jpg]]).
• have a link to an attachment appear without the "Attach:" at the beginning of the link, use [[(Attach:)file.ext]].

Attachments on other pages and groups

To link to an uploaded attachment (image or file) from another group, you simply refer the group itself (make sure "Groupname" has the dot in it).

If PmWiki is configured with an individual directory per page use

Names with spaces

To link to a filename with spaces in it use the bracket link notation, eg

"Embedding in the page" an image with spaces is not supported: just upload the images with names without spaces, and use the markup Attach:image.jpg.

The following workaround is possible, but is unsupported and not recommended:

International characters in file names

See UploadsAdmin and $UploadNameChars.

Listing Uploaded Files On A Page

To list files that have been uploaded, use the markup: (:attachlist:)

This will list attachments to the current group or page, depending whether attachments are organised per group or per page; each instance includes a link to the attachment for viewing or downloading. A list of attachments is also shown as part of the uploads page form.

Upload Form / Upload Replacement

One can go directly to the upload form by appending "?action=upload" to the URI for any page that has file uploads enabled by the Wiki Administrator. Replace a file by simply uploading a new version of the file with the same name.

• Be sure to clear your browser cache after replacing an upload. Otherwise, it may appear that the original upload is still on the server.

If you put $EnableUploadVersions=1; in your local/config.php, the old versions of the same files are renamed and not removed.

Type and Size Restrictions

For security reasons, the upload feature is disabled when PmWiki is first installed. When enabled uploads are restricted as to the types and sizes of files that may be uploaded to the server (see UploadsAdmin). PmWiki's default configuration limits file sizes to 50 kilobytes and file extensions to common types such as ".gif", ".jpeg", ".doc", ".txt", and ".pdf".

In addition, the administrator can configure the system to require an upload password--see Passwords and PasswordsAdmin.

By default the upload allows the following extensions. Note that by default, no file extension is required.

'gif','jpg','jpeg','png','bmp','ico','wbmp','svg','xcf'        # images

'mp3','au','wav','ogg','flac',                                 # audio
'ogv','mp4','webm','mpg','mpeg','wmf','mov','qt','avi',        # video
'zip','7z','gz','tgz','rpm','hqx','sit',                       # archives
'doc','ppt','xls','mdb',                                       # MSOffice
'exe',                                                         # executables
'pdf','psd', 'ps','ai','eps',                                  # Adobe
'htm','html','css','fla','swf',                                # web stuff
'txt','rtf','tex','dvi',                                       # text files
'odt','ods','odp','odg',                                       # OpenOffice.org 
'epub','kml','kmz',''                                          # misc

Removal

At present uploaded files can only be deleted from the server by the wiki administrator. Any uploads-authorized user may over-write an existing file by uploading another of the same name and extension to the same location.

The administrator may remove an uploaded file by accessing the server via ftp (or via a control panel, if the host offers such a feature). The recipe Cookbook:Attachtable allows the deletion of the files from the wiki.

Tables

Table basics

PmWiki has two types of table markup; the markup described in this page is useful for creating simple tables with lots of small cells, while table directive markups help with larger scale tables. For more possibilities with table formatting see Cookbook:Rowspan in simple tables and Cookbook:Formatting tables.

Tables are created via use of double pipe characters: ||. Lines beginning with this markup denote rows in a table or a formatting line. Within table row lines the double-pipe is used to delimit cells. In the examples below a border is added for illustration (the default is no border).

The first line in the markup contains formatting commands for the table. It only has double pipe characters at the start of the line.

|| border=1
|| cell 1 || cell 2 || cell 3 ||
|| cell 1 || cell 2 ||

Header cells can be created by placing ! as the first character of a cell. Note that these are table headers, not headings, so it doesn't extend to !!, !!!, etc.

|| border=1
||! cell 1 ||! cell 2 ||! cell 3 ||
|| cell 1  ||  cell 2 ||  cell 3 ||

A table can have a caption, indicated by ||!caption!||. Any caption must appear prior to other rows of the table.

|| border=1
||! A special table !||
||! cell 1 ||! cell 2 ||! cell 3 ||
|| cell 1  ||  cell 2 ||  cell 3 ||

Formatting cell contents

Cell contents may be aligned left, centered, or aligned right.

• To left-align contents, place the cell contents next to the leading ||.
• To center contents, add a space before and after the cell contents.
• To right-align contents, place a space before the cell contents and leave the cell contents next to the trailing ||.

|| border=1 width=100%
||!cell 1      ||! cell 2  ||!       cell 3||
||left-aligned || centered || right-aligned||

|| border=1 width=100%
||!cell default||!cell left ||
||default-aligned||left-aligned ||

Note that header and detail cells have different default alignments.

To get a cell to span multiple columns, follow the cell with empty cells. (At present there is no markup for spanning rows.)

|| border=1 width=100%
|| |||| right column ||
|| || middle column ||||
|| left column ||||||
|| left column || middle column || right column ||

Table attributes

Any line that begins with || but doesn't have a closing || sets the table attributes for any tables that follow. These attributes can control the size and position of the table, borders, background color, and cell spacing. (In fact these are just standard HTML attributes that are placed in the <table> tag.)

Use the width= attribute to set a table's width, using either a percentage value, an absolute size, or *.

|| border=1 width=100% 
|| cell 1 || cell 2 || cell 3 ||
|| c1 || cellcellcellcell2 || cell 3 ||

The border= attribute sets the size of a table's borders.

|| border=10 width=70%
||!cell 1      ||! cell 2  ||!       cell 3||
||left-aligned || centered || right-aligned||

|| border=0 width=70%
||!cell 1      ||! cell 2  ||!       cell 3||
||left-aligned || centered || right-aligned||

Use align=center, align=left, and align=right to center, left, or right align a table. Note that align=left and align=right create a floating table, such that text wraps around the table.

|| border=1 align=center width=50%
||!cell 1      ||! cell 2  ||!       cell 3||
||left-aligned || centered || right-aligned||
Notice how text does not wrap with a table using "align=center".

|| border=1 align=left width=50%
||!cell 1      ||! cell 2  ||!       cell 3||
||left-aligned || centered || right-aligned||
Notice how text wraps to the right of a table using "align=left".

|| border=1 align=right width=50%
||!cell 1      ||! cell 2  ||!       cell 3||
||left-aligned || centered || right-aligned||
Notice how text wraps to the left of a table using "align=right".

Note: to get a table to align left (but not "float left") requires CSS, as in

The bgcolor= attribute sets the background color for a table. At present there is no way to specify the color of individual rows or cells in this type of table (but see Cookbook:FormattingTables).

|| border=1 align=center bgcolor=yellow width=70%
||!cell 1    ||! cell 2 ||!     cell 3||
||left-align || center  || right-align||

|| border=1 rules=rows frame=hsides
|| cell 1 || cell 2 || cell 3 ||
|| cell 1 || cell 2 || cell 3 ||

|| border=1 rules=cols frame=vsides
||! cell 1 ||! cell 2 ||! cell 3 ||
|| cell 1  ||  cell 2 ||  cell 3 ||

||border="1" style="border-collapse:collapse" cellpadding="5" width=66%
||!Header ||! Header || '''Header'''||
||cells   ||  with   ||      padding||
||        ||         ||             ||

table.column td.col1 { width: 120px; }
table.column td.col3 { width: 40px; }

Table directives

There are six directives for table processing. All must be at the beginning of a line to have any effect.

(:table [attr...]:)

Generates a new HTML <table> tag with the attributes provided in attr.... Closes the previous table, if any. Valid attributes and values are:

• border (a positive integer)
• bordercolor (a color name or hex number; doesn't display in all browsers)
• cellspacing (a positive integer indicating the space between cells)
• cellpadding (a positive integer indicating the interior border of a cell)
• width (a positive integer or percent)
• bgcolor (a color name or hex number)
• align (left, center or right)
• summary (does not display; used primarily to help visually disabled people navigate)

(:cellnr [attr...]:), (:cell [attr...]:), (:headnr [attr...]:), (:head [attr...]:)

• The (:head:) directive opens a new "header cell" of the table (creates <th> tag in HTML).
• The (:cell:) directive opens a new "regular cell" of the table (creates <td> tag in HTML).
• The directives (:headnr:) and (:cellnr:) open a new cell on a new row in the table.

These directives close any previous cell and/or row. Note, the (:head:) and (:headnr:) directives exist from PmWiki version 2.2.11 or newer.

Valid attributes and values are:

• align (left, center or right)
• valign (top, middle or bottom) * default is "top", see note below
• colspan (a positive integer)
• rowspan (a positive integer)
• bgcolor (a color name or hex number)
• width (a positive integer or percent)
• class (a CSS class of the cell)
• style (custom CSS styles of the cell)

(:tableend:)

Closes the previous table cell and closes off any table. Generates </th>, </td>, </tr>, and </table> tags as needed.

* valign attribute

If not already set, PMWiki will automatically include the attribute valign='top' with all (:cell[nr]:) and (:head[nr]:). Pm said "Table Directives were created for layout purposes and in that case it makes the most sense for each cell (column) to have its content at the top of the row. The attribute is placed in each cell and not in the row because certain browsers didn't recognize valign='top' in the row tag.

Notes

For the table, cell, and cellnr tags the author can specify any attributes that would be valid in the HTML <table> or <td> tags. Thus you can specify rowspan, colspan, etc. arguments to build arbitrary tables. However, it's not possible to nest a (:table:) inside of a (:cell:) or (:cellnr:) -- the next paragraph explains why.

Many are likely to ask why we didn't just use the standard HTML table markup (<table>, <tr>, <td>, <th>) instead of creating a new markup, and allowing nested tables as a result. There are two answers: first, the HTML table markup is very ugly for naive authors (see PmWiki.Audiences and PmWikiPhilosophy #2), and second, it'd be very easy for authors to create tables that are incorrect HTML and that display incorrectly (or not at all) on some browsers. Even seasoned web professionals sometimes get the table markup wrong, so it's a bit unrealistic to expect the average author to always get it right, or to be able to read arbitrary HTML table markup that someone else has created.

It's difficult to write the code needed to make PmWiki understand and fix arbitrary table markup, so PmWiki uses the simplified version above. Still, this version is able to handle most table requirements (with the possible exception of nested tables).

And, this is not to say that nested HTML tables are impossible in PmWiki --they just can't be easily created by wiki authors using the default wiki markup. A site administrator can of course create header/footer HTML code and other local customizations that make use of nested tables.

Example 1. A table using table directive markup.

" " is a non-breaking space in html. Place it in a cell if a cell is to be empty or the border of the cell will not be drawn properly.

(:table border=1 cellpadding=5 cellspacing=0:)
(:head:) a1
(:cell:) b1
(:cell:) c1
(:cell:) d1
(:headnr:) a2
(:cell:) b2
(:cell:) c2
(:cell:)  
(:tableend:)

In HTML, this is the same as

<table border='1' cellpadding='5' cellspacing='0'>
  <tr>
    <th>a1</th>
    <td>b1</td>
    <td>c1</td>
    <td>d1</td>
  </tr>
  <tr>
    <th>a2</th>
    <td>b2</td>
    <td>c2</td>
    <td>&nbsp;</td>
  </tr>
</table>

Floating Table with bulleted navigation list

What if you wanted to create a nice little table like a table of contents in a page like this? In this example, the table is floating right and contains some links in a bulleted list. This is a nice demonstration of how it's possible to build a little table of contents in the page, which might navigate to other pages just within the same wiki group. Note that having a bulleted list won't work in a ordinary table - it only works inside an table created with table directives such as the example code used here.

(:table border=1 width=30% align=right bgcolor=#cccc99 cellspacing=0 :)
(:cellnr:)
'''Navigation Links'''
(:cellnr:)
*[[Tables]]
*[[Table directives]]
(:tableend:)

(:table border=1 width=30% align=right bgcolor=#cccc99 cellspacing=0 :)
(:cellnr colspan=2 align=center:)
'''Navigation Links'''
(:cellnr align=center:)
[[Tables]]
(:cell align=center:)
[[Table directives]]
(:tableend:)

Looking at the markup here, notice that we have used a #cccc99 hex color for the table background. Also, the (:cellnr:) markup creates a new row, a new cell and closes the row at the end.

You could take this concept a little further: since you might want each page in the group to contain the same table of contents, you can make ONE table like the above and put it in its own page. Then use an include on any of your pages and bring in the table. The float (align) property will be honored in each page where it's included.

WikiStyles

WikiStyle basics

WikiStyles allow authors to modify the color and other styling attributes of the contents of a page. A WikiStyle is written using percent-signs, as in %red% or %bgcolor=lightblue%.

WikiStyle attributes

The style attributes recognized within a WikiStyle specification are:

 bgcolor
 background-color
 border1
 color
 background-color
 border
 display
 float
 font-size
 font-family
 font-weight
 font-style

 height*
 list-style
 margin1
 padding1
 text-align
 text-decoration
 white-space
 width* 

 accesskey 
 align
 class
 hspace 
 id 
 target 
 rel 
 vspace 
 value

 Special: define, apply

The attributes in the first two columns correspond to the cascading style sheet (CSS) properties of the same name. The attributes in the last column apply only to specific items:

• class= and id= assign a CSS class or identifier to an HTML element
• target=name opens links that follow in a browser window called "name"
• rel=name in a link identifies the relationship of a target page
• accesskey=x uses 'x' as a shortcut key for the link that follows
• value=9 sets the number of the current ordered list item
  • The width and height attributes have asterisks because they are handled specially for <img .../> tags. If used by themselves (i.e., without anything providing an "apply=" parameter to the WikiStyle), then they set the 'width=' and 'height=' attributes of any <img ... /> tags that follow. Otherwise, they set the 'width:' and 'height:' properties of the element being styled.
  1. margin, padding, and border can be suffixed by -left, -right, -top, and -bottom

WikiStyles versus CSS styles

WikiStyles, as written in the wiki page, are not exactly CSS styles or CSS classes. WikiStyles allow authors to use both pre-defined by the administrator CSS classes, and to define new combinations of styles, without any need to edit/update local CSS files on the server.

Note that PmWiki allows advanced authors to use of class= and style= in tables and division blocks, but these are raw HTML attributes, and not WikiStyles, knowledge of CSS is required to use them.

Text color and font

The most basic use of WikiStyles is to change text attributes such as color, background color, and font. PmWiki defines several WikiStyles for changing the text color to %black%, %white%, %red%, %yellow%, %blue%, %gray%, %silver%, %maroon%, %green%, %navy%, and %purple%.

The basket contains %red% apples, %blue% blueberries, %purple% eggplant, %green% limes, %% and more.

For colors other than the predefined colors, use the %color=...% WikiStyle. (Note: RGB colors (#rrggbb) should always be specified with lowercase letters to avoid WikiWord conflicts.)

I'd like to have some %color=#ff7f00% tangerines%%,  too!

To change the background color, use %bgcolor=...% as a WikiStyle:

This sentence contains %bgcolor=green yellow% yellow text on a green background.

See WikiStyle Colors for more color help.

Text justification

WikiStyles are used to control the text justification

%center% This text is centered. 

%right% Right justified.

and to create floating text:

%rfloat% This text floats to the right

%rframe% floats to the right with a frame

Lorem ipsum dolor sit amet, consectetuer sadipscing elitr

Scope

WikiStyles can also specify a scope; with no scope, the style is applied to any text that follows up to the next WikiStyle specification or the end of the paragraph, whichever comes first. The apply= attribute and its shortcuts allow to change the scope as follows:

Thus, %p color=blue% is the same as %apply=p color=blue%, and %list ROMAN% is the same as %apply=list list-style=upper-roman%.

Some predefined style shortcuts also make use of apply, thus %right% is a shortcut for %text-align=right apply=block%.

Example: Apply a style to a paragraph:

%p bgcolor=#ffeeee% The WikiStyle specification at the beginning of this line applies to the entire paragraph, even if there are %blue% other WikiStyle specifications %% in the middle of the paragraph.

Caveat: An applied WikiStyle will only take effect if it's on the line that starts the thing it's supposed to modify. In other words, a WikiStyle in the third markup line of a paragraph can't change the attributes of the paragraph:

after the first line of the paragraph,
we try to %apply=p color=blue% change color.
This does't work because the style comes after the first line of the paragraph.

However, this %apply=p color=red% paragraph
''will'' be in red because its block style does
occur in the first line of its text.

* Here's a list item
* %list red% Oops, too late to affect the list!

Larger blocks

The >>WikiStyle<< block can be used to apply a WikiStyle to a large block of items. The style is applied until the next >><< is encountered.

>>blue font-style:italic bgcolor=#ffffcc<<
Everything after the above line is styled with blue italic text,

This includes
    preformatted %red%text%%
* lists
-> indented items
>><<

    preformatted text

Note, the (:div style="..." class="...":) directive does not work the same way as >>WikiStyke<<, it can only contain the regular HTML style and class attributes.

HTML "class" and "style" attributes for tables and divisions

WikiStyles are only the commands between %...% percent signs.

Tables, table directives and (:div:) division blocks allow advanced authors to incorporate the HTML/CSS attributes class= and style=. Note that these attributes are not WikiStyles, knowledge of CSS is required to use them.

(:table style="font-style:italic; color:green; border:1px solid blue; background-color:#ffffcc":)
(:cellnr:)
Everything after the above line is styled with green italic text,

This includes
    preformatted text
* lists
-> indented items
(:tableend:)

    preformatted text

Note, the (:div style="..." class="...":) directive does not work the same way as >>style<<, as mentioned above, it can only contain the HTML style and class attributes.

Custom style shortcuts

The define= attribute can be used to assign a shorthand name to any WikiStyle specification. This shorthand name can then be reused in later WikiStyle specifications.

%define=box block bgcolor=#ddddff border="2px dotted blue"%

%box% [@some sort of text@]

%box font-weight=bold color=green% [@some sort of text@]

Predefined style shortcuts

PmWiki defines a number of style shortcuts.

• Text colors: black, white, red, yellow, blue, gray, silver, maroon, green, navy, purple (shortcut for %color=...%)
• Justification: %center% and %right%
• Images and boxes
  • Floating left or right: %rfloat% and %lfloat%
  • Framed items: %frame%, %rframe%, and %lframe%
  • Thumbnail sizing: %thumb%
• Open link in new window: %newwin% (shortcut for %target=_blank%)
• Comments: %comment% (shortcut for %display=none%)
• Ordered lists: %decimal%, %roman%, %ROMAN%, %alpha%, %ALPHA% (see also Cookbook:OutlineLists)

Enabling Styles

Styles not listed above can be enabled by a PmWiki Administrator by modifying the local/config.php file. For instance to enable the "line-height" style attribute add the line

to the local/config.php file.

Defining scope for other HTML elements

You can add additional HTML elements to $WikiStyleApply to apply WikiStyles to other HTML elements. For example to allow styling on table rows, or anchor tags.

To apply styling to anchor tags, place in config.php:

$WikiStyleApply['link'] = 'a';

Then, you can apply a class or style to an anchor link:

%apply=link red%[[PmWiki.WikiStyles | test link]]

Or, to apply an ID attribute to a table row TR, place in config.php:

$WikiStyleApply['row'] = 'tr';

Then, in an advanced table, you can have:

(:cellnr:) %apply=row id=myid bgcolor=pink% cell content

And also in a simple table:

|| border=1
|| %apply=row id=myrowid% 1 || 2 || 3 || 4 ||

Note, the %apply=row...% WikiStyle should be on the same line as (:cellnr:).

Examples

WikiStyle Examples contains a number of examples of ways to use WikiStyles in pages.

Known Issues

• Percents in style definitions (like: %block width=50% %) require the use of "pct" instead of "%". PmWiki will convert the "pct" into "%" so that it becomes valid CSS.
• If you specify multiple values for an attribute, like border="2px solid blue" make sure you place the values in quotes.
• Be sure to use lowercase letters for red-green-blue hex colors, %color=#aa3333% will work, %color=#AA3333% may not.

See Also

• Custom WikiStyles Predefined PmWiki styles & adding custom wiki styles
• PmWiki:List Styles Styles for use in wiki lists
• WikiStylesPlus Lots of useful Wikistyles (rollovers, code blocks, notes, warnings, outlines)

WikiStyleExamples

See also Wiki Styles Plus and Wiki style colors.

PmWiki uses WikiStyles for styling text with color and other attributes. PmWiki 2.0 introduced the ability to control the styling further and to even place styles on blocks.

A style is specified within a pair of %-signs and styles the text that follows, as in:

This text is %color=red% red, %color=blue% blue, %% and normal (black).

There are a wide number of available style properties, borrowed primarily from HTML and CSS. In addition, an author can define a style "shortcut" by using the define= property. For example, to define a style of %red%, one can use:

%define=mystyle color=red%
Here is some %mystyle% red text created using a style shortcut.

Shortcuts can be combined with other styles, including other shortcuts:

%define=lovelyred color=red%
%define=likegrapefruit bgcolor=yellow%

%red% This text is red, %red bgcolor=#ccc% red on a grey background, and %lovelyred likegrapefruit% red on a yellow background.  

So far, this is all basically the same as what was available in PmWiki 1.0. PmWiki 2.0 includes the capability to style blocks, by using the apply= style property. Specifying apply=block in a WikiStyle will cause that style to be applied to the entire block, instead of just the text that follows:

This entire block %apply=block bgcolor=yellow% has a yellow background, even though the `WikiStyle appears in the middle of the line.  %bgcolor=pink% Other inline (non-block) WikiStyles can appear in the middle of the line,%% as before.

This means it's now possible to do right-aligned and centered text:

%block text-align=right% The text of this paragraph is right-aligned. 

%block text-align=center% The text of this paragraph is centered.  

In fact, PmWiki predefines %right% and %center% style shortcuts so that you can do this more simply:

%right% This is right-aligned.

%center% This is centered.

Authors can define their own custom styles:

%define=Pm block bgcolor=#fdf%
%define=goofy center bgcolor=#dfd border='3px dotted green'%
%define=rediguana right bgcolor=#ffffcc border='1px dotted red' padding=5px%
%define=strike text-decoration=line-through%

%Pm% Any text that is on a light purple background is a comment from "Pm".

%goofy% Here's some text from Goofy.

%rediguana% bla bla by rediguana!

%goofy%Hello, I am %strike%upset%% %strike%disheartened%% happy to meet you.

Styles can be applied to almost any kind of block:

* %block bgcolor=yellow% Here is a list item
* Here's another list item

* Here's more of a list

# A new list

In particular, this means that outlines are now possible using the predefined %ROMAN%, %roman%, %ALPHA%, and %alpha% list-block styles. The style has to be specified on the first item in the list (and we may develop an alternate syntax for this sort of ordered list):

# %ROMAN% Top level
## %ALPHA% second-level
## second-level
## second-level
### third-level
### third-level
## second-level
### third-level
#### %alpha% fourth-level
##### %roman% fifth-level
##### fifth-level
#### fourth-level
# top-level
# top-level

Wiki styles can be combined with CSS stylesheets to do this automatically -- see Cookbook:OutlineLists.

Q & A

How do I get a block of preformatted text?

Use something similar to this (assuming you want markup within the block to be interpreted as wiki markup and URIs? to be recognized).

>>white-space=pre<<
This block of text is ''preformatted'', see all   the   white-space
and   linebreaks
are preserved. Links such as [[wiki styles]] etc still work.
>><<

How do I get a block of preformatted text with a colored background and a border?

Use something similar to this (note that wiki markup etc is not recognized within the block):

%block bgcolor=#f0f9ff border='1px solid gray' padding=5px%[@
ip access-list extended example-acl
remark ** This is an example acl **
deny ip any host 10.0.0.1
permit ip any any
@]

ip access-list extended example-acl
remark ** This is an example acl **
deny ip any host 10.0.0.1
permit ip any any

How do I get a block of text (including wiki markup) with a colored background and a border?

>>teal background-color:silver border:'medium dotted green'<<
Hello world
* bullet
# number
>><<

How do I get a block of text (including wiki markup) with a border that is indented on the left and does NOT extend all the way to right? I'm not interested in having later text to the right as would occur with lfloat...

You can use the indent width=50pct wikistyle.

Before indention...
>>frame indent width=50pct<<
Hello world
* bullet
# number
>><<
... after indention!

AccessKeys

Access keys (See also Wikipedia:access keys) are keyboard shortcuts for tasks that would otherwise require a mouse click. They are part of markup that may exist on any webpage. On PmWiki steps have been taken to make it easier to use access keys throughout a site, and to make it possible to adjust key assignments to accommodate different languages and preferences.

Using access keys in different operating systems and browsers

Access keys require you to hold down two or more keys.

• On Windows with Internet Explorer, press ALT + the access key.
• With Firefox, press SHIFT + ALT + the access key.
• On a Macintosh with Firefox, Omniweb, Internet Explorer, press Ctrl + the access key.
  • With Safari (Version 4.0.2) press Ctrl + Option + the access key.
• With Opera press Shift+Esc to enter (or exit) access-key mode.
• With Konqueror, press Ctrl to enter (or exit) access-key mode.
• With Chrome, press SHIFT + ALT + the access key

Exceptions exist for specific browsers, and specific versions. For example,

• Internet Explorer requires that the Enter key be pressed at the end of the sequence for versions 5 and up under Windows, but not under Macintosh (where access keys were not supported until after version 4.5).
• Firefox versions 1.5 and earlier simply use Alt, while Firefox version 2.0 uses Shift+Alt.

Note, in cases of conflicts between the keyboard shortcuts assigned by browsers and access keys assigned by links and other markup on webpages, many browsers, including Mozilla, Netscape and Internet Explorer, allow access keys to override the browser defaults and require a different sequence to continue using overridden browser assignments (typically, by pressing and releasing the Alt key, instead of holding it down).

Access key assignments in this PmWiki installation

The following is a list of the currently defined access keys for built-in actions. Remember that the letters identified below must be used together with the combination listed above (depending on your operating system and browser). Note that some actions do not have a corresponding access key by default.

Note: If the 'Key Value' is the same as the 'Key Name', the access key is currently undefined.

When can these access keys be used

• Access keys ak_view, ak_edit, ak_history, ak_attach, ak_print, ak_backlinks, ak_logout and ak_recentchanges can be used all the time
• Access keys ak_save, ak_saveedit, ak_savedraft, ak_preview, ak_textedit can only be used in edit mode

Following table explains which button is activated by which access key. Note that the Cancel button has no access key.

• Access keys ak_em and ak_strong work only in edit mode and when the GUIbuttons? are enabled in local/config.php.

admins (intermediate)

Customizing access keys

PmWiki uses the same "phrase translation" methods for access key mappings as it does for internationalization. This makes it possible for administrators, skins, language translators, and visitors to all influence the way that specific keys are mapped to actions.

See SitePreferences and Site.Preferences for more information and a template.

Note that some skins (e.g., Lean) don't use the translation mechanism. In this case one must edit the template file itself in order to change the access keys.

By convention, the translation phrases for all of the access key actions start with the characters "ak_", so that the page variable "$[ak_edit]" is replaced by the access key for editing as defined by the current preferences, language, skin default, or site default.

Implementation of access keys

Access keys are implemented in html as optional parameters that can be added to links and many other types of markup.

Example: <a href="http://example.com" accesskey="x">Example</a> would create a link to example.com that could be triggered by clicking on the linked word "example" or using the access key Akey+x. That same action key link could be created in PmWiki markup by typing %accesskey="x"%[[http://example.com|Example]]%%, like this: Example. Try it and see if it works. Note that this AKey?+x access key only works this way on this page, because it is simply a shortcut for accessing the link that exists only on this page.

The list of access key assignments in default PmWiki installations generally work throughout a site because links have been created in PmWiki skins and editing screens that incorporate access key parameters using the access key translation phrases. One location where those links can be viewed is Site.PageActions. That page contains the links that the default PmWiki skin, and many other skins, use to generate links such as "View" "Edit" and "History" that appear on most pages (other than editing screens). Each of the links in that page also has an %accesskey=$[ak_xxx]% declaration in front of it, which enables a specific access key for that link.

PageDirectives

PmWiki uses a number of directives to specify page titles, descriptions, page keywords, and control the display of various components. Keywords are not case sensitive.

(:attachlist:)

(:description text:)

Descriptive text associated with the page. (Generates a <meta name='description' content='...' /> element in the page output.)

(:keywords word1, word2, ...:)

Identifies keywords associated with the page. These are not displayed anywhere, but are useful to help search engines locate the page. (Essentially, this generates a <meta name='keywords' content='...' /> element in the output.)

(:linebreaks:), (:nolinebreaks:)

Honors any newlines in the markup; i.e., text entered on separate lines in the markup will appear as separate lines in the output. Use (:nolinebreaks:) to cause text lines to automatically join again.

(:linkwikiwords:), (:nolinkwikiwords:)

Enables/disables WikiWord links in text. Note, this setting requires WikiWords to be enabled, see $EnableWikiWords. See also $LinkWikiWords.

(:markup:) ... (:markupend:) or (:markup:)[=...=]

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

Options

(:markup class=horiz:) will show the markup side by side instead of one upon the other.

(:markup caption='...':) adds a caption to the markup example.

(:markupend:) is not required when using (:markup:) [=...=].

(:messages:)

Displays messages from PmWiki or recipes, for instance from editing pages.

(:noaction:)

Turns off the section of the skin marked by <!--PageActionFmt?--> thru <!--/PageActionFmt?-->. In the pmwiki skin, this turns off the display of the actions at the top-right of the page (other skins may locate the actions in other locations).

(:nogroupheader:)

(:nogroupfooter:)

Turns off any groupheader or groupfooter for the page. (See GroupHeaders.)

(:noheader:), (:nofooter:)

(:noleft:), (:noright:), (:notitle:)

If supported by the skin, each of these turns off the corresponding portion of the page.

(:redirect PageName:)

Redirects to another wiki page.

(:redirect PageName#anchor:)

Redirects to an anchor within a page

(:redirect PageName status=301 from=name quiet=1:)

Redirects the browser to another page, along with a redirect message. For security reasons this only redirects to other pages within the wiki and does not redirect to external urls. The status= option can be used to return a different HTTP status code as part of the redirect. The from= option limits redirects to occuring only on pages matching the wildcarded name (helpful when (:redirect:) is in another page). The quiet=1 option allows the target page not to display a link back to the original page ($EnableRedirectQuiet variable should be set to 1).

(:spacewikiwords:), (:nospacewikiwords:)

(:title text:)

Sets a page's title to be something other than the page's name. The title text can contain apostrophes and other special characters. If there are multiple titles in a page, the last one encountered wins (see also $EnablePageTitlePriority about how to change it).

(:nl:)

Creates a new line if there isn't one already there. See this thread for more info.

Similar to [[<<]]

IncludeOtherPages

The (:include:) directive makes it possible to insert (or "transclude") the contents of other pages into the current wiki page. All of the include directives below perform a straight text inclusion. In particular, any page links in the included text are assumed to link to pages in the current group if not otherwise qualified.

Syntax

The basic syntax is

• (:include PageName:)

• {Group/PageName$:PTVar}

The full syntax is

• (:include FullName#fromanchor#toanchor lines=12..34 self=0 basepage=abc variable=value :)

Parameters

The directive can have multiple Name parameters with or without anchors, and multiple template variable parameters.

Named pages

You can use the above feature to display an error message if an include fails. Create a page, eg. Site.IncludeFailed containing the error message. You can use any page name. Then, in your include markup, append this page at the end of the page list:

 (:include Page1 Page2 Page3 Site.IncludeFailed:)

A slightly more complex approach is outlined at the talk page.

#From#To anchors

Lines=from..to

Self=

Page text variables

Basepage=

If basepage= is provided all relative links and page variables are interpreted relative to basepage. So, if one creates TemplateName as

Name: {$:Name}
Address: {$:Address}

then the directive

will retrieve the contents of TemplateName, treating any page variables and links as being relative to PageName. In particular, the values for {$:Name} and {$:Address} will be taken from PageName, but things like {$Title} and {$LastModifiedBy} would also work here.

Basepage usage

The primary purpose of basepage is to allow the include of pages in a way that mimics the 2.1.x behavior where page variables and links are interpreted relative to the currently displayed page. This is done with:

  -or-

It also allows GroupHeader and GroupFooter to have their page variables and links be relative to the currently displayed page (instead of GroupHeader and GroupFooter):

  ## PmWiki default $GroupHeaderFmt setting
  $GroupHeaderFmt = 
    '(:include {$Group}.GroupHeader self=0 basepage={*$FullName}:)(:nl:)';

Otherwise, using IncludeAll inside of a GroupHeader would display 'GroupHeader' and not the name of the currently displayed page.

The basepage= parameter is general enough that it can also be used as a templating engine, so that we can grab a template page containing variables that are then filled in with values from another page:

And, of course, a single TemplatePage? can actually contain multiple templates delimited by anchors, so that we end up with a syntax eerily similar^[5] to pagelist-templates:

    (:include TemplatePage#abc basepage=DataPage :)

So then TemplatePage can use a syntax like:

    
    [[#abc]]
    ...template stuff here...
    [[#abcend]]

and it's possible to display TemplatePage as a template without it being interpreted... same as we do for Site.PageListTemplates.

Specifying variables as parameters

You can also specify variable values inline with the include statement, and refer to the variables in the template using the {$$variable1} format:

This assumes that a site has $EnableRelativePageVars enabled, which is recommended in PmWiki 2.2.0 -- but was disabled by default in version 2.2.8 and earlier.

For example, on my included page ("template") I might have this:

[[#ivars]]
Hi, {$$Name}, how are you today?
[[#ivarsend]]

Then, including that section above (that section is available via the section {$FullName}#ivars)) you get this type of behavior:

(:include {$FullName}#ivars Name=Sam:)

If a value contains spaces, quote it:

(:include {$FullName}#ivars Name="my friend":)

See also $EnableUndefinedTemplateVars.

See Also

• Page text variables Page variables automatically made available through natural or explicit page markup
• Cookbook:IncludeUrl Include html pages into PmWiki 2.x pages

Styling Note

By default, Included pages or lines cannot be distinguished from other text on the page. To provide a visual indication that this text is special, you can apply Wiki Styles. For example:

%define=leftborder border-left="2px solid #88f" margin-left="2px" padding="1px 0 3px 10px"%
What is PmWiki?
>>leftborder<< (:include PmWiki.PmWiki lines=1..4:) 
>><<
''Have a very nice day!''

Parameter References

Any parameters supplied to an include statement (whether they are keywords or not) are accessible inside the included page as a special {$$...} variable of the same name. This feature can be used to provide extra information to use when displaying the included page.

Notes

• You can also say (:include My/Page#myanchor lines=4:) which starts from, and includes, the line with the anchor [[#myanchor]] for four lines.

Notes about use with conditional markup

The (:include ...:) markup is processed after conditional markup is evaluated.
Therefor you can include a page or page section as part of a condition, like

But (:include SomePage#section:) doesn't look to see if [[#section]] is part of a conditional, like

(:include SomePage#section:) will ignore such a condition.

When testing variables in included pages the context of the page (source or target) can be useful. See special references for details.

InterMap

The InterMap (also called InterWiki? in some other wikis) is a system for defining links between WikiWikiWeb sites that was first developed by UseMod? and Meatball (see UseMod:InterWiki and Meatball:InterWiki). The method is to use a word shortcut that stands for a defined path. InterMap links have the form MapPrefix:PagePath, where the host prefix is converted to a partial URL based on entries in the site's intermap.txt and localmap.txt files.

The default intermap.txt

The default intermap.txt distributed with PmWiki (in the scripts/ directory) includes the following InterMap entries:

 PmWiki:     http://www.pmwiki.org/wiki/PmWiki/ 
 Cookbook:   http://www.pmwiki.org/wiki/Cookbook/ 
 Wiki:       http://www.c2.com/cgi/wiki? 
 UseMod?:     http://www.usemod.com/cgi-bin/wiki.pl? 
 Meatball:   http://www.usemod.com/cgi-bin/mb.pl? 
 Wikipedia:  http://en.wikipedia.org/wiki/ 
 PITS:       http://www.pmwiki.org/wiki/PITS/ 
 PmL10n?:     http://www.pmwiki.org/wiki/Localization/
 Path:

The page Site.InterMap

Site.InterMap includes the following entries:

 PmWikiHome?:  https://www.pmwiki.org/wiki/
 Category:    https://www.pmwiki.org/wiki/Category/
 MoinMoin?:    https://moinmo.in/
 PmWikiUsers: https://pmichaud.com/pipermail/pmwiki-users/
 RFC:         https://tools.ietf.org/html/rfc

 Wiktionary:  https://en.wiktionary.org/wiki/
 Wikimedia:   https://meta.wikimedia.org/wiki/
 Wikitravel:  https://wikitravel.org/en/
 Wikivoyage:  https://en.wikivoyage.org/wiki/
 Wikiquote:   https://en.wikiquote.org/wiki/
 Wikinews:    https://en.wikinews.org/wiki/
 Wikibooks:   https://en.wikibooks.org/wiki/
 Wikisource:  https://en.wikisource.org/wiki/
 Wikispecies: https://species.wikimedia.org/wiki/
 Wikiversity: https://en.wikiversity.org/wiki/

 DOI:         https://dx.doi.org/$1

Thus, "PmWiki:Variables" becomes "http://www.pmwiki.org/wiki/PmWiki/" + "Variables," a link to the PmWiki.Variables page on the official PmWiki web site, Wiki:FrontPage is a link to the front page of the first WikiWikiWeb, and Wikipedia:Stonehenge takes you to the Wikipedia article about the famous megaliths in England.

Usage in a wiki page

Like other links, you can use the double-bracket syntax to get different link text:

* [[Meatball:StartingPoints | starting points]] over at Meatball
* [[starting points -> Meatball:StartingPoints]] over at Meatball

If you want to link just to what the intermap says (e.g. http://www.wikipedia.com/wiki/ for Wikipedia), then do [[Wikipedia:. | Wikipedia's main page]], which produces Wikipedia's main page. Note the . (period) after the Map: reference.

The special Path: InterMap entry can be used to create "relative urls" in links.

Custom InterMap prefixes

The actual set of InterMap links at any site is defined by the site administrator via the Site.InterMap page and the local/localmap.txt file.

An intermap entry takes the following format:

MapPrefix:      http://example.com/partial/url/

The InterMap entry can be for any of the link schemes supported by PmWiki.
You can create your own InterMap links by doing one or more of the following:

• Modify the page called Site.InterMap and place entries like the ones above in it.
• Create a file called local/localmap.txt and place entries like the ones above in it.
• In a WikiFarm installation you can create a file called local/farmmap.txt and there place entries like the ones above in it. These prefixes will be common to all the wikis in the farm.
• Ensure that there is a space after the colon.

Do not edit the file scripts/intermap.txt directly! If you do, you'll lose your changes when you upgrade PmWiki.

Variables and InterMap links

It's possible to use variables within your InterMap entries. The following entries create ThisWiki: and ThisPage: shortcuts:

ThisWiki:        $ScriptUrl
ThisPage:        {$PageUrl}

You can also define InterMap entries where the text of the entry is substituted into the middle of the URL. Just include '$1' in the URL where you want the substitution to take place. For example:

would cause Jargon:F/feature-creep to be converted to http://catb.org/~esr/jargon/html/F/feature-creep.html.

Tips and tricks

It is possible to document your intermap prefixes directly in the page Site.InterMap. The extra text will not cause a performance penalty, nor will it break the definition of prefixes. However, be aware that anything matching a line starting with a word and a colon (:) will be considered to define a prefix.

The order in which various sources are checked for definitions of prefixes is controlled by the variable $InterMapFiles. Currently the precedence (highest to lowest is as follows):

• local/localmap.txt
• $SiteGroup.InterMap
• $FarmD/local/farmmap.txt
• $FarmD/scripts/intermap.txt

      $LinkFunctions['PmWikiHome:'] = 'LinkIMap';
      $IMap['PmWikiHome:'] = 'http://pmwiki.org/wiki/$1';

ConditionalMarkup

Using the (:if:) Directive

The (:if:) directive allows portions of a page to be included or excluded from rendering. The generic forms of the (:if:) directive are

where "cond" names a condition to be tested, and "param" is a parameter or other argument to the condition.

Note that (:if:) without parameters and (:ifend:) are identical. Also note that (:if cond:) automatically closes a previous conditional. For nested multiple levels, see Nested conditionals.

Built-in Conditions

The built-in conditions include:

The name and group conditionals will work even for an included page, as the "name" and "group" conditionals always check the currently displayed page, as opposed to the page that the markup appears in.

Note: Although there is no built-in conditional markup to test ?action=, you can use (:if equal {$Action} ACTION:) to test what the current action being requested is.

Negated Conditions

Negated forms of conditions also work:

Nesting Conditions

Note that (:if cond:) automatically closes a previous conditional. Thus, the following two examples have identical meaning:

• (:if cond1:) cond1 is true (:if cond2:) cond2 is true (:ifend:)
• (:if cond1:) cond1 is true (:ifend:)(:if cond2:) cond2 is true (:ifend:)

Conditions can be nested from 2.2.beta 66. To have nested conditionals you need to number the if, and the matching else/ifend:

(:if cond1:)
  cond1 is true
  (:if2 cond2:)
     cond1 and cond2 are true
  (:else2:)
     cond1 is true, cond2 is not
  (:if2end:)
(:else:)
  cond1 is false, cond2 testing was ignored
(:ifend:)

Spaces were added for better readability.

Using wildcard placeholders

The character * can be used as a wildcard to represent any character, zero, one, or multiple times.
The character ? can be used as a wildcard to represent any character exactly once.
Wildcard characters (* and ?) can be used with the name and group conditional markups, thus:

Using page text variables, page variables and markup expressions

Page text variables (PTVs?), page variables (PVs?) and markup expressions can be used in conditional markup. They will be assigned/evaluated before the condition(s).

Combining conditions

Conditions (as previously defined) may be combined into more complex conditional expressions using one of these three equivalent forms:

(:if expr EXPRESSION :)
(:if [ EXPRESSION ] :)
(:if ( EXPRESSION ) :)

Conditions are combined into expressions with boolean operators and brackets. In the next table, A and B are either regular conditions or (round-)bracketed sub-expressions of regular conditions:

Example

(:if [ name SomePage and group SomeGroup ]:)    equivalent to (:if name SomeGroup.SomePage:)

Important Notes:

• Spaces are required around operators and brackets.
• No specific feedback is given for syntax errors or unbalanced brackets.
• Use round brackets (not square) for nested expressions.

Thus, the following is a valid way of building an expression that shows the following contents only when the user is either the administrator, or is logged in and the time is later than the given date:

Nesting with square brackets will silently fail to work as expected:

A common use of these complex tests are for expressions like:

which provides a logout link only when the browser has admin, attr, or edit permissions.

admins (advanced)

Creating new conditions

See Cookbook:ConditionalMarkupSamples.

See also special references for the use of {*$Variables}.

Page specific variables

This page describes the "variables" that are associated with pages. Page variables have the form {$variable}, and can be used in page markup or in certain formatting strings in PmWiki. For example, the markup "{$Group}" renders in this page as "Test".

Note: Do not confuse these variables (set and used only in PmWiki pages) with PHP variables. Page variables can be read in PHP with the PageVar() function.

Note that these variables do not necessarily exist in the PHP code, because they have to be determined for a specific page. (However, they are usable in FmtPageName strings.)

There is also the form {pagename$variable}, which returns the value of the variable for another page. For example, "{MarkupMasterIndex$Title}" displays as "Markup Master Index".

Special references

Special referenced variables are used to specify the context of the variable when:

• the variable is included into a destination (target) page
• the variable is used in a sidebar, header, or footer

Prefixing the variable name with an asterisk (*) means the variable's value is related to the target page or main (body) page.

• {*$PageVariablename?} - prefixed by an asterisk (*) - value reflects target page context

Without the asterisk the variable's value is that in the page from which it originates, eg source page of include, sidebar, or header or footer.

• {$PageVariablename?} - retains value in source page context

For example you can test to see if the page is part of another page

(:if ! name {$FullName}:) 
%comment% name of this page is not the same as the page this text was sourced from
->[[{$FullName}#anchor | more ...]]
(:ifend:)

or refer to the main page in a sidebar, footer, or header

This page is [[{*$FullName}]]

Default page variables

The page variables defined for PmWiki are:

In addition to the above, there are some page-invariant variables available through this markup:

Page variable security ($authpage)

The form {pagename$variable} or some PageLists, can display the values for other pages, regardless of the password protections.

If the other pages are protected and the visitor has no read permissions, PageVariables, unlike PageTextVariables, normally display the values. While most variables do not contain sensitive information, some of them could do: $Title, $Description and those starting with $LastModified.

Administrators and module developers can redefine the sensitive page variables to respect authentications, by using the "$authpage" variable instead of "$page" in the definition. The following snippet can be added in local/config.php -- it will rewrite the default possibly sensitive definitions to the secure ones.

foreach($FmtPV as $k=>$v) {
  if(preg_match('/^\\$(Title(spaced)?|LastModified(By|Host|Summary|Time)?|Description)$/', $k))
    $FmtPV[$k] = str_replace('$page', '$authpage', $v);
}

Custom page variables

You may add custom page variables as a local customization. In a local configuration file or a recipe script, use the variable $FmtPV:

$FmtPV['$VarName'] = "'variable definition'";
$FmtPV['$CurrentSkin'] = '$GLOBALS["Skin"]';
$FmtPV['$WikiTitle'] = '$GLOBALS["WikiTitle"]';

Defines new Page Variable of name $CurrentSkin, which can be used in the page with {$CurrentSkin} (also for Conditional markup). It's necessary to use the single quotes nested inside double-quotes as shown above (preferred) or a double-quoted string nested inside single-quotes like '"this"'.

If you want to have a Page Variable that returns the currently used password (more precisely, the last password entered), you can use

$FmtPV['$AuthPw'] = 'reset(array_keys((array)@$_SESSION["authpw"]))';

See also

• Cookbook:More custom page variables
• PmWiki.Variables — about variables internal to PmWiki.
• PmWiki.MarkupMasterIndex — complete list of PmWiki markups.
• PageTextVariables — page variables automatically made available through natural page markup or explicit page markup within the wiki text of the page.
• PmWiki.Markup Expressions — markup expressions can manipulate page variables

# add page variable {$PageCreationDate} in format yyyy-mm-dd
$FmtPV['$PageCreationDate'] = 'strftime("%Y-%m-%d", $page["ctime"])';

 $FmtPV['$Created'] = "strftime(\$GLOBALS['TimeFmt'], \$page['ctime'])";

PageTextVariables

Page text variables are string variables created in the wiki text of a page, and can be automatically made available for inclusion in other pages.

Defining Page Text Variables

There are three ways to define automated Page Text Variables:

• use a definition list - the normal pmwiki markup for a definition list will create a page text variable

:Name: Crisses
"{$:Name}"

• use a simple colon delimiter in normal text

Address: 1313 Mockingbird Lane

"{$:Address}"

• hidden directive form - PmWiki markup that doesn't render on the page, but defines the variable

(:Country: Transylvania :)
"{$:Country}"

Usage

Usage on the same page

On the same page you can resolve page text variables through the {$:Var} format (shown above).

Usage in headers and footers: special references

If you want a GroupHeader, GroupFooter, SideBar, etc to call on page text variable in the main page, you need to include special reference information. To explicitly reference the page text variable from the page being displayed add an asterisk to the page text variable's markup: {*$:Address} on the GroupFooter or GroupHeader page.

{*$:City}

To include a page text variable from a header or footer see usage from other pages below.

Usage from other pages

If you want to pull the data from another page, use the {Group/PageName$:Var} format.

Suburb: Khandallah
(:Lake:Taupo:)
:Mountain:Mt Ruapehu

->"{PmWiki/PageTextVariables$:Suburb}"
->"{{$FullName}$:Lake}"
->"{PmWiki/PageTextVariables$:Mountain}"

Usage from included pages

Page text variables are never included from their source page. See Usage from other pages above to refer to a page text variable on another page.

Usage with pagelists

Page lists can also access the page text variables:

(:pagelist group=PmWiki order=$:Summary count=6 fmt=#singleline:)

And to create pagelist formats (such as those documented at Site.Page List Templates, Page Lists, Page List Templates, Page Variables. Store custom pagelists at Site.Local Templates).

Page lists can also use page text variables to select pages :

(:pagelist group=PmWiki $:City=Paris count=8 fmt=#singleline order=-name:)

(:pagelist group=PmWiki $:City="Addis Ababa,Paris" order=-$:Version count=8 fmt=#singleline:)

• When using page text variables for selection or ordering, don't put the curly braces around the variable name. The curly forms do a replacement before the pagelist command is evaluated.

Testing if set or not set

Tip : (:if ! equal "{$:PTV}" "":) will test if PTV is empty/unset or not.

(:pagelist group=PmWiki $:Summary=-?* count=6  fmt=#singleline:)

Use page text variable in a template

Display pages by Audience page text variable.

>>comment<<
[[#byaudience]]
(:if ! equal '{=$:Audience}' '{<$:Audience}':)
-<'''{=$:Audience}''':  
(:ifend:)
[[{=$Name}]]
[[#byaudienceend]]
>><<
(:pagelist group=PmWiki count=10 fmt=#byaudience order=-$:Audience:)

Use page text variables in conditional markup

Page text variables will be assigned/evaluated before any conditional markup is evaluated. This effectively means that you cannot declare a PTV within an if...else condition; and also that a PTV will have a value even if it is set within a (:if false:)....(:if:) condition.

Usage - from within code (developers only)

The standard PageVar?($pagename,$varname) function can return page text variables, but remember to include the dollar and colon like this:

It works by caching all page (text) variables it finds in a page (in $PCache) and returns the one requested.

MarkupExpressions

The {(...)} "expression markup" allows for a variety of string and formatting operations to be performed from within markup. Operations defined by this recipe include substr, ftime, strlen, rand, toupper / tolower, ucfirst, ucwords, pagename and asspaced.

substr

The "substr" expression extracts portions of a string. The arguments are

1. the string to be processed. Always quote the string to be processed.
2. the initial position of the substring. Note that the initial position argument is zero-based (i.e., the first character is referenced via a "0").
3. the number of characters to extract

 {(substr "PmWiki" 2 3)}
 {(substr "PmWiki" 2)}
 {(substr "PmWiki" 0 1)}
 {(substr "PmWiki" 0 -3)}
 {(substr "PmWiki" -3)}

 Wik
 Wiki
 P
 PmW?
 iki

To obtain the last n characters of a string use {(substr "string" -n)}
To truncate the last n characters of a string use (substr "string" 0 -n)}

ftime

"Ftime" expressions are used for date and time formatting. The generic form is

where fmt is a formatting string and when is the time to be formatted. The arguments can be in either order and may use the optional "fmt=" and "when=" labels.

Examples:

 {(ftime)}
 {(ftime fmt="%F %H:%M")}
 {(ftime %Y)}
 {(ftime fmt=%T)}
 {(ftime when=tomorrow)}
 {(ftime fmt="%Y-%m-%d" yesterday)}
 {(ftime "+1 week" %F)}
 {(ftime fmt=%D "+1 month")}
 {(ftime fmt="%a%e %b" when="next week")}

 November 10, 2024, at 01:30 AM
 2024-11-10 01:30
 2024
 01:30:25
 November 11, 2024, at 12:00 AM
 2024-11-09
 2024-11-17
 12/10/24
 Mon11 Nov

The fmt parameter is whatever is given by "fmt=", the first parameter containing a '%', or else the site's default. The formatting codes are described at http://php.net/strftime. In addition to those, '%F' produces ISO-8601 dates, and '%s' produces Unix timestamps. Some common formatting strings:

     %F                # ISO-8601 dates      "2024-11-10"
     %s                # Unix timestamp      "1731202225"
     %H:%M:%S          # time as hh:mm:ss    "01:30:25"
     %m/%d/%Y          # date as mm/dd/yyyy  "11/10/2024"
     "%A, %B %d, %Y"   # in words            "Sunday, November 10, 2024"

The when parameter understands many different date formats. The when parameter is whatever is given by "when=", or whatever parameter remains after determining the format parameter. Some examples:

    2007-04-11            # ISO-8601 dates
    20070411              # dates without hyphens, slashes, or dots
    2007-03               # months
    @1176304315           # Unix timestamps (seconds since 1-Jan-1970 00:00 UTC)
    now                   # the current time
    today                 # today @ 00:00:00
    yesterday             # yesterday @ 00:00:00
    "next Monday"         # relative dates
    "last Thursday"       # relative dates
    "-3 days"             # three days ago
    "+2 weeks"            # two weeks from now

Note: If you want to convert a Unix timestamp you must prefix with the @. Thus, "{(ftime "%A, %B %d, %Y" @1231116927)}".

The when parameter uses PHP's strtotime function to convert date strings according to the GNU date input formats; as of this writing it only understands English phrases in date specifications.

The variable $FTimeFmt can be used to override the default date format used by the "ftime" function. The default $FTimeFmt is $TimeFmt.

strlen

The "strlen" expression returns the length of a string. The first argument is the string to be measured.

 {(strlen "{$:Summary}")}

 0

rand

The "rand" expression returns a random integer. The first argument is the minimum number to be returned and the second argument is the maximum number to be returned. If called without the optional min, max arguments rand() returns a pseudo-random integer between 0 and RAND_MAX. If you want a random number between 5 and 15 (inclusive), for example, use (rand 5 15).

 {(rand)}
 {(rand 1 99)}

 955165679
 9

toupper / tolower

The "toupper" and "tolower" expressions convert a string into uppercase or lowercase. The first argument is the string to be processed.

 {(toupper "{$:Summary}")}
 {(tolower "{$:Summary}")}

ucfirst / ucwords

The "ucfirst" expression converts to uppercase the first character of the string, and "ucwords", the first character of each word. The first argument is the string to be processed.

 {(ucfirst "{$:Summary}")}
 {(ucwords "{$:Summary}")}

pagename

The "pagename" expression builds a pagename from a string. The first argument is the string to be processed.

 {(pagename "{$:Summary}")}

 Test.

asspaced

The "asspaced" expression formats wikiwords. The first argument is the string to be processed.

 {(asspaced "{$FullName}")}

 Test.Include All

Nesting expressions

Markup expressions can be nested:

 {(tolower (substr "Hello World" 2))}

 llo world

Notes

• For PmWikis? version 2.2.33 or older, the string-processing expressions may not work properly on multibyte UTF-8 characters. Newer versions should work fine.

See also

• Page variables, Page text variables
• Conditional markup
• Cookbook:MarkupExpressionSamples — custom markup expression samples
• Cookbook:MarkupExprPlus

Forms

This page explains how you can embed input forms into wiki pages.

Input forms don't actually handle processing of the form data -- the feature simply allows creation of forms inside wiki pages. Forms processing can be found in the Cookbook (see below).

Markup

Two directives are used to begin and end forms:

    (:input form "url" method:)
    ...
    (:input end:)

The (:input form:) directive starts a form that will post to url (optional action=url) using the supplied method (optional method=method). The url must be in quotes if not specified via action=. If the url is omitted, then the current page is assumed. If method is omitted then "POST" is assumed. An optional name="FormName" argument can be used to name the form. You can explicitly state action=url or method=get or you can simply use them as positional parameters.

If your site uses ?n=Group.Page to specify the pagename then having a field (:input hidden name=n value={$FullName}:) will allow your form to post to the current page as an alternative to fully specifying the action=url.

The (:input end:) directive ends the current form.

Note that this feature doesn't ensure that the form output is correct HTML -- it assumes the author knows a little bit of what he or she is doing. Notably, (:input form:) and (:input end:) shouldn't appear inside tables, and all form fields and controls should be inside an (:input form:)...(:input end:) block.

Standard input controls

The standard input controls are:

    (:input text name value size=n:)
    (:input hidden name value:)
    (:input password name value:)
    (:input radio name value:)
    (:input checkbox name value:)
    (:input select name value label:)
    (:input default default-name default-value:) 
    (:input submit name value:)
    (:input textarea name [=value=] rows=n cols=n:)
    (:input reset name label:)
    (:input file name label:)
    (:input image name "src" alt:)

Where name and value are in the HTML syntax: name="addr" value="808 W Franklin".

For most controls the markup has the form:

    (:input type name value parameter=value:)

where type is the type of input element (described below), name is the name of the control, value is its initial value, and parameters are used to specify additional attributes to the control. If value contains spaces, enclose it in quotes; if it contains newlines (for textarea and hidden elements), enclose it in [=...=].

For example, the following creates a text input control with a size of 30 characters:

(:input text authorid "Jane Doe" size=30:)

For convenience, an author can also specify name and value arguments directly using name= and value= attributes (same as HTML):

(:input text name=authorid value="Jane Doe" size=30:)

For the textarea control a value can be set from PmWiki 2.2.0beta45 onwards. Enclose the value in [=...=] if it contains spaces or new lines.

The submit control will more often be written as:

    (:input submit value=label:)

Here's a more complete example, e.g., for a login prompt:

(:input form "http://www.example.com":)
(:input hidden action login:)
||     Name:||(:input text username:)    ||
|| Password:||(:input password password:)||
|| ||(:input submit value="Log In":) ||
(:input end:)

General form field attributes

• (:input ... focus=1:) Setting focus=1 causes that field to receive the initial focus when the form is first opened.
• The following advanced HTML attributes are supported: name, value, id, class, rows, cols, size, maxlength, action, method, accesskey, tabindex, multiple, checked, disabled, readonly, enctype, src, alt. For a more detailed description, see their counterparts in the w3c reference: HTML forms (not all of them can be used for all types of form fields).

(:input select ... :)

The basic form of a select box is a sequence of options:

(:input form:)
(:input select name=abc value=1 label=alpha :)
(:input select name=abc value=2 label=beta  :)
(:input select name=abc value=3 label=gamma :)
(:input submit:)
(:input end:)

The values can be specified positionally:

 (:input select abc 1 alpha :)

We can specify the size of the selection box:

 (:input select abc 1 alpha size=3 :)

You can specify a multiple select box:

 (:input select abc 1 alpha size=3 multiple:)

To have an element selected, use selected=selected:

 (:input select abc 2 beta selected=selected:)

Note that to have two select boxes inline, not only should you give them different name= parameters, but also place a separator, like a character,   or even the null sequence [==] between them:

(:input form:)
(:input select name=FIRST value=1:)(:input select name=FIRST value=2:)[==]
(:input select name=SECOND value=3:)(:input select name=SECOND value=4:)
(:input end:)

See Also

• Cookbook:Input Default Demonstrates various ways to set the default values for form controls
• Cookbook:Form Validation How to validate forms within wiki pages
• Cookbook:Form Extensions adds fieldset, legend, and label tags to PmWiki forms
• Cookbook:Input Forms and JavaScript Some ideas of combining Javascript with PmWiki Input forms

Compatible recipes:

• Cookbook:PmForm Form processing engine for PmWiki
• Cookbook:Fox Form processor to add, replace, copy, delete content plus upload files and send email notifications using templates and Input markup
• Cookbook:Wiki Forms Use a form template to create, edit and list wiki pages
• Cookbook:ProcessForm Maintain values in fields and make PVs? of the form name/values when a form is submitted

SimultaneousEdits

PmWiki has support for handling the case where multiple authors attempt to edit the same page nearly simultaneously. Here's the basic scenario for systems where simultaneous edits are not handled:

• Alice starts to edit a page.
• Before Alice saves her edits, Bob requests an edit of the same page, and receives the page text prior to Alice's edits.
• Bob finishes with his edits and hits "save".
• Alice finishes editing her page, hits "save", and since she was working from a version of the page from before Bob had made his changes, she wipes out Bob's edits in the process.

PmWiki's simultaneous edit feature detects when this occurs, and instead of saving Alice's edits PmWiki presents Alice with a message that someone else changed the page while she was editing it. Furthermore, Bob's changes are merged into Alice's copy of the page, with any conflicts highlighted by <<<<<<< and >>>>>>>. Alice can then fix things as appropriate and save the updated page, or, if Alice is lazy, she can just hit "save" a second time and leave it to someone else to fix.

The simultaneous edits feature is also invoked whenever someone requests a page preview; thus if a page changes while previewing a page the author gets notification and can see the merged results.

How can I test/experiment with this feature?

1. Open up two browser windows and select the same page to be edited in each window (e.g., try WikiSandbox?action=edit).
2. In one browser window, make some changes to the page and then save those changes.
3. In the second browser window, make some different changes to the same page and hit "save". Since the page changed after the edit form was loaded into the second window, there's a potential edit conflict and you'll receive the "edit conflict message".
4. You can make any adjustments in the second window, and press "Save" again to save the changes.

Notice

Some server environments such as Windows and PHP running in safe_mode are unable to use the simultaneous edits capability distributed with PmWiki. See Cookbook:SimultaneousEdits for a solution for these environments.

WikiStructure

Authors have a range of options to choose from when organizing a collection of wiki pages. Used in combination, these give a lot of flexibility. An effective wiki will use all of these to optimize

• content
• navigation

These are the two most important aspects of a website.

Wiki Word

The most powerful organizing principle is the author's choice of page names. When a search returns a list of pages, their names need to be clear enough to guide a visitor to the right place.

Providing a network of links to other points in the wiki, with or without wiki words, is the primary means of navigating a wiki.

Wiki Page

A page with text (and images), where the text can contain for instance WikiWords that automatically becomes a link to another WikiPage.

Wiki Group

PmWiki requires every page to be a member of a group. A group is like a wiki within a wiki; it can have its own presentation look, security controls and navigation aids. With default configuration, WikiWords are only searched inside the current group, and you use either OtherGroup/MyWikiWord or OtherGroup.MyWikiWord to refer to pages in other groups (see Links).

Wiki Trails

A collection of pages, either in the same group or across multiple groups, can be designated as a trail. A visitor can move from stop to stop by clicking on next and previous links.

Categories

Individual wiki pages can also be grouped by having tags and links to a common "category" page; we say that any pages that link to a common page are in a "category" defined by that page. PmWiki uses the [[!category]] markup as a shorthand to place a page into a category with other pages containing the same markup.

The shortcoming of categories is that categories do not distinguish between the declaration of a category ([[!structure]]) and the link to a category ([[Category/Structure]]).

Page text variables

A newer and more powerful concept than Categories, pages can use one of more page text variables to store page attributes. These can the be used in page lists.

Page lists

Page lists provide a powerful means of presenting lists of relevant pages, or selection of data from within a page. Lists are template based and are highly customizable.

Include other pages

The capability to include parts of other pages also provides a flexible means of sharing content between pages.

Search

Being able to search is a fundamental requirement of a website. In PmWiki search, like pagelists is both powerful and highly customizable.

WikiGroup

PmWiki pages are organized into groups of related pages. This feature was added to PmWiki to allow authors to create their own wiki spaces of specialized content on their own, without having to become, or rely on, wiki administrators. See Pm's post to the pmwiki-users mailing list.

By default, page links are between pages of the same group; to create a link to a page in another group, add the name of the other group and a dot or slash to the page name. For example, links to Main/WikiSandbox could be written as:

* [[Main.WikiSandbox]]
* [[Main/WikiSandbox]]
* [[(Main.Wiki)Sandbox]]
* [[Main.WikiSandbox | link text]]
* [[Main.WikiSandbox | +]]

To link to the default home page of a group, the name of the page can be omitted, like this:

* [[Main.]]
* [[Main/]]

Creating groups

Creating a new group is as easy as creating new pages; simply edit an existing page to include a link to the new group's default home page (or any page in the new group) then click on the '?' to edit the page. As a rule, group names must start with a letter (but this can be changed by the wiki administrator by adding

in config.php).

For example, to make a default page in the group Foo, create a link to [[Foo/]] (or [[Foo.]]). To make a page called Bar in the group Foo, create a link to [[Foo/Bar]] and follow the link to edit that page.

Groups in a standard PmWiki distribution

• Main: The default group. On many wikis, it contains most of the author-contributed content. Main.HomePage and Main.WikiSandbox come pre-installed.
• PmWiki: An edit-protected group that contains PmWiki documentation and help pages.
• Site: Holds a variety of utility and configuration pages used by PmWiki, including
  SideBar, Search, Preferences, Templates, and AllRecentChanges.
• SiteAdmin?: Holds a number of password protected administration and configuration pages used by PmWiki, including
  ApprovedUrls, and Blocklist
• To list all the groups in a site, try searching for "fmt=group".
• To list all the pages in a group, try searching for "GroupName/".

Special Pages in a Group

By default, the Recent Changes page of each group shows only the pages that have changed within that group; the Site.All Recent Changes page shows all pages that have changed in all groups.

Each group can also have Group Header or Group Footer pages that contain text to be automatically prepended or appended to every page in the group. A group can also have a Group Attributes page that defines attributes (read and edit passwords) shared by all pages within the group.

Each page can also have its own individual read/edit password that overrides the group passwords (see Passwords).

Finally, wiki administrators can set local customizations on a per-group basis--see Group Customizations.

Group's default page

The default "start page" for a group is a page whose name is:

1. the same as the group (Foo/Foo)
2. HomePage (HomePage?)
3. a name that the administrator has assigned to the {$DefaultName} variable in the configuration.php file.

Note, on this site, the value of {$DefaultName} is HomePage and, thus, the default home page would be HomePage?.

You can usefully change the default search order for an entered page name by setting the variable $PagePathFmt in config.php, eg

where "$1" is the name of the page entered.

As noted above, when linking to the default home page, authors can omit the page name and simply identify the group followed by a forward slash ([[Foo/]]).

Note the forward slash is required to ensure that the link unambiguously points to the identified group. If the slash is omitted, the link can end up being interpreted as pointing to an existing (or new) page in the current group (if the group, or its default home page, do not exist).

Subgroups? Subpages?

No, PmWiki does not have subpages. Pm's reasons for not having subgroups are described at PmWiki:Hierarchical Groups, but it comes down to not having a good page linking syntax. If you create a link or pagename like [[A.B.C]] PmWiki doesn't think of "B.C" as being in group "A", it instead thinks of "C" as being in group "AB", which is a separate group from "A". Wiki administrators can look at Cookbook:Subgroup Markup and Cookbook:Include With Edit for recipes that may be of some help with developing subgroups or subpages.

Restricting the creation of new groups

You can set PmWiki's $GroupPattern variable to only accept the group names you want to define. For example, to limit pages to the "PmWiki", "Main", "Profiles", and "Example" groups, add the following to local/config.php:

With this setting, only the listed groups will be considered valid WikiGroups. You can add more groups to the list by placing additional group names separated by pipes (|).

See other solutions to this at Cookbook:Limit Wiki Groups and Cookbook:New Group Warning.

GroupHeaders and GroupFooters?

Every WikiGroup can have GroupHeader and GroupFooter pages that contain markup that should be included at the beginning or end of each page within the group. This feature is useful for:

• adding a disclaimer or heading to all of the pages of a group
• defining custom WikiStyles that may be used for all pages in a group
• replacing the default headers and/or footers for pages in a group (e.g., using (:noheader:) and or (:nofooter:) -- see PageDirectives).

To create a group header, just create a new page called YourGroup.GroupHeader. Group headers allow authors to create groups with custom headers and footers without having to coordinate with a wiki administrator.

The default GroupHeader or GroupFooter can be suppressed on an individual page (such as a group's HomePage) by using the (:nogroupheader:) and (:nogroupfooter:) markups on that page.

If a generic GroupHeader is used in one wikigroup (say, the Site wikigroup), then the code can be easily duplicated in the GroupHeader of any other group by using (:include Site.GroupHeader:). See IncludeOtherPages.

If you want a header or footer to appear when you print a page (action print), simply create a page called YourGroup.GroupPrintHeader or YourGroup.GroupPrintFooter and fill it with your markup.

You can also set the variable $GroupPrintHeaderFmt and $GroupPrintFooterFmt in the same way as $GroupHeaderFmt and GroupFooterFmt in order to change the header used when action=print.

See also

• Cookbook:All group header How to create a page that appears as a header (or footer) for all pages in all groups
• Cookbook:Wiki footer

### If you use Site.SiteHeader and Group.GroupHeader
$GroupHeaderFmt = '(:include {$SiteGroup}.SiteHeader'
  . ' basepage={*$FullName}:)(:nl:)' . $GroupHeaderFmt;

### If you use Site.SiteHeader instead of Group.GroupHeader
$GroupHeaderFmt = '(:include {$SiteGroup}.SiteHeader'
  . ' basepage={*$FullName}:)(:nl:)';

### If you use Site.SiteFooter and Group.GroupFooter
$GroupFooterFmt .= '(:nl:)(:include {$SiteGroup}.SiteFooter'
  . ' basepage={*$FullName}:)';

### If you use Site.SiteFooter instead of Group.GroupFooter
$GroupFooterFmt = '(:nl:)(:include {$SiteGroup}.SiteFooter'
  . ' basepage={*$FullName}:)';

WikiTrails

The WikiTrails feature allows wiki authors to create "trails" through sequences of pages in the wiki. You simply specify pages and their order on a "trail index", and then place the navigation markup on the pages that you will be navigating.

(Don't confuse the pagelist directive with WikiTrails - they are different animals as explained in the Q and A below.)

Creating a trail

Before you can use a trail through a group of pages, you have to create a "trail index" on a separate page, which we will call the "trail index page". On that trail index page, you simply create a numbered or bulleted list of links. (So every numbered or bulleted list of links implicitly creates a trail.) It is important that each page name (link) be the first item following each bullet; any text or formatting in front of the page name will exclude it from the trail.
If you want to format your trail (list), you can include a CSS.

An example trail index page might contain the list:

• Installation how to install
• The customisation page
• PmWiki some other text PmWiki Philosophy (The latter won't be in the trail because it is preceded by text)
• Yet some other text. PmWiki.WikiStyles (This won't be in the trail because it follows text)
• Uploads (This won't be in the trail because it is preceded by the %center% style.)
• Some text (This won't be in the trail because it is not a link)
• PageLists Searching and listing pages by multiple criteria with templated output
• http://pmwiki.org (This won't be in the trail because it is not a page link)
  • PmWiki:InterMap (This won't be in the trail because it is an InterMap link)
• Cookbook:Cookbook (This won't be in the trail because it is an InterMap link)

PmWiki philosophy

Design notes (The first link will, and the second link won't, be in the trail defined by (definition list))

• Security (This won't be in the trail because its preceded by a (hidden) anchor)
• Links (This won't be in the trail because its preceded by a (hidden) %newwin% style)
• Troubleshooting (This won't be in the trail because its preceded by (hidden) italic style markup)

The list above creates the following "wikitrail", displayed using a pagelist:

(:pagelist trail={$FullName}#trailstart#trailend fmt={$FullName}#traillist:)

Observations

1. In general, indentation levels in the page list don't matter -- trails are a linear sequence of pages.
2. A page is part of the trail only if the page link immediately follows the list markup.
3. The list itself can be delineated by the use of anchors, allowing for multiple lists on a page, or for some list items to be excluded.

Trail types

PmWiki defines 2 trail markups:

• <<|[[Trail Index Page]]|>> displays as "<< PreviousPage | Trail Index Page | NextPage >>".
• <|[[Trail Index Page]]|> displays as "< PreviousPage | Trail Index Page | NextPage >", except the appropriate arrow is omitted at the beginning and end of the trail.

Trail link syntax

The trail link has the same syntax as a standard link, this means for example you can specify

• <|[[TrailIndexPage | +]]|>

Trail links can be restricted by anchors (links to a specific location within a page), this means you can have more than one trail on a page, or start a trail from a specific location in a page.

• <|[[Trail Index Page#trailstart#trailend]]|>

Using the trail

What makes a trail "work" is adding trail markup on the pages in the trail (i.e. the pages that are listed in the bullet/numbered list on the trail index page).

To build a trail, add trail markup like <<|[[TrailIndexPage]]|>> to a page, where TrailIndexPage is the page, described above, containing the bulleted list of pages in the trail. PmWiki will display the trail markup with links to any previous and next pages in the trail.

The trail markup can be placed anywhere in a page, and a page can contain multiple trail markups. If you are adding a trail to every page in a group, consider setting the trail markup in the GroupHeader or GroupFooter pages instead of on every individual page in your group.

Path trail

^|[[TrailIndexPage]]|^ treats the list levels as a hierarchy and displays the "path" to reach the current page (i.e., a "breadcrumb" trail). In the example trail above, the markup ^|TrailIndexPage|^ on TrailPage4 would display as "TrailIndexPage | TrailPage2 | TrailPage4".

Wiki administrators can change the trail separator of the "path" trail ( ^|[[TrailIndexPage]]|^ ) from the default | by setting the variable $TrailPathSep in the config.php file. For instance $TrailPathSep = ' > '; will output "TrailIndexPage > TrailPage2 > TrailPage4".

Circular trails

Typically, a trail is a linear list with a first and a last page. However, the trail can be made "circular" by repeating the first page as the last item in the trail index:

 * [[TrailPage1]]
 * [[TrailPage2]]
 ...
 * [[TrailPageN]]
 * [[TrailPage1]]

If the trail index page is intended to be read by others, the last item can be made invisible inside an (:if false:) block:

 * [[TrailPage1]]
 * [[TrailPage2]]
 ...
 * [[TrailPageN]]
 (:if false:)
 * [[TrailPage1]]
 (:ifend:)

Cross Group Trails

Before version 2.2.1, if your trail contains pages in different groups, it should use full [[Group.Name]] links instead of just [[Name]].

Other notes

• There is no space between and [[link]] and ; same for the other trail markups.
• Note that non-existing pages will appear in the WikiTrail as links.

Trail style

PmWiki encapsulates the trail with a wikitrail css class. This allows the wiki trail to be customised by defining CSS for the wikitrail in the local.css file.

Trail in page lists

Trails from a single page can only be displayed using the pagelist trail parameter. For example

(:pagelist trail=PmWiki/WikiTrails fmt=PmWiki.WikiTrails#traillist order=random count=3:)

A simple example of a WikiTrail

1) On the TrailIndexPage?:

* [[MyTrailPage1]]
* [[MyTrailPage2]]
* [[MyTrailPage3]]

2) On the pages MyTrailPage1?, 2, and 3:

<<|[[TrailIndexPage]]|>>

Questions

PageHistory

When PmWiki is called with '?action=diff', it displays a summary of past edits on a page. Each past edit is shown in a box which shows lines added, changed or deleted during that edit in a before & after format.

Below each box is a "Restore" link. Clicking the link will open an edit box with the page as it was before that edit. You can make changes or simply click Save to restore the text.

There are two additional options specific to PageHistory:

• Hide minor edits - hides any edit that the author marked as 'minor'. - This is done by adding "&minor=n" to "?action=diff". The default value for this is to show minor edits with "&minor=y"
• Show changes to output - It shows changes to the rendered output (as opposed to the normal display which shows changes to the wiki-markup). This is done by adding "&source=n" to "?action=diff". You can show changes to markup (the default behavior from 2.2.13) with "&source=y".
• You can set both by using "?action=diff&source=y&minor=y".

In the default mode "Show changes to markup", you can disable word-level highlighting of differences by adding to config.php such a line:

  $EnableDiffInline = 0;

A page's history is kept for the number of days given by the $DiffKeepDays and $DiffKeepNum variables (set by the site's wiki administrator). When a page is edited, any page history information older than both these values is automatically discarded.

Note that a specific page revision isn't removed from the page until the first edit after the time specified by $DiffKeepDays has elapsed. Thus, it's still possible for some pages to have revisions older than $DiffKeepDays -- such revisions will be removed the next time those pages are edited.

See also

• Cookbook:ExpireDiff
• Cookbook:LimitDiffsPerPage
• Cookbook:ViewDiff
• Cookbook:TrackChanges

Passwords

PmWiki has built-in support for password-protecting various areas of the wiki site. Authors generally want to be able to apply passwords to individual pages or to wiki groups. Wiki Administrators can apply passwords to individual pages, to wiki groups, or to the entire site. Setting an edit password on a page or group (or the entire site) is one of the most common ways to stop spam. As with any access control system, the password protection mechanisms described here are only a small part of overall system and wiki security.

As an author editing pages...

An author will generally set 3 types of passwords:

1. to control who can see a page or group, use read passwords
2. to control who can edit a page or group, use edit passwords
3. to control who can alter the passwords used to protect a page or group, use attr passwords

If required most page actions can be password protected.

Protect an individual page

To set a password on an individual wiki page, add the page action

to the page's URL (address) to access its attributes. Using the form on the attributes page, you can set or clear the read, edit, or attr passwords on the page. In the form you enter the passwords as cleartext; PmWiki encrypts them for you automatically when it stores them.

Additional options:

• Leaving a field blank will leave the attribute unchanged.
• To remove a password from a page (reverting back to the group's or site's default), enter

• To indicate that the page can be edited even if a group or site password is set, enter

• To lock a page for everybody but the admin, enter

• To assign the site's site-wide passwords to the read, edit, or attr password for the page, enter

Protect a wiki group of pages

To set a password on a wiki group is slightly more difficult -- you just set the passwords on a special page in each group called

First, you can get to the attributes page for GroupAttributes by entering a URL (address) like

Replace example.com with your domain name, and GroupName? with the name of the group

Then, using the form on the attributes page, you can set or clear the read, edit, or attr passwords for the entire group. In the form you enter the passwords as cleartext; PmWiki encrypts them for you automatically.

Additional options:

• To remove a password from a group (reverting back to the site's default), enter

• To indicate that the group can be edited even if a site password is set, enter

• To lock a group for everybody but the admin, enter

• (Beginning with Ver 2.2.3) To assign the site's site-wide passwords to the read, edit, or attr password for the group, enter

Passwords

Passwords may consist of any combination of characters, except double "quotes" or 'apostrophes'. Passwords with spaces or colons must be entered using quotes, eg "foo bar" or "foo:bar". Obviously longer is better, and on some systems passwords need to have 4 or more characters.

Multiple passwords

Multiple passwords for a page, group or site are allowed. Simply enter multiple passwords separated by a space. This allows you to have a read password, a write password, and have the write password allow read/write access. In other words, if the read password is

and the edit password is

then enter

Set new read password: alpha beta
Set new edit password: beta

This says that either

or

can be used to read pages, but only

may edit. Since PmWiki checks the passwords you've entered since the browser has been opened, entering a read password that is also a write password allows both reading and writing.

Protect the site

Passwords can be applied to the entire wiki website in config.php. See passwords administration for details.

administrator

As an administrator ...

You can set passwords on pages and groups exactly as described above for authors. You can also:

1. set site-wide passwords for pages and groups that do not have passwords
2. use attr passwords to control who is able to set passwords on pages
3. use upload passwords to control access to the file upload capabilities (if uploads are enabled)
4. use an admin password to override the passwords set for any individual page or group
5. use SiteAdmin.AuthList to view the permissions settings for pages that have permissions set.

For more information on password options available to administrators, see PasswordsAdmin.

Which password wins?

In PmWiki, page passwords override group passwords, group passwords override the default passwords, and the admin password overrides all passwords. This gives a great deal of flexibility in controlling access to wiki pages in PmWiki.

The special page SiteAdmin.AuthList is a page list of all pages with access permissions set.

Opening access to pages in protected groups/sites

Sometimes we want to "unprotect" pages in a group or site that is otherwise protected. In these cases, the special password

is used to indicate that access should be allowed to a page without requiring a password.

For example, suppose Main.GroupAttributes has an edit password set, thus restricting the editing of all pages in Main. Now we want Main.WikiSandbox to be editable without a password. Using

for the edit password for Main.WikiSandbox doesn't unprotect the page, because the password is being set by the group. Instead, we set the edit password for Main.WikiSandbox to the special value

which tells PmWiki to ignore any site-wide or group-level passwords for that page.

    $DefaultPasswords['edit'] = crypt('edit_password');

    $group = FmtPageName('$Group', $pagename); 
    $DefaultPasswords['edit'] = 'id:'.$group; 
    include_once("$FarmD/scripts/authuser.php");

    session_name('XYZSESSID');

    session_name('CS559SESSID?');

Categories

Purpose of categories

Categories (also known as "tags") are a way to organize and find related pages. Categories are implemented by default in PmWiki 2, and in most wikis they don't require any special code or markup, they're just a useful convention. The idea is that every page that falls into a particular subject area should have a link to a shared page containing links to other pages on that subject. These pages are created in the Category group, and thus these subject areas are called "categories".

Using categories

Getting categories to work requires a single step: adding links to each category. A category named Subject is created by adding a link to Category.Subject on any page. When you add the link to a page, the page can be described as being in the category "Subject".

There is a special markup for creating these links which makes categories work more smoothly: [[!Subject]] will create a link to Category.Subject. So [[!Subject]] is a kind of shortcut to the page Subject in the category group.

A Category.GroupFooter file is included in the PmWiki release that contains the line (:pagelist link={*$FullName} list=normal:) so that whenever a category page is displayed, it will show a list of links to pages that reference that page in the category group. Like any other page in wikilib.d you can modify this page and it will not get overwritten by another release.

It is worth noting that rather than using Category.GroupFooter, the pagelist directive can be added to Category.GroupHeader to similar effect; it just depends on whether you'd prefer to have the list of pages appear before or after any text that you add to the individual category pages (which can be edited just like normal pages).

Because we use the normal PageList link= markup, you can use it not only in the category group. If you want to show all pages belonging to the category Subject you can use on any wiki page (:pagelist link=Category.Subject list=normal:).

Similarly, there's no requirement that a "category page" has to be in the Category group -- any page can define a "category" of pages that link to it.

An administrator can override the default category group name of "Category" by setting the $CategoryGroup variable in config.php to another group name. (Normally a change such as this should be done during initial setup on a new wiki; changing this on a wiki with existing content can cause problems with pagelists unless each page with a category is re-saved.)

A page author can also link to a category list without adding the linking page to the category by using [[ {Category.Subject$PageUrl} | Subject ]]. This will create a link that looks like [[!Subject]] without adding the linking page to the category listing.

Recap

So, by adding the link [[!Subject]] to a page, a link to that page will automatically appear on the page Category.Subject, as long as Category.GroupFooter has been tweaked appropriately. Thus, you can create a page that automatically creates an alphabetized list of all movies discussed on your wiki by creating links to [[!Movies]] on each film's page; the resulting automatic list would be on the page Category.Movies .

authors (advanced)

Category nesting

Categories have the potential for even greater usefulness because Category.* pages can themselves be placed into categories! To follow an excellent example from John Rankin, let's suppose we have the following film pages in the categories listed to the right:

Film.ShaunOfTheDead   [[!Horror]] [[!Comedy]] [[!2003]]
Film.InMyFathersDen   [[!Drama]] [[!2004]]
Film.TheCorporation   [[!Documentary]] [[!2003]]

Now then, we can create Category.Horror, Category.Comedy, Category.Drama, and Category.Documentary, and in each one of those pages we put [[!Genre]]. In Category.2003 and Category.2004, we put [[!Year]].

So, what happens when we display Category.Genre ? We see links to "Comedy", "Drama", "Documentary", and "Horror", because they're in the Genre category. When we click on one of those links, we see all of the films listed in one of those categories. Similarly, if we click on Category.Year, we see links to "2003" and "2004", each of which in turn displays the list of films for that year.

Finally, in Category.Genre and Category.Year we can put [[!Category]], which makes them "top-level" categories reachable from the Category.Category page. Voila, we now have an instant "hierarchy":

Category.Category
    Category.Genre
        Category.Comedy
            Film.ShaunOfTheDead
        Category.Drama
            Film.InMyFathersDen
        Category.Documentary
            Film.TheCorporation
        Category.Horror
            Film.ShaunOfTheDead
    Category.Year
        Category.2003
            Film.ShaunOfTheDead
            Film.TheCorporation
        Category.2004
            Film.InMyFathersDen

Note however that this isn't a "strict" hierarchy--i.e., any page or category can appear simultaneously in multiple categories. For example, Category.Documentary could be a member of both the Genre and top-level category listings.

Each category page can have content text before the generated list, e.g., to give a generic description of things in the category. (Or it can be empty, which works fine.) It can also contain associations to related categories ("see also" references). For example, in a tourism wiki, the ''bed and breakfast" category might contain a see-also reference to the "self-catering" category.

administrators (intermediate)

The guts of the category markup

As mentioned, all of the necessary markup features for Categories are enabled by default in current releases of PmWiki 2.0, but here's how they work for those who are interested. The use of the Category group as the repository for all categories is determined by setting the $CategoryGroup variable, and the special [[!Subject]] markup is activated by a call to the Markup() function:

SDV($CategoryGroup,'Category');
Markup('[[!','<links','/\[\[!([^\|\]] ?)\]\]/',
  "<span class='category'>[[$CategoryGroup/$1]]</span>");

Coming up with good category schemes

The hard part about using categories is choosing a good vocabulary. Site content managers may wish to follow the Guidelines for the establishment and development of monolingual thesauri (ISO 2788-1986) and the Guidelines for the establishment and development of multilingual thesauri (ISO 5964-1985). Questions to think about include:

• whether a scheme already exists and can be reused
• number of levels in a multilevel scheme (not too shallow, not too deep -- e.g. 3)
• number of categories per page (not too many, not too few -- e.g. 3)
• consistent use of singular ([[Mercury]] is a [[!planet]]) or plural ([[Mercury]] is in the [[!planets]] category)
• disambiguation and use of phrases ([[!musical instruments]] and [[!medical instruments]]) or Cookbook:Subpage Markup ([[!Instruments*Musical]] and [[!Instruments*Medical]])

Or you can just let people use whatever category terms they find meaningful. A vocabulary (or "folksonomy") will emerge over time.

Showing a list of categories

To show a list of categories we can use a pagelist for the pages in the category group. For instance the following will list pages in the Category group, put it on page Category.Category for convenience, or on any other page:

But there is a problem: Just adding a category markup to a page will not create a corresponding category page, even though following the link will show the page with a list of pages linking to it!
To have category pages automatically created in group 'Category' add the following to config.php:

Change 'Category' to the name of your category group. You can also add more definitions for more category groups, useful if you use a recipe like Cookbook:Tagger which allows multiple category groups.

See also EditVariables#AutoCreate

PageLists

PmWiki comes with two directives for generating lists of pages -- (:pagelist:) and (:searchresults:). Both directives are basically the same and each accepts the parameters documented below. 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.

The (:searchbox:) directive generates a search form (input text box) to submit search queries. The markup generally accepts the same parameters as (:pagelist:), which makes it possible to restrict, order and format searchresults in the same ways that are described below for a (:pagelist:). For more information about the (:searchbox:) directive, and the ways in which it differs from a (:pagelist:), skip to the section below.

Basic syntax

• (:pagelist:)

• (:pagelist group=ab name=cd fmt=template list=ef order=gh count=123 link=ij trail=kl wrap=mn passwd=op if=qr $:ptv=st $pv=uv cache=0 argument1 -argument2 etc variable=value class=class request=1 req=1 :)

• (:searchbox value=abc size=99 target=def label="label":)
• (:searchresults:)

Parameters

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.

The minus sign (-) can be used to indicate things that should be excluded. Thus

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

With page text variables

You can also use page text variables as a key to list pages according to the existence of a page text variable. Eg :

lists pages having $:pagetextvar set to avalue.
Minus sign (-), wildcards (?*) and a comma separated list of values also works when specifying a selection based on pagetextvariables. Eg :

lists pages having $:apagetextvar like 't*' but not 'test'.
Examples:

Be aware that if using (:pagelist $:MyPTV=$:YourPTV :) PTVs? include PmWiki formatting, so you may not get the matches you expect. Currently the only way around this is to use wild cards, so if the formatting is embedded you may be out of luck.

With page variables (PV)

Page variables can be used within pagelists in the same way as page text variables. See Page Text Variables above for more details. Simply use $var instead of $:var.

group= and name=

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

Wildcards

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

Examples:

(:pagelist group=Cookbook name=A*,B*   :)
(:pagelist group=Cookbook name="A* B*" :)
(:pagelist group=Cookbook name=[AB]*   :)
(:pagelist group=Cookbook, name=[AB]*   :)

If you want to use multiples conditions in name you need to use quotes or commas to delimit the string.

trail=

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

• Display pages in the documentation by modification time

• Display five most recently changed pages

list=

The "list=" option allows a search to include or exclude pages according to predefined patterns set by the administrator.

• "list=normal" is predefined, and which excludes things like AllRecentChanges?, RecentChanges, GroupHeader, GroupFooter, GroupAttributes, and the like from being displayed in the list results. Note that list=normal also excludes the current page.
• "list=all" over-rides a "default" list that may be set by the wiki's administrator to exclude groups such as PmWiki or Site from regular search results.
• Wiki administrators can define custom lists via the $SearchPatterns array (see Cookbook:SearchResults).

fmt=

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

• fmt=#bygroup - Display pages within groups (default format)
• fmt=#simple - Display a simple ordered list of pages in the form Group.Name
• 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 a list of wikigroups (without listing the pages in the groups)
• fmt=#include - Display the contents of each page in the list (note, this could take a very long time for long lists!)

These formats are defined by page list templates, which can be customized.

This format is not predefined by a page list template:

• fmt=count - Display the number of pages in the list (note the absence of the "#"). In a trail, fmt=count counts existing and non-existing pages ; to limit count to existing pages, use : if="exists {=$FullName}" fmt=count (mailing list).

link=

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

• all pages with links to the current page

• all pages in the "Skins" category

count=

The "count=" option provides the ability to

• limit the pagelist to a specific number of pages
• subsets of a list
• return items from the end of a list, subsets of a list
• display pages in reverse sequence

count=1..10       # first ten pages of list
count=5..10       # 5th through 10th pages of list

count=10..        # skip first ten pages
count=..10        # 1st through 10th page of list
count=-10..       # last ten pages of list
count=..-10       # all but the last nine pages

count=5..10       # 5th through 10th pages of list
count=10..5       # same as 5..10 but in reverse sequence
count=-1..1       # all pages in reverse sequence

(:pagelist order=-name count=10:)
(:pagelist order=-name count=1..10:)
(:pagelist order=name count=-1..-10:) 

wrap=

The "wrap" option has the values, none and inline.

With "wrap=inline" and "wrap=none", the output from pagelist (markup or HTML) is directly embedded in a page's markup without any surrounding <div> class=...</div> tags.

With "wrap=inline", any surrounding <ul> is continued. Without "wrap=inline", the HTML output starts a new <ul>. This is important if you want to get a second level <ul> produced by the page list since starting a new <ul> with "**" doesn't yield a second level <ul> but <dl><dd><ul>...

"wrap=inline" likely has other effects since it suppresses the call to $FPLTemplateMarkupFunction (being MarkupToHTML? by default).

class=

By default, a pagelist has the 'fpltemplate' class. The 'bygroup', 'simple', 'group' and 'title' page list formats have specific class names fplbygroup, fplsimple etc. You can set any class using the class= parameter or by setting the $FPLFormatOpt array.

request=1

With (:pagelist [other parameters] request=1:) you can override most pagelist parameters, by providing request parameters in the URL. For example, (:pagelist order=name request=1:) will normally sort the list by name. But if the page's URL contains ?order=time, the list will be sorted by time. If the URL contains ?order=, the list will be unordered.

req=1

The req=1 parameter makes the pagelist execute only when the search terms are posted (that is, when the user presses "search" on a search form). Note that (:pagelist request=1 req=1:) works mostly like (:searchresults:) without the lines "Results of search for ..." and "X pages found out of Y pages searched". Both "request=1" and "req=1" are needed.

passwd=

The "passwd" option returns only those pages that have some sort of password attribute on them.

if=

The "if" option allows a condition to be specified as part of the pagelist processing, rather than from within the page list template. Only those pages for which the condition is true are retrieved. Anything that could go within an (:if ...:) can be used as a condition. For example

  (:pagelist if="date {(ftime %GW%V {*$Name})} {=$Name}" :)

returns all of the pages where the name is in the same week as that of the current page.

If any arguments within the quotes could contain a space they must be quoted:

  (:pagelist if="date 2009-01-01..2009-12-31 '{=$:Mydate}'" :)

order=

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, and you can create your own custom pagelist sort order:

• order=name - alphabetically by name (default order)
• order=title - alphabetically by title rather than names
• order=time - most recently changed pages last
• order=ctime - time of page creation (see note)
• order=group,title - by multiple criteria, in this instance sort by title within groups
• order=random - shuffle the pages into random sequence
• order=$:pagetextvarname - alphabetically by page text variable value
• order=$pagevarname - alphabetically by page variable value

Also, the order= option allows custom ordering functions to be written.

• Note: trail= preserves the order of the pages as they appear on the trail (unless you've specified order= explicitly or there is a default order in the page list template). So PmWiki's alphabetical default order does not apply when trail= is specified.
• Note: ctime was added to pages only from pmwiki 2.1.beta15 onwards, pages created by earlier versions don't carry a ctime attribute and can't be sorted that way.

cache=0

Pagelist has the capability to cache lists which greatly speeds up processing (when $PageListCacheDir is set). Every once in a while this caching can result in undesired results. Specifying cache=0 disables caching.

Specifying variables as parameters

You can also specify variable values inline with the pagelist statement, and refer to the variables in the template using the {$$variable1} format:

This assumes that a site has $EnableRelativePageVars enabled, which is recommended in PmWiki 2.2.0 -- but disabled by default to help people upgrading from 2.1.x.

For example, in the template:

>>comment<<
[[#tvars]]
(:template default count=1 ParamName=Simon:)
Hi, {$$ParamName}, how are you today?
[[#tvarsend]]
>><<

This gives:

(:pagelist fmt=#tvars ParamName="Sam":)

(:pagelist fmt=#tvars ParamName="Sally":)

(:pagelist fmt=#tvars:)

See also $EnableUndefinedTemplateVars.

Examples

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

Display a simple list of the last ten recently changed pages:

Display the "top twenty" biggest cookbook pages:

The Searchbox Directive

The (:searchbox:) directive generally accepts the same parameters as (:pagelist:) and (:input text:) directives:

• Pagelist parameters can be added to the input text of a searchbox (or to the markup, or both)
• Input text box parameters can be added to the searchbox markup
  • An initial search string can be specified in the searchbox markup, but it must be in the form value='search string'. That search string is displayed in the input text and can be modified by when the search is run.
  • The size of the text input field can be specified with the size parameter, where "size=40" would specify the current default value.
    • Tip: If more than one searchbox appears on a page, adding a blank initial value like this value='', to the markup for each searchbox will prevent a search string for one box from populating all of the other boxes.
• The target page for displaying searchbox results can be set with the parameter target=GroupName.PageName?. The default is the current page.
• The entire searchbox form can be overridden by defining the $SearchBoxFmt variable in one's configuration file. If $SearchBoxFmt is defined, then the parameters to (:searchbox:) are ignored, and the content of the $SearchBoxFmt variable are used instead.

The additional parameter label="Label" can be used to change the label of the associated submit button:

 (:searchbox label="Search this wiki":)

The Searchresults directive

The (:searchresults:) directive generally accepts the same parameters as (:pagelist:) and (:input text:) directives.

Customizing "Results of search for..." and "3 pages found out of..."

To change the text surrounding the search results, customize the following and add it to local/config.php or $FarmD/local/farmconfig.php. Note that 'en' should be changed to the localized language.

XLSDV('en', array(
        'SearchFor' => 'Results of search for <em>$Needle</em>:',
        'SearchFound' => 
                '$MatchCount pages found out of $MatchSearched pages searched.'
));

Alternatively, adjust the 'SearchFor?' and 'SearchFound?' phrases in your translation pages.

The $SearchResultsFmt variable can also be set in local/config.php or $FarmD/local/farmconfig.php.

SDV($SearchResultsFmt, "<div class='wikisearch'>\$[SearchFor]
  <div class='vspace'></div>\$MatchList
  <div class='vspace'></div>\$[SearchFound]</div>");

See Also

• PageDirectives#attachlist - display a list of attachments
• Site.PageListTemplates - default pmwiki pagelist templates
• Cookbook:PagelistTemplateSamples - contributed pagelist template samples
• PageListTemplates - how to create custom pagelist templates for the fmt= option
• PagelistVariables - local/config.php customizations
• Cookbook:Forms - documentation for (:input text:) markup, which applies to (:searchbox:)
• CustomPagelistSortOrder - creating custom order sort functions
• Cookbook:CustomPagelistSortOrderFunctions - Custom functions for creating custom page sort orders with pagelists
• Cookbook:SearchResults - How to change the way search results are displayed
• PageDirectives#attachlist display a list of attachments
• PmWiki.Search - Simple test of search

DeletingPages

To delete a page, edit the page, select (highlight) all text in the edit textarea and replace it with the single word

Note that it may be a good idea to add a comment to the field summary explaining why you deleted the page. (The field summary is usually found just below the edit textarea).

After saving the changes the page is deleted. As an added safety feature, the deleted page still exists on the server (with a timestamp) and can be restored to the former page by the wiki administrator.

If you suspect that a page has been deleted but aren't sure, have a look at the wikigroup's RecentChanges. Erasing a page counts as editing the page, and the activity is recorded there and on Site.AllRecentChanges.

The default word used for page deletion ("delete") can be changed in config.php by setting the variable $DeleteKeyPattern (see Edit Variables). If there is a danger of malicious page deletion it may be a good idea to change the delete word to something more obscure. There is also a recipe for creating a separate delete action at Cookbook:DeleteAction.

Removing deleted pages

The deleted pages are kept in the wiki.d directory, with an extension of ,del-123456789 where 123456789 is a unique number (timestamp). A wiki administrator may log into the server via FTP or SSH and periodically remove these files.