FAQ

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.

How do I create a new page?

Typing [[my new page]] will create a link to the new page. There's a lot you can do with double bracket links.

Why do some new pages have a title with spaces like "Creating New Pages" and others end up with a WikiWord-like title like "CreatingNewPages"?

The default page title is simply the name of page, which is normally stored as "CreatingNewPages." However, you can override a page's title by using the (:title Creating New Pages:) directive. This is especially useful when there are special characters or capitalization that you want in the title that cannot be used in the page name.

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 http://example.com/dox/mydoc, add a fake query string on the end with the desired extension (e.g., http://example.com/dox/mydoc?format=.docx). If query strings are unsuitable, a fragment identifier should work, e.g. http://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.

Are InterMap names case sensitive?

Yes, thus eAdmin: is a different InterMap link than EAdmin:.

How can I achieve a localmap.txt mapping with the effect of Pics: Path:/somepathto/pics/?

Use the following:

How can I define an InterMap in PHP?

Use the following:

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

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'] = 'strftime("%Y-%m-%d", $page["ctime"])';

If you like the same format that you define in config.php with $TimeFmt use

 $FmtPV['$Created'] = "strftime(\$GLOBALS['TimeFmt'], \$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 can I get rid of the 'Main' group in urls for pages pointing to Main?

See Cookbook:Get Rid Of Main.

How can I limit the creation of new groups?

See Cookbook:Limit Wiki Groups.

Why doesn't [[St. Giles and St. James]] work as a link? (It doesn't display anything.)

Because it contains periods, and destroys PmWiki's file structure, which saves pages as Group.PageName. Adding those periods disrupts this format. Links may only contain words. If you need a link precisely as shown, the page must be named eg StGilesAndStJames then you can use the (:title:) directive to have the page's title appear with periods (:title St. Giles and St. James:). (Although in US grammar the period is often omitted and in UK grammar the period must be omitted for contractions like St).

How can I delete a wiki group?

Normally you can't, as this requires an admin with server-side access to delete the file that makes up the group's RecentChanges page. But there is an option method of making it possible to delete RecentChanges pages from within the wiki if the admin enables the code found on Cookbook:RecentChanges Deletion.

How can I delete a wiki group's Group.RecentChanges page?

Normally you can't, as this requires an admin with server-side access to delete a file. But there is an optional method of making it possible to delete RecentChanges pages from within the wiki if the admin enables the code found on Cookbook:RecentChanges Deletion.

Can I delete a wiki group inside wiki.d folder on the server to eliminate the group?

