DokuWiki Template Configuration — Settings, User CSS, and Template Inheritance

In this tutorial, you'll learn how to configure DokuWiki templates, including template-specific settings in the Configuration Manager, user CSS overrides with userstyle.css, template inheritance and fallback, and managing template configurations across multiple wiki instances.

What You'll Learn

• Template settings in the Configuration Manager
• User CSS overrides (userstyle.css and userrtl.css)
• Template inheritance and fallback
• Template configuration files
• Managing template settings across environments
• Debugging template configuration issues

Why It Matters

Template configuration is how you customize a template without modifying its code. Using the Configuration Manager means your settings are stored separately from the template files and survive template updates. User CSS lets anyone (not just template developers) make visual changes. Understanding how to configure templates properly keeps your customizations maintainable.

Real-World Use

An organization uses the same template on 5 DokuWiki instances: development, staging, production, and two client wikis. Each instance has the same template but different colors. They use Configuration Manager settings for instance-specific values (logo, site name) and maintain a shared userstyle.css for common styles. Template updates are applied to all instances without losing customizations.

Learning Path

flowchart LR
  A[Custom Template] --> B[Template Configuration]
  B --> C[Caching]
  C --> D[SEO]
  D --> E[Multi-Language]
  E --> F[CLI Tools]

Template Configuration Manager

Many templates (especially Bootstrap3) register their own settings in the Configuration Manager.

Accessing Template Settings

1. Admin > Configuration Manager
2. Scroll to the template section (usually named after the template)
3. Adjust settings as needed
4. Click "Save"

Common Template Settings

Settings Storage

Template settings are stored in conf/tpl/templatename.local.php:

<?php
// conf/tpl/mytemplate.local.php
$conf['sidebar_position'] = 'left';
$conf['show_breadcrumbs'] = 1;
$conf['footer_text'] = 'Custom footer';

User CSS Overrides

Users can override template styles without editing template files.

userstyle.css

Create conf/userstyle.css to add custom CSS:

/* conf/userstyle.css */
/* This file is loaded AFTER template styles */

#dokuwiki__header {
    background-color: #2c3e50;
    color: #ecf0f1;
}

.dw-navbar a {
    color: #3498db;
}

.dw-navbar a:hover {
    color: #2980b9;
}

userrtl.css

For right-to-left languages, use conf/userrtl.css:

/* conf/userrtl.css */
body {
    direction: rtl;
}

#dw__sidebar {
    float: right;
}

#dw__content {
    margin-left: 0;
    margin-right: 270px;
}

CSS Loading Order

The CSS loading order determines which styles take priority:

1. DokuWiki core CSS
2. Template CSS
3. Plugin CSS
4. userstyle.css (highest priority)

Because userstyle.css is loaded last, its styles override everything without needing !important.

Template Inheritance

Templates can inherit from parent templates, creating a hierarchy.

How Inheritance Works

lib/tpl/
├── dokuwiki/              # Parent: default template
│   └── main.php
└── mychildtemplate/       # Child: inherits from dokuwiki
    ├── template.info.txt   # parent: dokuwiki
    ├── main.php            # Overrides parent's main.php
    └── css/
        └── style.css      # Additional CSS

Declaration in template.info.txt

base    mychildtemplate
parent  dokuwiki

Fallback Chain

When DokuWiki looks for a template file:

1. Check child template first
2. If not found, check parent template
3. If not found, check grandparent template

This allows child templates to override only specific files.

Common Inheritance Patterns

Pattern 1: Minimal Override

The child template only overrides CSS:

mychildtemplate/
├── template.info.txt    # parent: dokuwiki
└── css/
    └── style.css        # Only CSS changes

Pattern 2: Layout Change

The child template overrides main.php for a different layout but uses all other files from parent:

mychildtemplate/
├── template.info.txt    # parent: dokuwiki
├── main.php            # Different layout structure
└── detail.php          # Custom media page

Pattern 3: Multi-Level Inheritance

grandparent/            # Base template
parent/                 # Inherits from grandparent
child/                  # Inherits from parent

