It's better when it's simple

User Tools

Site Tools


Using CSS to Style Headers.

This work in progress is a contribution originated from discussion in the Forum Thread Use of small images in the section headers.

One of the limitations1) of the DokuWiki software is the inability to use formatting style and links inside headings (titles). In other words, the following is not possible:

==== {{:images:icon.png}} MyHeading ====

Which renders as:

{{:images:icon.png}} MyHeading

However, this does not mean that headers can not be stylized. As any other element in a wikipage, headers are affected by the styles defined in, preferably, and among other files, conf/userstyle.css. So it is possible to use even very basic CSS rules to add some style to headers.

Headers can be stylized with normal CSS tags as follows:

h1 {
  font-family: fantasy;
  font-variant: italic;

Which, on my particular installation, has the following effect:

But the key to efficiently customize the headers is to remember these three simple rules:

  1. Every header is a (direct) child of div.page2).
  2. Every header, except the first, is preceded with a div.
  3. An a tag inside the header is the real container of the header text.

With this simple knowledge, one can do some nice stuff to their headers.

Here some examples, as well as pictures displaying the effect, will be provided:

:!:Note: these examples are intended for decent web browsers, at least. The testsuite is comprised of Opera 9.6 and Firefox 3.0. These enhacements were not tested in Internet Explorer (and, if they were, most probably they would fail). And the pictures were taken from the default template and rendering by Opera 9.6.

It is recommended that one reloads from server (via ?purge=true, for example) to see the results.

Case 1: A simple modification of the text style

This example is very simple. We will apply “small-caps” to all our h2 headings.

To do this, let's paste the following at the end of our conf/userstyle.css:

  font-variant: small-caps;

Reload and marvel before the results:

Case 2: Borders and backgrounds

This example is a bit more complicated. Paste the following into the conf/userstyle.css:

h2 {
  margin: 2px;
  padding: 2em;
  border: 2px solid __text_alt__;

The result is as follows:

Here you can see that, despite the fact that we have specified a padding, the text appears very close to the border. The reason for that lies in both the CSS box model and the DokuWiki rendering rules. Besides, there's about one em of extra height above the text. This is caused by the <a> tag placed inside the header.

Watch the effects of the following modification:

h2 {
  margin: 2px;
  padding: 2em !important;
  border: 2px solid __text_alt__;

The !important modification is necessary because the headers are already being stylized by the style.css corresponding to the template. The “!important” modificator indicates to the browser that this style takes precedence over a style that is usually overriden by the presence of children elements, of which we have none3).

So, bottom line, if you want to do anything with the size or shape of your headers, you must add the “!important” modificator to the corresponding rules.

Case 3: Adding a small icon before the heading

A more advanced case would be to add a small icon to the left of our headers, just like what is one with interwiki links. For this, we need more advanced CSS rules: in particular, we need CSS Selectors.

Paste the following into the conf/userstyle.css:

h2:before {
  content: url(;

Again, reload from server to see the results. See how simple it is to add a icon to a header?

To add the same icon to a group of headers, one would need to indicate the :before selector for all of them:

h2:before, h3:before, h4:before {

Of course, if you want a text symbol (like, a discus or something, just like lists) instead of an image, one can still do that:

h2:before {
  content: '\26a0\00a0';

The content is added using the Unicode values for the symbols. You can check a list of symbols, as well as their availability for web rendering in your system, at Allan Wood's Page. The \00a0 is actually a nonbreaking space (the &nbsp; entity) and is being used to prevent the “warning” symbol from being too close to the text.

The solution for all browsers

The above solution won't work for “old-fashioned” browsers. Here is the variant that will also work in IE6 + IE7:

h2 {
  background: url( no-repeat left center;
  padding-left: 20px;

Case 4: Styling a header with respect to the preceding content

To be done

Case 5: Styling a header depending on key terms

To be done

See also

as :!: discussed here and in the mailing lists
the class name can change depending on template
the <a> is an inline element, thus any padding or size setting is ignored as per CSS
tips/styling-headers.txt · Last modified: 2023-05-03 01:06 by

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki