====== Stylesheet ======

[[dokuwiki|DokuWiki's]] presentation can be controlled completely by changing its stylesheets (CSS).  The default template includes five stylesheets: \\ \\
| ''design.css'' | [[http://dev.splitbrain.org/view/darcs/dokuwiki/lib/tpl/default/design.css|view]] | [[http://dev.splitbrain.org/download/darcs/dokuwiki/lib/tpl/default/design.css|download]] | controls the look of dokuwiki's "chrome", that's the titles, bars, buttons, etc. |
| ''layout.css'' | [[http://dev.splitbrain.org/view/darcs/dokuwiki/lib/tpl/default/layout.css|view]] | [[http://dev.splitbrain.org/download/darcs/dokuwiki/lib/tpl/default/layout.css|download]] | controls the look of the wiki page itself |
| ''media.css'' | [[http://dev.splitbrain.org/view/darcs/dokuwiki/lib/tpl/default/media.css|view]] | [[http://dev.splitbrain.org/download/darcs/dokuwiki/lib/tpl/default/media.css|download]] | controls the appearance of the media manager |
| ''print.css'' | [[http://dev.splitbrain.org/view/darcs/dokuwiki/lib/tpl/default/print.css|view]] | [[http://dev.splitbrain.org/download/darcs/dokuwiki/lib/tpl/default/print.css|download]] | controls what gets printed and how it looks |
| ''rtl.css'' | [[http://dev.splitbrain.org/view/darcs/dokuwiki/lib/tpl/default/rtl.css|view]] | [[http://dev.splitbrain.org/download/darcs/dokuwiki/lib/tpl/default/rtl.css|download]] | makes layout corrections to support right to left languages |


These files can be found in ''<your.dokuwiki.root>/lib/tpl/<templatename>/''



===== Customizing a style sheet =====

Although it is possible to modify the default template stylesheets, it makes more sense to make a copy of the whole template, change the dokuwiki template setting to the new template and modify the CSS files of the new template.  This way, if there are any problems, you can always change the template setting back to ''default''.  

For more information on how DokuWiki handles stylesheets (including how to properly use IDs) and its CSS dispatcher refer to [[wiki:devel:css]]. For information about templates, and a list of available templates refer to [[wiki:tpl:templates]].


===== Repairing a style sheet =====

Simply copy over the problem stylesheet with an original, either from your most recent Dokuwiki download or from the most recent sources in the link(s) above.







===== More Stylesheet Resources =====


  * [[wp>Cascading_Style_Sheets]] From Wikipedia, the free encyclopedia.
  * [[http://www.w3schools.com/css/|W3Schools]], free tutorials.
  * [[http://htmldog.com/|HTML Dog]], free HTML/CSS tutorials and reference.
  * [[http://www.csscreator.com/css-forum/|CSS Creator Forums]], free CSS help and discussion.

====== CSS Stylesheets ======

All parts of [[wiki:DokuWiki]]'s design are controlled through CSS stylesheets. These files are located in various places but are fetched through a single dispatcher in ''lib/exe/css.php'' which also handles caching, pattern replacement and optimizing.

Certain aspects of handling the CSS files can be configured on a per [[wiki:tpl:template]] basis through an ini file named ''style.ini'' in the template directory.

===== 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 [[wiki:pagenames]], they will never contain adjacent underscores.



===== Stylesheet Loading =====

DokuWiki always loads certain basic stylesheets. Which files from the template should be loaded additionally is configured in the ''[stylesheets]'' section of the ''style.ini''. Stylesheets need to be defined as key = value pairs with the name of the stylesheet on the left side and the output mode on the right.

Possible modes are currently ''screen'', ''rtl'' and ''print''. ''screen'' is the normal mode when the page is viewed in the browser. The ''rtl'' stylesheet is loaded additionally to the screen sheets when a right-to-left [[wiki:multilanguage|language]] language is configured. The ''print'' styles are used when a page is printed.

Here is a list of all loaded stylesheets and their order.

The following style sheets are loaded in **screen mode**

  - lib/styles/style.css
  - styles from lib/tpl/<template>/style.ini with mode ''screen''
  - styles from lib/tpl/<template>/style.ini with mode ''rtl'' ((only loaded when a right-to-left language like Hebrew is configured))
  - lib/plugins/*/style.css
  - lib/plugins/*/screen.css
  - conf/userstyle.css

These files are loaded in **print mode**

  - styles from lib/tpl/<template>/style.ini with mode ''print''
  - lib/plugins/*/print.css
  - conf/userprint.css

A relative URL inside a url() construct in a loaded style sheet is  rewritten 
so that it is the correct relative location for the
designated resource when referenced externally. Generally the  rewriting 
will assume that these URL's are relative to the
location of the style sheet containing the URL. For example, this
will be assumed for plugins and for templates.

URL's inside a url() which are absolute, that is, those beginning  with a 
slash, are not rewritten.

>I have observed a very different screen load order, namely:
>1. style.css from /lib/styles
>2. style.css, screen.css and all.css for each plugin in alphabetical order
>3. css files from style.ini for our template
>4. userstyle.css from /conf



===== Pattern Replacement =====

DokuWiki's CSS dispatcher is able to replace placeholders in the loaded stylesheets which are configured through the ''[replacements]'' section in the templates ''style.ini''. This is especially useful for defining a color scheme once and reuse these colors in all files. Adjusting the colors later then is simply a matter of changing the ''style.ini'' file.


==== Guaranteed color placeholders ====

The following placeholders are the only ones that are safe to be used by plugins.

^placeholder variable		^meaning			^value in default tpl	^name before 2006-08-05	^
^''%%__background__%%''		|main background color		|''#fff''		|''%%__white__%%''	|
^''%%__background_alt__%%''	|alternative background color	|''#dee7ec''		|''%%__medium__%%''	|
^''%%__background_neu__%%''	|neutral background color	|''#f5f5f5''		|''%%__darkgray__%%''	|
^''%%__border__%%''		|border color			|''#8cacbb''		|''%%__dark__%%''	|
^''%%__text__%%''		|main text color		|''#000''		|''%%__black__%%''	|
^''%%__text_alt__%%''		|alternative text color		|''#638c9c''		|''%%__darker__%%''	|
^''%%__text_neu__%%''		|neutral text color		|''#666''		|''%%__lightgray__%%''	|

From 2006-08-05 on they have been renamed to be more semantically correct. Plugins and templates making use of the pattern replacement which are older than this might not yet have adopted these variables, but are advised to do so.

==== Other color placeholders used by the default template ====

These additional placeholders are used in the default templates. Other templates might use them as well, but are not necessarily obliged to do so.

^placeholder variable		^meaning				^value in default tpl	^name before 2006-08-05	^
^''%%__background_other__%%''	|other background colour		|''#f7f9fa''		|''%%__lighter__%%''	|
^''%%__text_other__%%''		|other text colour			|''#ccc''		|''%%__mediumgray__%%''	|
^(none, omitted)		|-					|''#eef3f8''		|''%%__light__%%''	|
^''%%__extern__%%''		|link colour				|''#436976''		|(unchanged)		|
^''%%__existing__%%''		|link colour of existing internal links	|''#090''		|(unchanged)		|
^''%%__missing__%%''		|link colour of missing internal links	|''#f30''		|(unchanged)		|
^''%%__highlight__%%''		|colour of highlighted search snippets	|''#ff9''		|(unchanged)		|

==== Custom color placeholders ====
Adding custom color placeholders is simply a matter of adding them to the ''style.ini'' of your template, analogous to the existing ones ie.

<file>
__your_custom_placeholder__ = "#f8f8f8"
</file>



====== Comments ======
>rtl.css does not seem to load on rtl languages used with translation plugin, multitemplate, and styleman.  Can someone help with this?