CSS Stylesheets

Most of DokuWiki's presentation can be controlled through CSS stylesheets. DokuWiki defines some very minimal styles itself. The rest of the CSS definitions come from the template and plugins used.

All CSS files are fetched through a single dispatcher in lib/exe/css.php which also handles caching, pattern replacement, LESS preprocessing and optimizing. The loading of the stylesheets amongst other things is done via the tpl_metaheaders() function, so don't forget to have it within your template.

There are five types of stylesheet modes:

• screen: This is used when displaying pages in the web browser
• print: Definitions here will be used for printing pages
• all: Applied in all display modes
• rtl: Definitions in rtl files will be loaded additionally when a right-to-left language is used deprecated, see RTL Styles
• feed: Applied when displaying the feed

The RTL mode has deprecated since release 2012-10-13 “Adora Belle”, and should therefore not be used anymore. The new and better technique to write styles for right-to-left languages is by using [dir=rtl] in front of each CSS selector within styles for any of the other modes. E.g.

.someClass {
    float: left;
    background-color: __background__;
}
[dir=rtl] .someClass {
    float: right;
}

DokuWiki loads its stylesheets from 4 sources, which are loaded in this order:

These stylesheets are located within /lib/styles. They define basic styling, like the appearance of error messages.

Plugins may define their own style definitions using the following files:

Mode	CSS File
screen	style.css or screen.css
print	print.css
all	all.css
rtl	rtl.css deprecated, see RTL Styles
feed	feed.css

Stylefiles with extension .less are supported as well. However you can use LESS formatting in both the *.css and *.less files.

To fit in well into any template's color scheme, plugin authors should use the guaranteed color placeholders.

Stylesheets from plugins are loaded even if a plugin is not used (but not if a plugin is disabled).

Styles defined here should take care of conflicts. So please be careful when writing a plugin. If possible add a prefix to your styles so that you're sure they won't conflict.

Template's stylesheets are loaded from the selected template dir. DokuWiki reads the template's style.ini located within the directory and loads all CSS that are referenced within that file. The loading is done according to the current mode.

• Changes to style.ini by wiki admins have to be stored in conf/tpl/<tpl>/style.ini. If the changes are applied via the Styling Plugin, this file is automatically created.
• See also: Template Development

Additional styles, independently from the used template can be defined by the wiki administrator by creating the following CSS files in the wiki's configuration folder (conf/ in unadjusted wikis):

CSS File	When it is used
conf/userstyle.css conf/userstyle.less	Applied in screen mode
conf/userprint.css conf/userprint.less	Applied when a page is printed
conf/userrtl.css Since Angua deprecated	Applied when a right-to-left interface language is used deprecated, see RTL Styles
conf/userfeed.css conf/userfeed.less	Applied when displaying the feed
conf/userall.css conf/userall.less	Applied in all display modes

(Note: the .less are possible since 2015-08-10 “Detritus”.)

These style files are useful to override small portions of template or plugin styles without running into problems on updating those later.

The following example reduces the bottom margin of the h2 and h3 headings when viewing in browser:

userstyle.css

h2, h3 {
  margin-bottom: 4px;
}

When you use custom IDs in your template for assigning styles, be sure that the ID does not conflict with an existing ID. In particular, be sure that it won’t conflict with the IDs automatically assigned to section headers. The easiest way to ensure this is to use two adjacent underscores (__) in your ID. Because section IDs are always valid pagenames, they will never contain adjacent underscores.

In plugins use <pluginname>__<id>. For example 'searchindexplugin__buttonfield'

Most often people only need to modify a style of some element on all pages. For example one may want to change the font style for h1 heading. But from time to time, it is desirable to modify a style only on certain page. You could want a special background for any page in the attic namespace so that reader instantly realize that they are reading outdated documentation left as a reference. One could also want to add a specific style to some elements if visitor is a connected user, or only on edit page but not when viewing the page. This is possible because most template use an internal DokuWiki function called tpl_classes(). All you need to know is that this function is used by templates to add classes based on page properties to one of the top div element. For example, when a connected visitor is reading the page syntax the default template produces this div element :

<div id="dokuwiki__top" class="site dokuwiki mode_show tpl_dokuwiki loggedIn   showSidebar hasSidebar lv_1 ns__wiki ns_wiki_ pg_syntax pg_wiki_syntax">

This offers quite a lot of possibilities. you can create a style for

• this page only

  conf/userstyle.css.snippet

  div.dokuwiki.pg_wiki_syntax {
    background: red;
    h1 {
      text-transform: uppercase;
    }
  }

• any page viewed by a connected user in a namespace just below the root

  conf/userstyle.css.snippet

  div.dokuwiki.loggedin.lv_1.mode_show {
    background: red;
    h1 {
      text-transform: uppercase;
    }
  }

