Q What is PmWiki?

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

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

Q What are the requirements?

See the PmWiki requirements page.

Q Where can I find documentation?

See the documentation index page.

Q How can I download PmWiki?

See the download page.

Q How do I install PmWiki?

Instructions for installation are on the installation page.

Q How do I get help with PmWiki?

See Mailing lists and How to get assistance.

Q How do you pronounce “Michaud”?

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

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

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

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

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

Q Where can I find more documentation?

See the documentation index and the markup master index pages.

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

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

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

Q How do I create an advanced table?

See table directives

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

Q 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; }

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

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

Q How to 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.

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

See Customizing access keys.

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

Use (:redirect PageName status=301:).

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

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

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

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

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

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

Q How can I embed Java Script? into a page’s output?

There are several ways to do this. The Cookbook:JavaScript recipe describes a simple means for embedding static Java Script? into web pages using custom markup. For editing Java Script? directly in wiki pages (which can pose various security risks), see the JavaScript-Editable recipe. For Java Script? 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.

Q 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:\\)/e', 'setHideDiscussion(true)'); 
function setHideDiscussion($val) { 
  global $HideDiscussion; 
  $HideDiscussion = $val;
} 

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"]';

Q PmWiki only supports tool tips for external links, can I use custom markup to add tool tips to internal links?

Yes, add the following custom markup to your config.php:
Markup('%title%', 'inline', '/%title%(.*?)"(.*?)"(.*?)%%/', '<span title="$2">$1$3</span>'); # Add tool tips to internal links, Example: %title%[[link"tool tip"]]%%

Use the markup with internal links such as:
%title%[[CookBook "cool" | Example]]%%

You can apply it in other situations too, for instance:
%title%"flexible"(:if true:)write something(:else:)write something else(:ifend:)%%

See also Cookbook:LinkTitles.

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

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

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

(alternate) Introduction to custom markup for Beginners

Q 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);”;

Q If my wiki is internationalized by config.php, how do I revert a specific group to English?

Use $XLLangs = array('en'); in the group’s group customization file.

Q If my wiki is in English and I want just one page, or group, in Spanish do I say XLPage('es','PmWikiEs.XLPage'); in the group or page configuration file?

Yes, that is usually the best method. If you were doing this with many scattered pages, or with several languages, you might find it easier to maintain if you load the translations all in config.php like this:

   XL Page?(‘es’,’PmWiki Es.XL Page?’);
   XL Page?(‘fr’,’PmWiki Fr.XL Page?’);
   XL Page?(‘ru’,’PmWiki Ru.XL Page?’);
   $XLLangs = array(‘en’);

Then in each group or page configuration file, you’d just use $XLLangs = array(‘es’); to set the language to use (in this case, Spanish). Note that though this method is easier to maintain, its somewhat slower because it loads all the dictionaries for each page view, even if they won’t be used.

Q What does the first parameter of this function stand for? How can it be used?

The XL Page? mechanism allows multiple sets of translations to be loaded,
and the first parameter is used to distinguish them.

For example, suppose I want to have translations for both normal French
and “Canadian” French. Rather than maintain two entirely separate sets
of pages, I could do:

    XL Page?(‘fr’, ‘PmWiki Fr.XL Page?’);
    XL Page?(‘fr-ca’, ‘PmWiki Fr Ca.XL Page?’);

PmWiki Fr.XL Page? would contain all of the standard French translations,
while PmWiki Fr CA.XL Page? would only need to contain “Canada-specific”
translations — i.e., those that are different from the ones in the
French page.

The first parameter distinguishes the two sets of translations.
In addition, a config.php script can use the $XLLangs variable
to adjust the order of translation, so if there was a group or
page where I only wanted the standard French translation, I
can set

    $XLLangs = array(‘fr’, ‘en’);

and PmWiki will use only the ‘fr’ and ‘en’ translations (in that order),
no matter how many translations have been loaded with XL Page?().

Q How can I use PHP to add a translation for an individual string on the fly?

Use the XLSDV() function to provide a translation for a specific (English) string. For instance, with this in config.php

    XLSDV(‘nl’, array(‘my English expression’=>’mijn Nederlandse uitdrukking’));

any instance of the variable expression $[my English expression] in wiki mark-up will be displayed as my English expression in default (English) context, but as mijn Nederlandse uitdrukking in Dutch (nl) context, i.e. when XLPage('nl',...) has been called for that page in config.php or a cookbook recipe.

But beware: XL Page?() uses XLSDV() internally for its translation pairs, too, and only the first definition is accepted! Thus, if the Dutch XL Page? already contains a translation for your string like

    ‘my English expression’ => ‘bla bla’,

