%audience% 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
>><<

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

||border=1 cellpadding=3 cellspacing=0
||apply=img ||apply the style to any image that follows|| ||
||apply=p ||apply the style to the current paragraph||* ||
||apply=pre ||apply the style to the current preformatted text|| ||
||apply=list ||apply the style to the current list||* ||
||apply=item ||apply the style to the current list item||* ||
||apply=div ||apply the style to the current div|| ||
||apply=block ||apply the style to the current block,
whether it's a paragraph, list, list item,
heading, or division.||* ||

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.

Tip: Any undefined WikiStyle is automatically treated as a request for a class, thus %pre% is the same as saying %class=pre%.

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

%trail% <<|Documentation Index|>>

>>faq<<

Q: Some of my colors aren't working! For example, %color=#AAAAAA% works, but %color=#AA3333% doesn't work. What's wrong?

A: Be sure to use lowercase letters for rgb hex colors, otherwise PmWiki may mistake the color value for a WikiWord.