Style Guide

The first step to create a new page, you need to edit an existing page, and on it add a link to the page you want to create.

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

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

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

Learn more:

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

A key feature of Wiki Wiki Webs is the ease of creating hyper links in the text of a document. PmWiki provides multiple mechanisms for creating such links.

Links to other pages in the wiki

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

PmWiki creates a link by using the text inside the double brackets. It does this by removing spaces between words, and automatically capitalizing words following spaces or other punctuation (like ~). Thus [[Wiki sandbox]], [[wiki sandbox]], and [[WikiSandbox]] all display differently but create the same link to the page titled WikiSandbox.

In other words, PmWiki will automatically create the link path name using title case as a rule, but link text will display in the format you have entered it.

A suffix can also be added to the end of a link, which becomes part of the link text but not the target. Thus [[wiki sandbox]]es is a link to WikiSandbox but displays as wiki sandboxes.

Link text in (parentheses) will not be not displayed, so that [[(wiki) sandbox]] links to WikiSandbox and displays as sandbox.

Finally, you can specify the link text via a vertical brace, thus [[WikiSandbox | a play area]], which links to WikiSandbox but displays as a play area. You can use an arrow (->) to reverse the order of the text and target, as in [[a play area -> WikiSandbox]] (a play area).

Some sites also recognize WikiWord links, in which a camel case (capitalised) WikiWord appearing in the text is automatically treated as a link to a page of the same name.

Link shortcuts

Use of special characters in title is not a problem for PmWiki, but sometimes the character set is different from your computer and the server computer or the client computer that is used to read your wiki. Specially UTF-8 gives some problems. So it's better not to use these and keep ASCII characters if possible. Any page can have a (:title <name>:) directive to display a localized title instead of the page file name. In this case, the following tip is important and usefull.

[[PageName|+]] creates a link to PageName and uses that page's title as the link text, e.g., [[PmWiki.BasicEditing|+]] where the page BasicEditing has the directive (:title Basic PmWiki editing rules:) gives Basic PmWiki editing rules. Since PmWiki version 2.2.14 this works also for those technical pages that have an entry in the XLPage, without the need to add a (:title <name>:) directive in that page (for more details see Localization.Localization).

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

[[!PageName]] creates a link to the PageName in the group called Category. See Categories.

[[~Author]] link creates a link to the page called Author in the Profiles group.

~~~ markup creates a link for the current Author when it encounters three tilde characters (~) in a row (~~~).

~~~~ markup creates a link for the current author and appends the current date and time when four tilde characters (~) in a row are encountered

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

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

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

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

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

Links to actions

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

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

Links outside the wiki

Links to external sites (URLs)

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

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

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

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

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

Links to intranet (local) files

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

Link characteristics

Links as References

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

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

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

Intermaps

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

Links to pages in other wiki groups

See Wiki Group.

Links that open a new browser window

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

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

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

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

Links that are not followed by robots

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

Links and CSS Classes

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

.selflink

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

.wikilink

A link to another page within the wiki.

.urllink

A link to a page outside the wiki.

Notes

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

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

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

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

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

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

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

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

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

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

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

Creating groups

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

in config.php).

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

Groups in a standard PmWiki distribution

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

Special Pages in a Group

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

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

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

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

Group's default page

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

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

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

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

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

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

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

Subgroups? Subpages?

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

Restricting the creation of new groups

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

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

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

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

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

Paragraphs

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

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

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

Indented Paragraphs (Quotes)

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

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

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

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

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

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

Bulleted and Numbered Lists

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

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

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

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

Also see: PmWiki:ListStyles, Cookbook:WikiStylesPlus.

Definition Lists

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

:term:definition of term
::second-level item: definition of 2nd-level item

Whitespace Rules

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

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

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

Horizontal Line

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

Emphasis and character formatting

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

Other styling

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

{+insert or underscore+}, 

{-delete or strikethrough or strikeout-}

• `WikiWord WikiWord neutralisation

See also Wiki Styles for advanced text formatting options.

References

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

See Links for details.

Headings

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

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

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

See Cookbook:Numbered Headers for numbered headings.

Escape sequence

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

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

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

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

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

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

 
  The font color of 
  this text is blue

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

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

Comments

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

Special Characters

Tables

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

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

See Table Directives for advanced tables.

Can't find it here?

See Markup Master Index.

Table basics

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

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

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

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

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

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

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

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

Formatting cell contents

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

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

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

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

Note that header and detail cells have different default alignments.

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

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

Table attributes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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