Yes, if you delete all files named YourGroup.*, the pages from that group will be removed from the wiki. Note that the documentation (group PmWiki) and the site configuration (groups Site and SiteAdmin) that exist in the default installation, are located in wikilib.d and not in wiki.d, and some recipes provide files located in a wikilib.d subdirectory in the cookbook directory. (You shouldn't delete the groups Site and SiteAdmin, required for normal function.)

How can I list all pages in a WikiGroup?

In a wiki page use (:pagelist group=GroupName list=all:) or in a search box type GroupName/ list=all.

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:

What's the difference between a PageList and a WikiTrail?

The pagelist directive dynamically generates a list of pages. There are many ways to generate the list, including using a WikiTrail as the source. The pagelist directive then displays the pages that match the criteria using an optional template - for example displaying each page name on a separate line as a link or including the entire content. The pagelist directive currently does not have built-in navigation markup that you can put on the pages in the list. By contrast, WikiTrails are simply specified via links on an "index" page and you can put previous-next navigation markup on each page. The two serve very different purposes. WikiTrails are useful for specifying the pages in web feeds, for creating a "tour" through a predefined set of pages, and many other things.

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.

How is a Wiki Group deleted?

An admin can remove the group pages from wiki.d/. Note that a wiki page may also have related uploads.

Fully deleting a group via the wiki isn't possible, since a delete counts as an "update" which causes the Recent Changes? page to be re-created. It is possible to modify the site's configuration to allow deletion of the group's RecentChanges page -- see Cookbook:RecentChangesDeletion.

How is a Category deleted?

To delete a category, delete all the [[!Category]] references from all pages where they occur, then delete the category page as explained above.

maintenance

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 "http://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 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 <script> statements can be inserted using the $HTMLHeaderFmt array.

How would I create a markup ((:nodiscussion:)) that will set a page variable ({$HideDiscussion}) which can be used by (:if enabled HideDiscussion:) in .PageActions?

Add the following section of code to your config.php

SDV($HideDiscussion, 0); 	#define var name
Markup('hideDiscussion', '<{$var}',
 '/\\(:nodiscussion:\\)/', 'setHideDiscussion'); 
function setHideDiscussion() { 
  global $HideDiscussion; 
  $HideDiscussion = true;
} 

This will enable the (:if enabled HideDiscussion:) markup to be used. If you want to print the current value of {$HideDiscussion} (for testing purposes) on the page, you'll also need to add the line:
$FmtPV['$HideDiscussion'] = '$GLOBALS["HideDiscussion"]';

It appears that (.*?) does not match newlines in these functions, making the above example inoperable if the text to be wrappen in <em> contains new lines.

If you include the "s" modifier on the regular expression then the dot (.) will match newlines. Thus your regular expression will be "/STUFF(.*?)/s". That s at the very end is what you are looking for. If you start getting into multi-line regexes you may be forced to look at the m option as well - let's anchors (^ and $) match not begin/end of strings but also begin/end of lines (i.e., right before/after a newline). Also make sure your markup is executed during the fulltext phase.

How can the text returned by my markup function be re-processed by the markup engine?

If the result of your markup contains more markup that should be processed, you have two options. First is to select a "when" argument that is processed earlier than the markup in your result. For example, if your markup may return [[links]], your "when" argument could be "<links" and your markup will be processed before the links markup. The second option is to call the PRR() function in your markup definition or inside your markup function. In this case, after your markup is processed, PmWiki will restart all markups from the beginning.

How do I get started writing recipes and creating my own custom markup?

(alternate) Introduction to custom markup for Beginners

How do I make a rule that runs once at the end of all other rule processing?

Use this statement instead of the usual Markup() call:

$MarkupFrameBase['posteval']['myfooter'] = "\$out = onetimerule(\$out);";

How can I apply CSS styles to a particular group or page?

Simply create a pub/css/Group.css or pub/css/Group.Page.css file containing the custom CSS styles for that group or page. See also Cookbook:LocalCSS.

Why shouldn't passwords be set in group (or page) customization files? Why shouldn't group or page passwords be set in config.php?

The reason for this advice is that per-group customization files are only loaded for the current page. So, if $DefaultPasswords['read'] is set in local/GroupA.php, then someone could use a page in another group to view the contents of pages in GroupA. For example, Main.WikiSandbox could contain:

(:include GroupA.SomePage:)

and because the GroupA.php file wasn't loaded (we're looking at Main.WikiSandbox --> local/Main.php), there's no read password set.

The same is true for page customization files.

Isn't that processing order strange? Why not load per page configuration last (that is after global configuration an per group configuration)?

Many times what we want to do is to enable a certain capability for a group of pages, but disable it on a specific page, as if it was never enabled. If the per-group config file is processed first, then it becomes very difficult/tedious for the per-page one to "undo" the effects of the per-group page. So, we load the per-page file before the per-group.

If a per-page customization wants the per-group customizations to be performed first, it can use the techniques given above (using include_once() or setting $EnablePGCust = 0;).

How do I change the Wiki's default name in the upper left corner of the Main Page?

Put the following config.php

The docs/sample-config.php file has an example of changing the title.

How can I embed PmWiki pages inside a web page?

Source them through a PHP page, or place them in a frame.

How do I change the font or background color of the hints block on the Edit Page?

Add a CSS style to pub/css/local.css: .quickref {background:...; color:... }. The hints are provided by the Site.EditQuickReference page, which is in the PmWiki or Site wikigroup. Edit that page, and change the "bgcolor" or specify the font "color" to get the contrast you need.

