What is PmWiki?

PmWiki is a wiki-based system for collaborative creation and maintenance of websites. See PmWiki.

What can I do with it?

PmWiki pages look and act like normal web pages, except they have an "Edit" link that makes it easy to modify existing pages and add new pages into the website, using basic editing rules. You do not need to know or use any HTML or CSS. Page editing can be left open to the public or restricted to small groups of authors. Feel free to experiment with the Text Formatting Rules in the "Wiki sandbox". The website you're currently viewing is built and maintained with PmWiki.

What are the requirements?

See the PmWiki requirements page.

Where can I find documentation?

See the documentation index page.

How can I download PmWiki?

See the download page.

How do I install PmWiki?

Instructions for installation are on the installation page.

How do I get help with PmWiki?

See Mailing lists and How to get assistance.

How do you pronounce "Michaud"?

"Michaud" is french pronounced "mee show", the trailing D is silent.

I'm new to PmWiki, where can I find some basic help for getting started?

The Basic Editing page is a good start. From there, you can just follow the navigational links at the top or the bottom of the page (they are called Wiki Trails) to the next pages, or to the Documentation Index page, which provides an outline style index of essential documentation pages, organized from basic to advanced.

How do I include special characters such as Copyright (©) and Trademark (® or ™) on my wiki pages?

See special characters on how to insert special characters that don't appear on your keyboard.

How can I preserve line-breaks from the source text?

PmWiki normally treats consecutive lines of text as being a paragraph, and merges and wraps lines together on output. This is consistent with most other wiki packages. An author can use the (:linebreaks:) directive to cause the following lines of markup text in the page to be kept as separate lines in the output. Or a wiki administrator can set in config.php $HTMLPNewline = '<br/>'; to force literal new lines for the whole site.

Can I just enter HTML directly?

By default (and by design), PmWiki does not support the use of HTML elements in the editable markup for wiki pages. There are a number of reasons for this described in the PmWiki Philosophy and Audiences. Enabling HTML markup within wiki pages in a collaborative environment may exclude some potential authors from being able to edit pages, and pose a number of display and security issues. However, a site administrator can use the Cookbook:Enable HTML recipe to enable the use of HTML markup directly in pages.

Where can I find more documentation?

See the documentation index and the markup master index pages.

How do I create a link that will open as a new window?

Use the %newwin% wikistyle, as in:

%newwin% https://example.com/ %%

How do I create a link that will open a new window, and configure that new window?

This requires javascript. See Cookbook:PopupWindow.

How do I place a mailing address in a page?

Use the mailto: markup, as in one of the following:

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

The markup [[mailto:me@example.com?cc=someoneelse@example.com&bcc=else@example.com&subject=Pre-set Subject&body=Pre-set body | display text]] lets you specify more parameters like the message body and more recipients (may not work in all browsers and e-mail clients).

See also Cookbook:DeObMail for information on protecting email addresses from spammers.

How can I enable links to other protocols, such as nntp:, ssh:, xmpp:, etc?

See Cookbook:Add Url schemes

How do I make a WikiWord link to an external page instead of a WikiPage?

Use link markup. There are two formats:

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

How do I find all of the pages that link to another page (i.e., backlinks)?

In the wiki search form, use link=Group.Page to find all pages linking to Group.Page.

Use the link= option of the (:pagelist:) directive, as in

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

Note that (with a few exceptions) includes, conditionals, pagelists, searchresults, wikitrails, and redirects are not evaluated for Wikilinks, and so any links they put on the page will not be found as backlinks. All other directives and markup, for example links brought to the page by (:pmform:), will be found.

What link schemes does PmWiki support?

See PmWiki:Link schemes

How do I open external links in a new window or mark them with an icon?

See Cookbook:External links

How can I use an image as a link?

