DokuWiki Caching — Rendering Cache, Cache Clearing, and Performance Tuning

In this tutorial, you'll learn how DokuWiki's caching system works, including the rendering cache, cache types, how to clear caches, configure cache behavior, and performance tuning for faster page loads.

What You'll Learn

• How DokuWiki's caching system works
• Cache types (rendering cache, index cache, template cache)
• Clearing caches manually and automatically
• Configuring cache behavior
• Cache performance tuning
• CDN and browser caching integration

Why It Matters

Caching is the difference between a fast wiki and a slow one. Without caching, DokuWiki parses every page from text to HTML on every request — which can take 200-500ms per page. With proper caching, the same page loads in 20-50ms. For wikis with hundreds of pages and dozens of concurrent users, caching is essential for acceptable performance.

Real-World Use

A wiki with 500 pages and 50 daily editors serves 2,000 page views per day. Without caching, the server CPU runs at 60% during peak hours. After enabling proper caching — rendering cache, template cache, and browser caching — the server CPU drops to 15%. Page load times decrease from 800ms to 100ms. Users report the wiki feeling "instant."

Learning Path

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

How DokuWiki Caches Pages

When a page is requested, DokuWiki:

1. Checks if a rendered HTML cache exists in data/cache/
2. If cached and fresh, serves the cached HTML
3. If not cached or stale, reads the .txt file, parses syntax to HTML, and stores the result in cache
4. The cached copy is reused for subsequent requests

Cache File Naming

Cache files are named based on page ID and a hash of rendering parameters:

data/cache/
├── p/projects_roadmap.12345678.cache    # Rendered HTML
├── i/projects_roadmap.12345678.i        # Index data
└── x/projects_roadmap.12345678.xhtml    # Alternative format

Cache Types

Rendering Cache

The main cache that stores rendered HTML pages. When a page is edited, its rendering cache is invalidated.

Template Cache

Template files are compiled and cached to avoid repeated Parsing. Template cache files are stored in data/cache/tpl/.

Index Cache

The search index (in data/index/) is a form of cache. It is rebuilt by the indexer when pages change.

Plugin Cache

Some plugins maintain their own caches. The Gallery plugin, for example, caches generated thumbnails.

Configuring Cache Behavior

Cache Settings in local.php

<?php
// conf/local.php

// Maximum cache age in seconds (default: 86400 = 24 hours)
$conf['cachetime'] = 86400;

// Disable caching for certain pages
$conf['cache'] = 1;           // 1 = normal caching, 0 = no caching

// Allow caching of HTML output for anonymous users
$conf['allowcache'] = 1;      // 1 = cache for all users

// Template caching
$conf['tpl_cache'] = 1;       // 1 = cache compiled templates

Per-Page Cache Control

Add the following tags to any page to control caching for that page:

~~NOCACHE~~           # Disable caching for this page

Pages with dynamic content (like blog listings or tag clouds) benefit from disabling the cache.

Cache Invalidation

The cache is automatically invalidated when:

• A page is edited and saved
• A template is changed
• A plugin is installed or updated
• The cache time expires

Clearing Caches

From the Admin Panel

1. Admin > Configuration Manager
2. Click "Clear Cache" button

This clears the rendering cache but preserves search index and plugin caches.

From the Command Line

# Clear rendering cache
rm -rf data/cache/*

# Clear index cache (forces full re-index)
rm -rf data/index/*
php bin/indexer.php -f

From a URL

Access the following URL as an admin:

http://yourserver/wiki/admin?page=config&cmd=clearcache

Selective Cache Clearing

To clear cache for a single page, add &purge=true to the page URL:

http://yourserver/wiki/projects:roadmap?purge=true

This forces DokuWiki to re-render that specific page and update its cache.

Cache Performance Tuning

1. Set Appropriate Cache Time

<?php
// For wikis with infrequent changes: longer cache
$conf['cachetime'] = 604800;  // 7 days

// For wikis with frequent changes: shorter cache
$conf['cachetime'] = 3600;    // 1 hour

2. Disable Cache for Specific Pages

Add ~~NOCACHE~~ to pages that change frequently:

~~NOCACHE~~
====== Dashboard ======
{{blog>blog?5}}    # Blog listings change with each new post

3. Enable Gzip Compression

<?php
// conf/local.php
$conf['compression'] = 'gz';     // gz for gzip, bz2 for bzip2
$conf['gzip_output'] = 1;        // Compress HTML output

4. Configure Browser Caching

Set appropriate headers in your web server:

# Apache: enable browser caching
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/html "access plus 1 hour"
    ExpiresByType image/png "access plus 1 month"
    ExpiresByType image/jpeg "access plus 1 month"
    ExpiresByType text/css "access plus 1 week"
    ExpiresByType application/javascript "access plus 1 week"
</IfModule>

# Nginx: enable browser caching
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

CDN Integration

For public wikis, a CDN caches rendered pages at the edge:

<?php
// conf/local.php - CDN configuration
$conf['proxy']['host'] = 'cdn.example.com';
$conf['proxy']['port'] = 80;
$conf['allowcache'] = 1;

Cache Headers for CDN

<?php
// Add caching headers for CDN
$conf['cachetime'] = 3600;
$conf['allowcache'] = 1;

Cache Monitoring

Check Cache Status

View cache statistics by checking the data/cache/ directory:

# Count cached pages
ls data/cache/p/ | wc -l

# Check cache age
ls -la data/cache/p/

# Total cache size
du -sh data/cache/

Identify Uncached Pages

Pages that frequently miss the cache are candidates for optimization:

• Pages with ~~NOCACHE~~ tag
• Dynamic pages (blog listings, tag clouds)
• Pages that change very frequently

Common Mistakes

1. Clearing the entire cache too often: Each cleared cache means all pages must be re-parsed. Only clear cache when necessary.
2. Disabling cache globally: Setting $conf['cache'] = 0 kills performance. Use ~~NOCACHE~~ for specific pages instead.
3. Not configuring browser caching: Server-side caching helps, but browser caching eliminates repeat requests entirely. Configure both.
4. Using CDN with dynamic pages: CDNs cache static content effectively but may cause stale content for pages that change frequently. Configure appropriate TTLs.
5. Ignoring plugin cache: Some plugins maintain separate caches. If a plugin's output is stale, try clearing its specific cache.

Practice Questions

1. How does DokuWiki's rendering cache work, and what triggers cache invalidation?
2. What is the difference between the $conf['cachetime'] setting and the ~~NOCACHE~~ tag?
3. How would you configure DokuWiki to cache pages for 24 hours, disable caching for a dashboard page, and enable browser caching for static assets?
4. Challenge: Design a caching Strategy for a wiki that has: 10 pages updated daily (meeting notes, status reports), 50 pages updated weekly (documentation, guides), 200 pages updated monthly (reference, archives), 500 pages that rarely change (policies, historical records). For each group, specify the cache time, any special tags needed, and the browser caching strategy. Implement your strategy and measure the cache hit rate before and after.

FAQ

Mini Project

Goal: Implement and measure a caching strategy.

1. Measure baseline page load time for 5 pages (use browser DevTools)
2. Configure DokuWiki cache: set $conf['cachetime'] = 86400 (24 hours)
3. Enable gzip compression: $conf['gzip_output'] = 1
4. Configure browser caching for images, CSS, and JS
5. Add ~~NOCACHE~~ to one page that shows dynamic content
6. Measure page load times again after caching
7. Calculate the improvement (before vs after)
8. Clear the cache and measure the first load after clearing
9. Document your caching configuration and results

What's Next

Caching makes your wiki fast. Now learn about SEO configuration to make your wiki discoverable on search engines.