Template Configuration Files

Templates can have their own configuration files similar to plugins.

conf/default.php

<?php
// lib/tpl/mytemplate/conf/default.php
$conf['sidebar_position'] = 'left';
$conf['show_breadcrumbs'] = 1;
$conf['footer_text'] = '';
$conf['logo_url'] = '';

conf/metadata.php

<?php
// lib/tpl/mytemplate/conf/metadata.php
$meta['sidebar_position'] = array('multichoice', '_choices' => array('left', 'right', 'hidden'));
$meta['show_breadcrumbs'] = array('onoff');
$meta['footer_text'] = array('string');
$meta['logo_url'] = array('string');

Settings Override Order

1. Template's conf/default.php (lowest priority)
2. conf/tpl/templatename.local.php (user settings from Configuration Manager)
3. conf/local.php with $conf['tpl']['templatename']['setting'] (highest priority)

Multi-Instance Template Management

When managing multiple DokuWiki instances:

Centralized Configuration

Maintain a base configuration file that is included by all instances:

<?php
// /etc/dokuwiki/base-template-config.php
$TPL_CONF['sidebar_position'] = 'left';
$TPL_CONF['show_breadcrumbs'] = 1;

Then in each instance's conf/local.php:

<?php
require_once('/etc/dokuwiki/base-template-config.php');

foreach ($TPL_CONF as $key => $value) {
    $conf['tpl']['mytemplate'][$key] = $value;
}

Deployment Automation

Use a deployment script to push template configuration changes:

#!/bin/bash
# sync-template-config.sh
for instance in /var/www/html/wiki-*; do
    cp /etc/dokuwiki/userstyle.css "$instance/conf/userstyle.css"
    cp /etc/dokuwiki/template-config.php "$instance/conf/local.d/template.php"
done

Debugging Template Configuration

Check Active Template

<?php
// Add to main.php temporarily to verify
echo '<!-- Active template: ' . hsc($conf['template']) . ' -->';

Verify CSS Loading

Use browser developer tools:

1. Open the page
2. Open DevTools > Elements
3. Check the <head> section for CSS files
4. Verify userstyle.css is loaded after template CSS

Check Configuration Values

Create a temporary info page:

<?php
// Save as data/pages/debug/template.txt
// View at /wiki/debug:template

<code php>
print_r($conf['tpl']);
</code>

Common Mistakes

1. Editing template files directly instead of using userstyle.css: Changes to template files are lost on update. Use userstyle.css for all CSS customizations.
2. Using !important in userstyle.css: If userstyle.css is loaded last, it should have priority without !important. Using !important makes future overrides difficult.
3. Not inheriting from a base template: Writing a template from scratch means you must handle all DokuWiki edge cases. Use inheritance when possible.
4. Overriding settings in multiple places: Settings can be overridden in template config, local config, and instance config. Use one method consistently.
5. Forgetting to test after template updates: Template updates can change configuration option names. Always test after updating a template.

Practice Questions

1. Where is userstyle.css located, and why does it take priority over template CSS?
2. How does template inheritance work, and what field in template.info.txt enables it?
3. What is the override order for template settings (from lowest to highest priority)?
4. Challenge: Create a template Configuration Management system for three DokuWiki instances. The instances share: the same template (inheritance from dokuwiki), a common userstyle.css with brand colors, the same sidebar position (left), and the same breadcrumb settings. Each instance has unique: site title, logo image, and footer text. Design the configuration file structure, write the common CSS and settings, and write instance-specific configurations. Test that each instance displays correctly with its unique settings.

FAQ

Mini Project

Goal: Set up a multi-instance template configuration.

1. Create a child template that inherits from the default template
2. Add userstyle.css that overrides the default colors (custom brand colors)
3. Configure template settings for sidebar position and breadcrumbs via local.php
4. Create a second instance (or simulate by switching configurations)
5. Verify both instances have different logos and footer text
6. Apply a template update (simulate by touching template files)
7. Verify all customizations survive the update

What's Next

Template configuration completes the design layer. Now learn about caching to optimize your wiki's performance.