Use [[Page| Attach:image.jpg ]] or [[ https://site | https://site/image.jpg ]] See Images#links

Why my browser does not follow local file:// links?

For security reasons, most browsers will only enable file:// links if the page containing the link is itself on the local drive. In other words, most browsers do not allow links to file:// from pages that were fetched using https:// such as in a PmWiki site. See also Cookbook:DirList for a workaround.

How links to the first existed page ? for example [[Group1.Page Group2.Page|Page]]

See ConditionalMarkup

(:if exists Group1.Page:)
   [[Group1.Page|Page]]
(:elseif exists Group2.Page:)
   [[Group2.Page|Page]]
(:ifend:)

How do I make Reference links also show up on the bottom of the page like Wikipedia? Or, how do I list all links on a page?

See Cookbook:Footnotes.

When I upload a file, how do I make the link look like "file.doc" instead of "Attach:file.doc Δ"?

Use parentheses, as in [[(Attach:)file.doc]]. There is also a configuration change that can eliminate the Attach: -- see Cookbook:AttachLinks.

Why can't I upload files of size more than 50kB to my newly installed PmWiki?

Out of the box PmWiki limits the size of files to be uploaded to 50kB. Add

Why does my upload exit unexpectedly with "Incomplete file received"?

You may be running out of space in a 'scratch' area, used either by PmWiki or by PHP. On *nix, check that you have sufficient free space in /tmp and /var/tmp.

How do I make it so that the upload link still allows one to make another upload (if someone wants to replace the old version of a file with a newer version, for example). Currently you only get the upload link when there is no file in the upload directory.

Use the Attach page action, and click on the delta symbol (Δ) shown against each of files listed. If you can't see the attach action either uploads are not enabled, you are not authorized to upload, or the attach action has been commented out or is missing. See also available actions.

How do I hide the "Attach:" for all attachments

See Cookbook:AttachLinks, note that this does not currently work for [[Attach:my file.ext]] .

How can I link a file that have a 4-letter file extension such like 'abc.pptx'?

See Cookbook:Upload Types

How can I prevent others from using the url's of my images on their site

See Cookbook:Prevent Hotlinking

How can I display a file that lacks a correct extension? (e.g. you are using Cookbook:LinkIcons)

A file can be displayed by addition of a "false" extension to the URL. For example, if the url is https://example.com/dox/mydoc, add a fake query string on the end with the desired extension (e.g., https://example.com/dox/mydoc?format=.docx). If query strings are unsuitable, a fragment identifier should work, e.g. https://example.com/dox/mydoc#.docx.

How do I create a basic table?

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

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

How do I create cell headers?

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 rules=cols frame=vsides
||! cell 1 ||! cell 2 ||! cell 3 ||
|| cell 1  ||  cell 2 ||  cell 3 ||

How do I obtain a table with thin lines and more distance to the content?

"Thin lines" is tricky and browser dependent, but the following works for Firefox and IE (Nov. 2009):

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

How do I create an advanced table?

See table directives

My tables are by default centered. When I try to use '||align=left' they don't align left as expected.

Use ||style="margin-left:0px;" instead.

How can I specify the width of columns?

You can define the widths via custom styles, see Cookbook:FormattingTables and $TableCellAttrFmt. Add in config.php : $TableCellAttrFmt = 'class=col$TableCellCount';

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

How can I display a double pipe "||" in cell text using basic table markup?

Escape it with [=||=] to display || unchanged.

How do I apply styles to the elements of the table, like an ID to the table row, or a class/style to the TD?

See $WikiStyleApply.

Alternately, use table directives, which allow specifying styling either directly (style="...") or by a class="..." attribute for CSS.

Is there a simple way to change the table defaults? I prefer a border and I'm tired of adding it to every table.

You can set $SimpleTableDefaultClassName = 'simpletable'; and/or define your own styles in your stylesheet. The "simpletable" class is available in the core skins, and can be redefined or overridden in pub/css/local.css.

Can I define table headers using the table directive markup?

Yes, use (:head:) or (:headnr:) with PmWiki version 2.2.11 or newer. See also Cookbook:AdvancedTableDirectives.

Is it possible to do nested tables?

Yes, if you nest simple tables inside advanced tables. See also Cookbook:AdvancedTableDirectives.

Is it possible to add background images to tables and table cells?

Yes, see Cookbook:BackgroundImages.

Is it possible to apply styles to the elements of the table, like an ID to the table row, or a class/style to the TD?

Yes, see $WikiStyleApply.

Is it possible to automatically generate columns or rows in tables, i.e. without having to do a lot of counting?

Yes, this is possible with the Cookbook:CreateColumns recipe - it allows you to specify a certain number of columns, and/or to specify a certain number of items per column. Plus, someone has provided some similar markup on the TableDirectives-Talk page.

Is it possible to use table captions in table directives similar to simple tables? Tried ! Captiontext ! and (:caption:) . Didn#t work. How to do?

Yes, this is possible with the Cookbook:AdvancedTableDirectives recipe - There you will find a (:caption:) directive.

How can I change the keyboard shortcuts for editing and saving a page?

See Customizing access keys.

Can I get (:redirect:) to return a "moved permanently" (HTTP 301) status code?

Use (:redirect PageName status=301:).

Is there any way to prevent the "redirected from" message from showing at the top of the target page when I use (:redirect:)?

From version 2.2.1 on, set in config.php $EnableRedirectQuiet=1; and in the page (:redirect OtherPage quiet=1:) for a quiet redirect.

Is there any method for redirecting to the equivalent page in a different group, i.e. from BadGroup/thispage => GoodGroup/thispage using similar markup to (:redirect Goodgroup.{Name}:)?

How can a wiki enable linebreaks by default, i.e. without having the directive (:linebreaks:) in a page or in a GroupHeader?

Add to config.php such a line:
$HTMLPNewline = '<br/>';

What's the maximum number of includes that can exist in a page?

By default, PmWiki places a limit of 50 include directives for any given page, to prevent runaway infinite loops and other situations that might eat up server resources. (Two of these are GroupHeader and GroupFooter.) The limit can be modified by the wiki administrator via the $MaxIncludes variable.

Is there any way to include from a group of pages without specifying by exact name, e.g. between Anchor X and Y from all pages named IFClass-* ?

This can be achieved using page lists.

There appears to be a viewing issue when the included page contains the (:title:) directive.

In a default installation, the last title in the page overrides previous ones so you can place your (:title :) directive at the bottom of the page, after any includes. See also $EnablePageTitlePriority.

How to test to see if the page is part of another page?

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

Is there any way to include (chapters of) pages which are protected (authuser.php)?

You can achieve this the other way around: have the public sections in a public page (passwdread=@nopass or @_site_read) and include those into both the protected page, and the public page.

Note that it is strongly recommended to NOT hide sensitive content inside a conditional in an unprotected page.

Is there a variable like $LastModified, but which shows me the creation time?

No, but you can create one in config.php. For instance:

# add page variable [={$PageCreationDate}=] in format yyyy-mm-dd

$FmtPV['$PageCreationDate'] = '[[PmWiki/Functions#PSFT|PSFT]]("[=%Y-%m-%d=]", $page["ctime"])';

How can I test if a variable is set and/or not empty?

Use [=(:if ! equal "{$Variable}" "":) $Variable is not empty. (:ifend:)=]. Note that undefined/inexistent variables appear as empty ones.

Categories: PmWiki Developer

How do I set the same header or footer for all pages/groups?

The header and footer for each page are controlled by the variables $GroupHeaderFmt and $GroupFooterFmt. If your site-wide header and footer pages are Site.SiteHeader and Site.SiteFooter, you can add this in config.php:

### 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}:)';

Note that single quotes must be used in the lines above.

See also the Cookbook:AllGroupHeader recipe.

Instead of using an additional page, you could set any wiki text in $GroupHeaderFmt, for example:

Is there a way to remove page history from page files?

1. Administrators can clean page histories using the Cookbook:ExpireDiff recipe.

2. Administrators with FTP file access can download individual pages from the wiki.d directory, open them in a text editor, manually remove history, and re-upload the files to wiki.d/ directory. Care must be exercised, when manually editing a page file, to preserve the minimum required elements of the page and avoid corrupting its contents. See PageFileFormat#creating.

3. Edit the page. Select all the contents of the edit text area and cut them to the clipboard. Enter delete into the text area and click on the save and edit button. Select all the contents of the edit text area and paste the contents of the clipboard over them. Click on the save button. This will remove all of the page's history up to the final save in which the pasted material is re-added.

How can I restrict viewing the page history (?action=diff) to people with edit permission?

In the local/config.php file, set

In case of this restriction is set up on a farm, and you want to allow it on a particular wiki, set in your local/config.php:

How can I password protect all the pages and groups on my site? Do I really have to set passwords page by page, or group by group?

Administrators can set passwords for the entire site by editing the config.php file; they don't have to set passwords for each page or group. For example, to set the entire site to be editable only by those who know an "edit" password, an administrator can add a line like the following to local/config.php:

For more information about the password options that are available only to administrators, see PasswordsAdmin.

I get http error 500 "Internal Server Error" when I try to log in. What's wrong?

This can happen if the encrypted passwords are not created on the web server that hosts the PmWiki.
The PHP crypt() function changed during the PHP development, e.g. a password encrypted with PHP 5.2 can not be decrypted in PHP 5.1, but PHP 5.2 can decrypt passwords created by PHP 5.1.
This situation normally happens if you prepare everything on your local machine with the latest PHP version and you upload the passwords to a webserver which is running an older version.
The same error occurs when you add encrypted passwords to local/config.php.

Solution: Create the passwords on the system with the oldest PHP version and use them on all other systems.

How can I create private groups for users, so that each user can edit pages in their group, but no one else (other than the admin) can?

Modify the edit attribute for each group to id:username, e.g. set the edit attribute in JaneDoe.GroupAttributes to id:JaneDoe.

There is a more automatic solution, but it's probably not a good idea for most wikis. Administrators can use the AuthUser recipe and add the following few lines to their local/config.php file to set this up:

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

This automatically gives edit rights to a group to every user who has the same user name as the group name. Unfortunately it also gives edit rights to such a user who is visiting a same-named group not just for pages in that group, but for any page on the wiki that relies on the site's default edit password. This can create security holes.

How come when I switch to another wiki within a farm, I keep my same authorization?

PmWiki uses PHP sessions to keep track of authentication/authorization information, and by default PHP sets things up such that all interactions with the same server are considered part of the same session.
For security considerations about shared session pools, see the "Session injection" chapter in Cookbook:SessionSecurityAdvice.
To fix the browser-side convenience issue, one easy way is to make sure each wiki uses a different cookie name for its session identifier. Near the top of one of the wiki's local/config.php files, before calling authuser or any other recipes, add a line like:

You can pick any alphanumeric name for XYZSESSID; for example, for the cs559-1 wiki you might choose

This will keep the two wikis' session cookies independent of each other.

Is it possible to test the password level for display and/or if condition? Example: * (:if WriterPassword:) (display Edit link) (:ifend:)

You can use (:if auth edit:). See ConditionalMarkup.

Can I use (:if …:) to hide secrets in a wiki page?

You can, but usually that's not secure. The recommended strategy is to put secrets in a separate page and restrict all read-related¹ access permissions to those users who are allowed to read the secrets. To display the secrets in another page, you can include (parts of) the secrets page: Users with read access to the secrets will readily see them, whereas other users see nothing or (at your choosing) some other text, e.g. a login link.

The reason why Conditional Markup isn't suitable for access control is that it only applies for rendering wikitext as a web page, and that's just one of many ways to access a page's text. In order to rely on Conditional Markup for protection of secrets, you'd have to restrict all access methods that can circumvent it. To do so, you'd need to keep track of all methods available. In a default installation of PmWiki, some of the easy methods include: Editing a page, viewing its edit history, its source, or including fragments of it into the edit preview of another page. (Preview: To avoid traces in RecentChanges.) However, this list is far from exhaustive, and could easily grow with Recipes? or future versions of PmWiki.

• fmt=#includefaq - Include just the #faq sections from pages in the list. (This can also be expensive, especially if the list includes pages that don't have the [[#faq]] anchor!)
• fmt=#description - List pages and append the page's description if it exists. Creates dash by all names, but adding a nested loop to get rid of it causes markup problems (nested loops are not allowed).
• fmt=#simplename - Simple bullet list of page names, without the Group name.
• fmt=#simplenamespaced - Simple bullet list of spaced page names, without the Group name.
• fmt=#titlesummary - A simple bullet list of page title and summary, defined in page by (:title ttttt:) and (:Summary:sssss:) markup.

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= and category=

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

The category=Name argument differs from link=Category.Name as it only lists pages declared in the category with the markup [[!Name]], and does not include pages simply linking to [[Category/Name]] (unless they also contain [[!Name]]).

• all pages with a link to PmWiki.DocumentationIndex

• all pages with links to the current page

• all pages in the "Skins" category

Since PmWiki 2.3.0, link= and category= accept multiple and negative targets and wildcard lists, see the section Wildcards.

Note, link= and category= will ignore the directives (:if...:), (:include...:), (:redirect...:), (:pagelist...:), and page text variable directives, while searching for links in a page. That means links in included pages will not be found, and links inside non-displayed conditional markup will be found. See PageTextVariables for ways to hide a link on a page while still allowing link= to find it.

Note: The new category= argument requires all pages containing [[!Category]] links to be reindexed. See the recipe Cookbook:ReindexCategories which can automate this.

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=

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. Note: In the URL, encode any "#"s that are in your parameters as "%23". Since this parameter gives users who don't have edit rights the ability to run a pagelist of their choosing, consider its security implications for your website before using it.

Since version 2.2.71, it is possible to explicitly allow only certain parameters that can be overridden, or to disallow some parameters to be overridden. If you need this, instead of 1, enter the parameter names.

(:pagelist request=1:)

(:pagelist request=order,count:)

(:pagelist request=-fmt,-trail:)

req=1

The req=1 parameter requires that search terms be posted (that is, that the user presses "search" on a search form, or follows a link with additional parameters like [[Page?q=terms&order=-name]]) before the pagelist is executed. 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.

When a search is performed, either via a searchbox directive, or via the search form of the skin, if the page contains a "searchresults" directive, that page will be used to display the results of the search; if the page doesn't have a "searchresults" directive, the page Site.Search will be used to display the results.

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=$Name - alphabetically by name across groups
• 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 (note no braces)
• order=$pagevarname - alphabetically by page variable value (note no braces)

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 format:

This assumes that a site has $EnableRelativePageVars enabled (default since 2.2.9).

For example, in the template:

>>comment<<
[[#tvars]]
(:template default count=1 ParamName=Simon:)
Hi, , 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:

The Searchbox Directive

The (:searchbox:) directive generally accepts the same parameters as (:pagelist:) and (:input search:) 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 default placeholder value is "Search" (localized in other languages), and can be modified in the form placeholder="Type search terms..." or removed with placeholder="". In recent browsers, this value appears gray in the search field when it is empty.
  • Optionally, you can add aria-label and other aria-* accessibility attributes that will be attached to the input text field.
  • 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":)

Use label="" to remove the submit button (users need to press "Enter" to search).

By default, the input field has the "text" type for compatibility with HTML/XHTML. Alternatively, you can set it to the "search" input type for HTML5, see $SearchBoxInputType (some HTML5 skins already set this).

The Searchresults directive

The (:searchresults:) directive generally accepts the same parameters as (:pagelist:) and (:input search:) 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>");

You can remove the lines above and below the generated list by adding this in config.php:

See Also

• 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 -
• Cookbook:PageListMultiTargets -
• Cookbook:SearchResults -
• PageDirectives#attachlist - display a list of attachments
• PmWiki.Search - Targeting and customizing search results

FAQ

How PmWiki opens pages with PageStore?

When PmWiki needs to open a file for reading, it will ask the PageStore, objects one after another, in the order you have defined them in config.php, if they have MyGroup.MyPage. The first PageStore object that finds this page will return it and if there are more PageStores they will be not bothered.

When you define a PageStore object with paths like wiki.d/{$Group}/{$FullName} and then ask "is there a page MyGroup.MyPage", the PageStore only checks "is there a file wiki.d/MyGroup/MyGroup.MyPage" so it will only look in the wiki.d/MyGroup sub-directory, not in other subdirectories.

When you write a page, only the first PageStore object is used, that is usually $WikiDir. This way we can have documentation in wikilib.d but if you modify a page from the PmWiki or Site groups on your wiki, it will be saved in wiki.d and from now on only the file in wiki.d will be read and written.

What is the behavior of pagelist and searchresults when only name or word is provided?

Both pagelist and searchresults are searching for all groups unless either (there is a group=ThisGroup argument in the markup or in the search field), or (you have (:template default group=SomeGroup,{*$Group}:) in the pagelist template), or (there is a request=1 argument in the markup and there is somehow a $_REQUEST['group'] variable, eg from a search form or from the url), or (you set some $SearchPatterns['xy'] and list=xy), or (set a default $MakePageListOpt['group'] or $SearchBoxOpt['group']).

If one option is not used, then this option should not be predefined. If there is no needle show all pages; if group= is not used show all groups; if name= is not used show all names; if link= is not used show pages linking or not linking to anywhere; if count= is not used show all pages instead of a portion of them. (The only exception is the order= option which defaults to order=name because without it the results may be ordered inconsistently between page reloads, especially bad if you also use count=21..30.)

How can a custom function retrieve the results of a pagelist as an array?

See this thread on the mailing list.

Should I rename pmwiki.php to index.php?

Renaming pmwiki.php is not recommended. Instead, create an index.php file that contains this single line

How do I make pmwiki.php the default page for a website?

Create an index.php file that runs PmWiki from a subdirectory (pmwiki/ for example) and place it in the site's web document root (the main directory for the website).

Note: You will also need to explicitly set the $PubDirUrl variable (e.g. to "https://example.com/pmwiki/pub") in local/config.php .

How do I enable "Clean URLs" that are shorter and look like paths to my wiki pages? Why does pmwiki.org appear to have a directory structure rather than "?n=pagename" in URLs?

See Cookbook:CleanUrls.

How can I run PmWiki on a standalone (offline, portable) machine ?

See Cookbook:Standalone or Cookbook:WikiOnAStick.

How do I disable uploading of a certain type of file?

Here's an example of what to add to your local/config.php file to disable uploading of .zip files, or of files with no extension:

$UploadExtSize['zip'] = 0;  # Disallow uploading .zip files
$UploadExtSize[''] = 0;     # Disallow files with no extension

How do I attach uploads to individual pages or the entire site, instead of organizing them by wiki group?

Use the $UploadPrefixFmt variable (see also the Cookbook:UploadGroups recipe).

$UploadPrefixFmt = '/$FullName';    # per-page, in Group.Name directories
$UploadPrefixFmt = '/$Group/$Name'; # per-page, in Group directories with Name subdirectories
$UploadPrefixFmt = '';   # site-wide

For $UploadDirQuota - can you provide some units and numbers? Is the specification in bytes or bits? What is the number for 100K? 1 Meg? 1 Gig? 1 Terabyte?

Units are in bytes.

   $UploadDirQuota = 100*1024;         # limit uploads to 100KiB
   $UploadDirQuota = 1000*1024;        # limit uploads to 1000KiB
   $UploadDirQuota = 1024*1024;        # limit uploads to 1MiB
   $UploadDirQuota = 25*1024*1024;     # limit uploads to 25MiB
   $UploadDirQuota = 2*1024*1024*1024; # limit uploads to 2GiB

Is there a way to allow file names with Unicode or additional characters?

Yes, see $UploadNameChars

Where is the list of attachments stored?

It is generated on the fly by the

Downloading binary files such as pictures or ZIP archives with $EnableDirectDownload=0; sometimes results in corrupted files, why?

Some recipe or local configuration may output something before the file. This may happen if you have PHP files with a closing "?>" marker at the end, and some text or white space after it. It is recommended to remove these closing markers from your local and cookbook files.
Alternatively, there may be some PHP warning or message before the file data. On Unix-like systems you can peek into the file with the command less -f -L file.ext and see the first few characters or lines. See Troubleshooting on how to track the source for the errors/warnings.

How do I report a possible security vulnerability of PmWiki?

Pm wrote about this in a post to pmwiki-users from September 2006. In a nutshell he differentiates two cases:

1. The possible vulnerability isn't already known publicly: In this case please contact us by private mail.
2. The possible vulnerability is already known publicly: In this case feel free to discuss the vulnerability in public (e.g. on pmwiki-users or in the PITS).

See his post mentioned above for details and rationals.

What about the botnet security advisory at https://isc.sans.edu/diary/Reports+of+Bots+exploiting+pmwiki+and+tikiwiki/1672?

Sites that are running with PHP's register_globals setting set to "On" and versions of PmWiki prior to 2.1.21 may be vulnerable to a botnet exploit that is taking advantage of a bug in PHP. The vulnerability can be closed by turning register_globals off, upgrading to PmWiki 2.1.21 or later, or upgrading to PHP versions 4.4.3 or 5.1.4.
In addition, there is a test at PmWiki:SiteAnalyzer that can be used to determine if your site is vulnerable.

Wiki Vandalism and Spam

Assumptions

you are using a Blocklist and Url approvals.

You don't want to resort to password protecting the entire wiki, that's not the point after all.

Ideally these protections will be invoked in config.php

How do I stop pages being deleted, eg password protect a page from deletion?

Use Cookbook:DeleteAction and password protect the page deletion action by adding $DefaultPasswords['delete'] = '*'; to config.php or password protect the action with $HandleAuth['delete'] = 'edit';

How do I stop pages being replaced with an empty (all spaces) page?

Add block: /^\s*$/ to your blocklist.

how do I stop pages being completely replaced by an inane comment such as excellent site, great information, where the content cannot be blocked?

Try using the newer automatic blocklists that pull information and IP addresses about known wiki defacers.

(OR) Try using Cookbook:Captchas or Cookbook:Captcha (note these are different).

(OR) Set an edit password, but make it publicly available on the Site.AuthForm template.

How do I password protect the creation of new groups?

See Cookbook:Limit Wiki Groups

How do I password protect the creation of new pages?

See Cookbook:Limit new pages in Wiki Groups

How do I take a whitelist approach where users from known or trusted IP addresses can edit, and others require a password?

Put these lines to local/config.php:

## Allow passwordless editing from own turf, pass for others.
if ($action=='edit'
 && !preg_match("/^90\\.68\\./", $_SERVER['REMOTE_ADDR']) )    
 { $DefaultPasswords['edit'] = pmcrypt('foobar'); }

Replace 90.68. with the preferred network prefix and foobar with the default password for others.

For a single IP, you may use

if($_SERVER['REMOTE_ADDR'] == '127.0.0.1') { # your IP address here
 $_POST['authpw'] = 'xxx';                  # the admin password
}

Please note the security issues: this means that you have your admin passwords in clear in config.php and someone with access to the filesystem can read them (for example a technician of your hosting provider); your IP address may change from time to time (unless you have a fixed IP contract with your ISP). When that happens, someone with your old IP address will be logged in automatically as admin on your wiki. It is extremely unlikely to become a problem, but you should know it is possible; if you are behind a router, all other devices which pass through that router will have the same IP address for PmWiki - your wifi phone, your wife's netbook, a neighbour using your wifi connection, etc. All these people become admins of your wiki. Again, you should evaluate if this is a security risk; In some cases, your ISP will route your traffic through the same proxy as other people. In such a case, thousands of people may have the same IP address.

See also Cookbook:AuthDNS & Cookbook:PersistentLogin

How do I password protect page actions?

See Passwords for setting in config.php

or

How do I moderate all postings?

Enable PmWiki.Drafts

• Set $EnableDrafts, this relabels the "Save" button to "Publish" and a "Save draft" button appears.
• Set $EnablePublishAttr, this adds a new "publish" authorization level to distinguish editing from publishing.

How do I make a read only wiki?

In config.php set an "edit" password.

How do I restrict access to uploaded attachments?

See

• instructions for denying public access to the uploads directory
• Cookbook:Secure attachments

How do I hide the IP addresses in the "diff" pages?

If the user fills an author name, the IP address is not displayed. To require an author name, set in config.php such a line:

  $EnablePostAuthorRequired = 1;

The IP address can also be seen in a tooltip title when the mouse cursor is over the author name. To disable the tooltip, set in config.php:

$DiffStartFmt = 
  "<div class='diffbox'><div class='difftime'><a name='diff\$DiffGMT' href='#diff\$DiffGMT'>\$DiffTime</a>
   \$[by] <span class='diffauthor'>\$DiffAuthor</span> - \$DiffChangeSum</div>";

How do I stop some Apache installations executing a file which has ".php", ".pl" or ".cgi" anywhere in the filename

Use $UploadBlacklist

How do I stop random people from viewing the ?action=source (wiki markup) of my pages? I have (:if auth edit:) text that I don't want the world to see.

$HandleAuth['source'] = 'edit'; or $HandleAuth['source'] = 'admin';

How to I secure my cookies?

See $EnableCookieSecure and $EnableCookieHTTPOnly

How do I set a global password to resist spambots, and informed humans of the password?

See Cookbook:OpenPass-Talk

How can I embed JavaScript into a page's output?

There are several ways to do this. The Cookbook:JavaScript recipe describes a simple means for embedding static JavaScript into web pages using custom markup. For editing JavaScript directly in wiki pages (which can pose various security risks), see the JavaScript-Editable recipe. For JavaScript that is to appear in headers or footers of pages, the skin template can be modified directly, or