DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:css

This is an old revision of the document!


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.

Stylesheet Modes

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

RTL styles

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 Stylesheets

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

1. Base Stylesheets

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

2. Plugins Styles

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 in both, the *.css and *.less, the LESS formatting.

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.

3. Templates Styles

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.

4. User Styles

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.

Using IDs

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'

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:

.someclass {
   background-image: url(images/icon.gif);
}

DokuWiki will automatically change the URL, so that the image will be found in the plugin directory, relative to the template directory.

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:

#IE7 #dokuwiki__header h1 {
  ...css styles...
}

If you use the dokuwiki_template_starter as the basis for your template, you can use the following #ID's in your CSS file:

ID Browser
#IE7 IE 7 and Earlier
#IE8 IE 8 only

To use additional IDs, you will need to edit the files in your template (ie. detail.php, main.php, etc.) and insert the relevant conditional checks.

devel/css.1440621446.txt.gz · Last modified: 2015-08-26 22:37 by Klap-in

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