====== Customizing templates ======

===== Ways to customize a template =====

There are two main ways to customize a template.

1. If a template supports it, overwrite template files in

//(your DokuWiki root path)///**conf/tpl**%%/%%//(template name)///

as it's described in [[template:dokuwiki#customizing]].

You can put there your own **style.ini**, **header.html**, **footer.html** etc.

(Now (2015 April) developers work on user interface for customizing templates, but while it's a work in progress, do that manually).


2. If a template doesn't support such customization, or if you wish to make deeper changes, refer to
[[devel:templates]]

Basically, you are advised to copy and rename the folder of a template that you wish to change. Thus you create your own template that you can experiment with.

Go into the folder of templates:

//(your dokuwiki path)///lib/tpl/

and there copy a folder of the initial template (that you want to change) into another folder where you will make actual changes. For example the folder

//(your dokuwiki path)///lib/tpl/dokuwiki/

you copy and rename into

//(your dokuwiki path)///lib/tpl/my-template/

Then you can edit files inside "my-template" freely. If something goes wrong you have the initial template untouched, and your customizations will not be overwritten on updates.

You will need also to go to Config manager of DokuWiki and choose your template ("my-template", or what will you name it, instead of "dokuwiki" or something).

Mainly you would need just basic HTML and CSS knowledge to change templates that way. (Also see how PHP is embedded in html). That's simpler than it looks.


3. Another possibility is quick fixing styles by creating and editing file

//(your dokuwiki path)///conf/userstyle.css

In userstyle.css, you can add or overwrite any CSS style of your DokuWiki pages.
(This is useful to override small portions of template or plugin styles without running into problems on updating those later).
[[devel:css#user_styles]]

===== Using CSS =====

:!: Generally, most of the changes to the template can be done just by adding you own CSS styles.
Styles added to userstyle.css would be applied to ALL the templates. Otherwise change individual templates' CSS files.

:!: In order to debug styles, it's useful to have a modern browser with a capability to "inspect elements".
Then right-click over the page and choose from the context menu "Inspect DOM element" or "Inspect with Firebug" or something.

Some users prefer to use PaleMoon browser with FireBug addon
[[http://www.palemoon.org]]

You can check where which elements are, their colors, margins and paddings, etc.
In styles panel you can see which exactly styles are applied, and you can edit elements' styles on-the-fly, and then copy successful results to your CSS files.
Also, it's a good help in learning how HTML and CSS work.

===== Examples =====

An example how you can improve the look of headers using CSS:
[[tips:styling-headers]]