====== 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 [[xref>lib/exe/css.php]] which also handles caching, pattern replacement 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 [[:localization|language]] is used * **feed**: Applied when displaying the [[:syndication|feed]] ===== DokuWiki Stylesheets ===== [[:DokuWiki]] loads its stylesheets from 4 sources, which are loaded in that order (RTL Stylesheets are added last in each step): ==== 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'' | | feed | ''feed.css'' | To fit in well into any template's color scheme , Plugin authors should use the [[#guaranteed color placeholders]]. :!: Stylesheets from plugin are loaded even if a plugin is not used (but not if a plugin is [[:config:disableactions|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 ''[[#style.ini]]'' located within the directory and loads all CSS that are referenced within that file. The loading is done according to the [[#Stylesheet Modes|current mode]]. Additionally, [[#replacements|pattern replacements]] are defined in this ''[[#style.ini]]'' file. * See also: [[templates|Template Development]] ==== 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 before and after Anteater((changed back on 2011-02-26)) ^ CSS File in Anteater ^ When it is used ^ | ''conf/userstyle.css'' | ''conf/userstyle.css'' | Applied in screen mode | | ''conf/userprint.css'' | ''conf/printstyle.css'' | Applied when a page is printed | | ''conf/userrtl.css'' | (''conf/rtlstyle.css'') [[develonly]] | Applied when a right-to-left interface language is used | | ''conf/userfeed.css'' | ''conf/feedstyle.css'' | Applied when displaying the [[:syndication|feed]] | | ''conf/userall.css'' | ''conf/allstyle.css'' | Applied in all display modes | This is 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 %%__%%. For example '' 'searchindexplugin%%__%%buttonfield' '' ===== Style.ini ===== The ''style.ini'' is a [[wp>INI_file|ini file]]. It has two sections : ==== [stylesheets] ==== This part defines which CSS files are loaded. Each line is defined as follow : cssfile.css = mode ''cssfile.css'' is your file name, and mode is the [[#Stylesheet Modes|mode]] to which it applies. ==== [replacements] ==== 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 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'' |''%%__lightgray__%%'' | ^''%%__border__%%'' |border color |''#8cacbb'' |''%%__dark__%%'' | ^''%%__text__%%'' |main text color |''#000'' |''%%__black__%%'' | ^''%%__text_alt__%%'' |alternative text color |''#638c9c'' |''%%__darker__%%'' | ^''%%__text_neu__%%'' |neutral text color |''#666'' |''%%__darkgray__%%'' | 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) |