and you want to override that, you need to use your XLSDV(‘nl’,…) before calling the correspondent XL Page?(‘nl’,…). Otherwise, by using XLSDV() after XL Page?() - e.g. within a recipe that is included later in config.php - your translation will only work as long nobody defines ‘my English expression’ in that XL Page?.

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

Q 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/Group A?.php, then someone could use a page in another group to view the contents of pages in Group A?. For example, Main.Wiki Sandbox could contain:

(:include GroupA.SomePage:)

and because the Group A?.php file wasn’t loaded (we’re looking at Main.Wiki Sandbox → local/Main.php), there’s no read password set.

The same is true for page customization files.

Q 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 in PmWiki.GroupCustomizations (using include_once() or setting $EnablePGCust = 0).

Q Why am I seeing strange errors after upgrading?

Make sure all of the files were updated, in particular pmwiki.php.

This question sometimes arises when an administrator hasn’t
followed the advice, which used to be less prominent, on the
installation and
initial setup tasks pages and has renamed
pmwiki.php instead of creating an index.php wrapper script.
If you have renamed pmwiki.php to index.php, then the upgrade procedure
won’t have updated your index.php file. Delete the old version and
create a wrapper script so it won’t happen again.

Sometimes an FTP or other copy program will fail to transfer all of the
files properly. One way to check for this is by comparing file sizes.

Be sure all of the files in the wikilib.d/ directory
were also upgraded. Sometimes it’s a good idea to simply delete the wikilib.d/
directory before upgrading. (Local copies of pages are stored in wiki.d/ and not wikilib.d/.)

If you use a custom pattern for $GroupPattern make sure that it includes Site ($SiteGroup) and since PM Wiki? 2.2 also Site Admin ($SiteAdminGroup).
Otherwise migration may fail (e.g. missing Site Admin for PM Wiki? 2.2 and later) and/or login does not work.
Additionally Main ($DefaultGroup) should be included too.

Q I’m suddenly getting messages like “Warning: fopen(wiki.d/.flock): failed to open stream: Permission denied…” and Cannot acquire lockfile”… what’s wrong?

Something (or someone) has changed the permissions on the wiki.d/.flock file or the wiki.d/ directory such that the webserver is no longer able to write the lockfile. The normal solution is to simply delete the .flock file from the wiki.d/ directory — PmWiki will then create a new one. Also be sure to check the permissions on the wiki.d/ directory itself. (One can easily check and modify permissions of the wiki.d/ directory in FileZilla (open-source FTP app) by right-clicking on the file > File attributes)

Q My links in the sidebar seem to be pointing to non-existent pages, even though I know I created the pages. Where are the pages?

Links in the sidebar normally need to be qualified by a WikiGroup in order to work properly (use [[Group.Page]] instead of [[Page]]).
Also: Make sure you type SideBar with a capital B.

Q Why am I seeing “Warning: Cannot modify header information - headers already sent …” messages at the top of my page.

If this is the first or only error message you’re seeing, it’s usually an indication that there are blank lines or spaces before the <?php or after the ?> in a local customization file. Double-check the file and make sure there aren’t any blank lines or spaces before the initial <?php. It’s often easiest and safest to eliminate any closing ?> altogether. On Windows, it may be necessary to use a hex editor to convert LFCR line endings to LF line endings in the local\config.php file.

If the warning is appearing after some other warning or error message, then resolve the other error and this warning may go away.

Q How do I make a PHP Warning about function.session-write-close go away?

If you are seeing an error similar to this

Warning: session_write_close() [function.session-write-close]:
open(/some/filesystem/path/to/a/directory/sess_[...]) failed: No such file
or directory (2) in /your/filesystem/path/to/pmwiki.php on line NNN

PmWiki sometimes does session-tracking using PHP’s
session-handling functions.
For session-tracking to work, some information needs to be written
in a directory on the server. That directory needs to exist and
be writable by the webserver software. For this example, the
webserver software is configured to write sessions in this
directory

but the directory doesn’t exist. The solution is to do at least one
of these:

• Create the directory and make sure it’s writable by the webserver software
• Provide a session_save_path value that points to a directory that is writable by the server, e.g.

Q Why is PmWiki prompting me multiple times for a password I’ve already entered?

This could happen like out of nowhere if your hosting provider upgrades to PHP version 5.3, and you run an older PmWiki release. Recent PmWiki releases fix this problem.