If your particular template does not use the tpl_classes() function, you will have different classes available. In fhis case, you may want to contact the developer of your theme and ask that the template makes use of this function.

Enough examples, here are the details :

• site
  No idea what it means, when it is present…
• dokuwiki
  This class is always present
• tpl_<name_of_template>
  By default, this will be tpl_dokuwiki. If you use the sprintdoc, this will be tpl_sprintdoc. and if you use the Art for water template, this will be tpl_artforwater.
• mode_<ACT>
  the action that created the page. Most of the time, this will be mode_view. But see action_modes for a list of action modes. Note that plugins may create more actions.
• loggedIn
  This class is present only for connected user. There is no «notloggedin» or «loggedout» class.
• notFound
  This class is added for non existent page. Follow this link :this:page:does:not:exist:on:purpose ; the rendered page will have this notFound class in its main DW div.
• home
  This class is only present on the main DokuWiki page.
• lv_<X>
  This is the tree depth level of a page. for :dokuwiki page, this level is 0 (zero), so the class will be lv_0 ; for the page devel:css this will be 1, lv_1 and for fr:plugin:struct:aggregation, this will be 3, lv_3.
• ns__<namespace-chain>
  These class are built on the page namespace. Each namespace component concatenated with _ separator. If a namespace has an _ in its name, then this result in a __ in the class name. examples :
  • page :start ⇒ class ns__
  • page fr:plugin:struct:aggregation ⇒ 3 classes are added :
    • class ns__fr
    • class ns__fr_plugin
    • class ns__fr_plugin_struct
  • page matching_food_and_drinks:big_juicy_steak:pan_galactic_gargle_blaster ⇒ 2 classes added :
    • class ns__matching__food__and__drinks
    • class ns__matching__food__and__drinks_big__juicy__steak
• ns_<last_ns_component>_'
This class is based on the last component of the page namespace. Please note that for all pages in the root namespace, there is nothing since the empty root namespace would produce ns__ which is already added by the previous rule. Examples : * page :start ⇒ nothing * page fr:plugin:struct:aggregation ⇒ class ns_aggregation_ * page matching_food_and_drinks:big_juicy_steak:pan_galactic_gargle_blaster ⇒ class ns_big__juicy__steak_ pg_<full-page-id>
* page dokuwiki-css-doc ⇒ class ===== Using images and importing styles ===== Relative links to images (url(…)) and imported stylesheets (@import …) in your own stylesheets are automatically fixed by DokuWiki's CSS dispatcher by treating them relative to the template's root directory. An example: In a plugin, you want to use an image in the sub directory images from your style.css. You can simply write the following CSS: <code css> .someclass { background-image: url(images/icon.gif); } </code> DokuWiki will automatically change the URL, so that the image will be found in the plugin directory, relative to the template directory. Notes: * url(…) in @import folder/style.less are not automatically fixed, the dispatcher assumes these are at top level lib/exe/, not in the actual folder. * @import folder/style.css is handled by the CSS-dispatcher/LESS-parser as normal CSS. So it is not directly included in the css.php. However, the relative references with url(…) to style.css's actual folder are working. Importing css-files is only working if you add these in a all.css/all.less, because these place them as really the first lines of the css.php-file. Via the other files these css-imports are ignored, because they are not really on the first line but on the first line of the e.g. a @media screen {…} block. ===== Caching ===== All CSS files are fetched through a single dispatcher in lib/exe/css.php which also handles caching, amongst other things. The cache expires if files are changed that are mentioned above in the section DokuWiki stylesheets or are referred in the style.ini of your template. Note: Imported stylesheets (@import) are not checked for changes. If you are making changes, ensure that you refresh the cache of your browser by a Hard reload/Force Refresh (e.g. in Chrome/Firefox use Ctrl+F5). ===== Browser (Internet Explorer) Specific CSS ===== DokuWiki does not provide features to address browser specific CSS rendering, therefore any standard approach can be used in your template files. The suggested approach, which will allow the DokuWiki CSS-Dispatcher to process and deliver the CSS normally, is to use conditional comments (mediacollege:detect-IE or WikiPedia Conditional Comments) to create <div id> wrappers around the entire content - the wrappers specify the version of IE in use (see the dokuwiki_template_starter as an example). This wrapper method inserts a specific CSS style ID around the entire content. Your template .css file (design.css, content.css, etc.) then creates browser specific styles by starting a line with #ID. An example, as used for IE7 would be: <code css> #IE8 #dokuwiki__header h1 { …css styles… } </code> You will need to edit the files in your template (ie. detail.php, main.php'', etc.) and insert the relevant conditional checks.