There seems to be a default password. What is it?

There isn't any valid password until you set one. Passwords admin describes how to set one.

PmWiki comes "out of the box" with $DefaultPasswords['admin'] set to '*'. This doesn't mean the password is an asterisk, it means that default admin password has to be something that encrypts to an asterisk. Since it's impossible for the pmcrypt() function to ever return a 1-character encrypted value, the admin password is effectively locked until the admin sets one in config.php.

How do I use passwd-formatted files (like .htpasswd) for authentication?

See AuthUser, Cookbook:HtpasswdForm or Cookbook:UserAuth2.

Is there anything I can enter in a GroupAttributes field to say 'same as the admin password'? If not, is there anything I can put into the config.php file to have the same effect?

Enter '@lock' in GroupAttributes?action=attr to require an admin password for that group.

How do I edit protect, say, all RecentChanges pages?

see Security#wikivandalism.

How can I read password protect all pages in a group except the HomePage using configuration files?

As described in PmWiki.GroupCustomizations per-group or per-page configuration files should not be used for defining passwords. The reason is that per-group (or per-page) customization files are only loaded for the current page. So, if $DefaultPasswords['read'] is set in local/GroupA.php, then someone could use a page in another group to view the contents of pages in GroupA. For example, Main.WikiSandbox could contain:

(:include GroupA.SomePage:)

and because the GroupA.php file wasn't loaded (we're looking at Main.WikiSandbox --> local/Main.php), there's no read password set.

How can I password protect the creation of new pages?

See Cookbook:LimitWikiGroups, Cookbook:NewGroupWarning, Cookbook:LimitNewPagesInWikiGroups.

How do I change the password prompt screen?

If your question is about how to make changes to that page... edit Site.AuthForm. If your question is about how to change which page you are sent to when prompted for a password, you might check out the Cookbook:CustomAuthForm for help.

How do I change the prompt on the attributes (?action=attr) screen?

Simply create a new page at Site.AttrForm?, and add the following line of code to config.php:

$PageAttrFmt = 'page:Site.AttrForm';

Note that this only changes the text above the password inputs on the attributes page, but doesn't change the inputs themselves - the inputs have to be dealt with separately. See Cookbook:CustomAttrForm for more info.

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 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.

I only want users to have to create an 'edit' password, which is automatically used for their 'upload' & 'attr' passwords (without them having to set those independently). How do I do this?

By setting $HandleAuth like so:

      $HandleAuth['upload'] = 'edit';
      // And to prevent a WikiSandbox from having it's 'attr' permissions changed 
      // except by the admin (but allowing editors to change it on their own pages/group)
      if(($group=="Site") || ($group=="Main") || ($group=="Category") || 
             ($group=="SiteAdmin") || ($group=="PmWiki") ) {
	$HandleAuth['attr'] = 'admin';  // for all main admin pages, set 'attr' to 'admin' password
      } else { 
	$HandleAuth['attr'] = 'edit';  // if you can edit, then you can set attr
      }

Why doesn't PmWiki use hierarchical / nested groups?

It essentially comes down to figuring out how to handle page links between nested groups; if someone can figure out an obvious, intuitive way for authors to do that, then nested groups become plausible. See Design Notes and PmWiki:Hierarchical Groups.

Why don't PmWiki's scripts have a closing ?> tag?

All of PmWiki's scripts now omit the closing ?> tag. The tag is not required, and it avoids problems with unnoticed spaces or blank lines at the end of the file. Also, some file transfer protocols may change the newline character(s) in the file, which can also cause problems. See also the Instruction separation page in the PHP manual.

Does PmWiki support WYSIWYG editing (or something like the FCKEditor)?

Short answer: PmWiki provides GUI buttons in a toolbar for common markups, but otherwise does not have WYSIWYG editing. For the reasons why, see PmWiki:WYSIWYG.

Categories: PmWiki Developer