Alternatively, this may be an indication that the browser isn’t accepting cookies, or that PHP’s session handling functions on the server aren’t properly configured. If the browser is accepting cookies, then try setting $EnableDiag=1; in local/config.php, run PmWiki using ?action=phpinfo, and verify that sessions are enabled and that the session.save_path has a reasonable value. Note that several versions of PHP under Windows require that a session_save_path be explicitly set (this can be done in the local/config.php file). You might also try setting session.auto_start to 1 in your php.ini.

See also the question I have to log in twice below.

Q I edited config.php, but when I look at my wiki pages, all I see is “Parse error: parse error, unexpected T_VARIABLE in somefile on line number.”

You’ve made a mistake in writing the PHP that goes into the config.php file. The most common mistake that causes the T_VARIABLE error is forgetting the semi-colon (;) at the end of a line that you added. The line number and file named are where you should look for the mistake.

Q Searches and pagelists stopped working after I upgraded — no errors are reported, but links to other pages do not appear (or do not appear as they should) — what gives?

Be sure all of the files in the wikilib.d/ directory
were also upgraded. In particular, it sounds as if the Site.Page List Templates page is either missing (if no links are displayed) or is an old version (if the links do not appear as they should). Allso make sure that read-permissions (attr) are set for the pages Site.Page List Templates and Site.Search.

Q Some of my posts are coming back with “403 Forbidden” errors, “Not Acceptable”, or “Internal Server Error”. This happens with some posts but not others.

Your webserver probably has mod_security enabled. The mod_security “feature” scans all incoming posts for forbidden words or phrases that might indicate someone is trying to hack the system, and if any of them are present then Apache returns the 403 Forbidden error. Common phrases that tend to trigger mod_security include “curl “, “wget”, “file(“, and “system(“, although there are many others.

Since mod_security intercepts the requests and sends the “forbidden”
message before PmWiki ever gets a chance to run, it’s not a bug in PmWiki, and
there’s little that PmWiki can do about it. Instead, one has to alter the
webserver configuration to disable mod_security or reconfigure it to allow
whatever word it is forbidding. Some sites may be able to disable mod_security
by placing SecFilterEngine off in a .htaccess file.

Q I get the following message when attempting to upload an image, what do I do?

Warning: move_uploaded_file(): SAFE MODE Restriction in effect. The script whose uid is 1929 is not allowed to access /home/onscolre/public_html/pmwikiuploads/Photos owned by uid 33 in /home/onscolre/public_html/pmwiki/scripts/upload.php on line 198

PmWiki can’t process your request

?cannot move uploaded file to /home/onscolre/public_html/pmwikiuploads/Foundation Pupils in 1958?.jpeg

We are sorry for any inconvenience.

Your server is configured with PHP Safe Mode enabled. Configure your wiki to use a site-wide uploads prefix, then create the uploads/ directory manually and set 777 permissions on it (rather than letting PmWiki create the directory).

Q I’m starting to see “Division by zero error in pmwiki.php…” on my site. What’s wrong?

It’s a bug in PmWiki that occurs only with the tables markup and only for versions of PHP >= 4.4.6 or >= 5.2.0. Often it seems to occur “out of nowhere” because the server administrator has upgraded PHP. Try upgrading to a later version of PmWiki to remove the error, or try setting the following in local/config.php:

    $TableRowIndexMax = 1;

Q I have to log in twice (two times) (2 times). -or- My password is not being required even though it should. -or- I changed the password but the old password is still active. -or- My config.php password is not over-riding my farmconfig.php password.

It could happen if (farm)config.php, or an included recipe, directly calls the functions Cond Auth?(), or Retrieve Auth Page?(), Page Text Var?(), Page Var?() and possibly others, before defining all passwords and before including Auth User (if required).

The order of config.php is very significant.

Q 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 crypt() function to ever return a 1-character encrypted value, the admin password is effectively locked until the admin sets one in config.php.

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

See AuthUser, Cookbook:HtpasswdForm or Cookbook:UserAuth.

Q Is there anything I can enter in a Group Attributes 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 Group Attributes?action=attr to require an admin password for that group.

Q How do I edit protect, say, all Recent Changes? pages?

see Security#wikivandalism.

Q How can I read password protect all pages in a group except the Home Page? 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/Group A?.php, then someone could use a page in another group to view the contents of pages in Group A?. For example, Main.Wiki Sandbox could contain:

(:include GroupA.SomePage:)

and because the Group A?.php file wasn’t loaded (we’re looking at Main.Wiki Sandbox → local/Main.php), there’s no read password set.

Q How can I password protect the creation of new pages?

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

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

Q 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.Attr Form?’;

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.

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

Q 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 Wiki Sandbox 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==“Site Admin”) || ($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
      }