• View
• Edit
• History
• Print

authors (basic)

Wikistyle basics

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

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

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

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

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

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

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

See PmWiki:WikiStyleColors for more color help.

Scopes

Wikistyles can also specify a scope; with no scope, the style is applied to any text that follows up to the next wikistyle specification or the end of the paragraph, whichever comes first. Including a scope changes the specification to apply to the whole paragraph (%p ...%), an entire list (%list ...%), an item within a list (%item ...%), or any block (%block ...%). Those scopes are predefined shortcuts for the "apply=" attribute, which is discussed below.

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

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

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

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

    preformatted text

Wikistyle attributes

The style attributes recognized within a wikistyle specification are:

    ------------ CSS -------------          --HTML--
    color               bgcolor             class 
    background-color    margin              id
    text-align          padding             hspace
    text-decoration     border              vspace
    font-size           float               target
    font-family         list-style          rel
    font-weight         width*              accesskey
    font-style          height*             value
    display

    Special: define, apply

The attributes in the first two columns correspond to the [Link requires approval](approve) (CSS) properties of the same name. The attributes in the last column apply only to specific items:

• class= and id= assign a CSS class or identifier to an HTML element
• target=name opens links that follow in a browser window called "name"
• rel=name in a link identifies the relationship of a target page
• accesskey=x uses 'x' as a shortcut key for the link that follows
• value=9 sets the number of the current ordered list item

* The width and height attributes have asterisks because they are handled specially for <img .../> tags. If used by themselves (i.e., without anything providing an "apply=" parameter to the wikistyle), then they set the 'width=' and 'height=' attributes of any <img ... /> tags that follow. Otherwise, they set the 'width:' and 'height:' properties of the element being styled.

Applying wikistyles to blocks

Normally a wikistyle applies to a span of (inline) text, but the apply= attribute allows a style to be applied to something else. The predefined apply= values are:

The starred items also have wikistyle shortcuts already defined, thus %p color=blue% is the same as %apply=p color=blue%, and %list ROMAN% is the same as %apply=list list-style=upper-roman%.

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

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

here is some text in
a paragraph and if
we try to %apply=p color=blue% change
the color of the paragraph in the middle
it won't work because the style comes
after the paragraph has already been started.

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

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

Enabling Styles

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

    $WikiStyleCSS[] = 'line-height';

to the local/config.php file.

Custom style shortcuts

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

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

%box% [@
$ echo "Hello world"
Hello World
$ exit
@]

%box font-weight=bold color=green% [@
$ echo "I said, HELLO"
@]

$ echo "Hello world"
Hello World
$ exit

$ echo "I said, HELLO"

Tip: It's often a good idea to put common style definitions into Group Header pages so that they can be shared among multiple pages in a group. Or, the wiki administrator can predefine styles site-wide as a local customization (see CustomWikiStyles).

Tip: Use custom style definitions to associate meanings with text instead of just colors. For example, if warnings are to be displayed as green text, set %define=warn green% and then use %warn% instead of %green% in the document. Then, if you later decide that warnings should be styled differently, it's much easier to change the (one) definition than many occurrences of %green% in the text.

Predefined style shortcuts

PmWiki defines a number of style shortcuts.

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

Examples

WikiStyleExamples contains a number of examples of ways to use wikistyles in pages.

Known Issues

• Percents in style definitions (like: %block width=50% %) require the use of "pct" instead of "%".

See Also

Custom Wiki Styles

<< Table directives | Documentation Index | WikiStyle examples >>