DokuWiki Plugin System — Plugin Structure, Events, Hooks, and Extension Points

In this tutorial, you'll learn how the DokuWiki plugin system works, including plugin directory structure, the plugin.info.txt manifest, events and hooks, and the three plugin types (syntax, action, and admin).

What You'll Learn

• How plugins extend DokuWiki functionality
• Plugin directory structure and the plugin.info.txt manifest
• Event system and hook registration
• Syntax plugins, action plugins, and admin plugins
• Plugin lifecycle (install, enable, disable, uninstall)
• Using the Extension Manager

Why It Matters

Plugins are how you add functionality to DokuWiki that is not included in core. Understanding the plugin system lets you choose the right type of plugin for each task. When you need to modify DokuWiki's behavior — whether adding a new syntax element, integrating with an external service, or adding an admin interface — the plugin system is the supported way to do it.

Real-World Use

A development team needs to add a custom syntax tag [[server:hostname]] that links to their internal monitoring dashboard. They create a syntax plugin that registers the new tag, parses it during page rendering, and generates a link. The plugin is installed via the Extension Manager, enabled immediately, and works without modifying any core files. When they upgrade DokuWiki, the plugin continues to work.

Learning Path

flowchart LR
  A[Spam Protection] --> B[Plugin System]
  B --> C[Essential Plugins]
  C --> D[Custom Plugins]
  D --> E[Plugin Configuration]
  E --> F[Plugin Security]

Plugin Directory Structure

Each plugin is a subdirectory under lib/plugins/. The directory structure:

lib/plugins/
├── pluginname/              # Plugin directory (lowercase, no spaces)
│   ├── plugin.info.txt      # Plugin manifest (required)
│   ├── action.php           # Action plugin class
│   ├── syntax.php           # Syntax plugin class
│   ├── admin.php            # Admin plugin class
│   ├── helper.php           # Helper plugin class
│   ├── lang/                # Language files
│   │   ├── en/
│   │   │   └── lang.php    # English translations
│   │   └── de/
│   │       └── lang.php    # German translations
│   ├── conf/                # Plugin configuration
│   │   ├── default.php     # Default configuration values
│   │   └── metadata.php    # Configuration metadata
│   └── style.css           # Plugin styles (optional)

A plugin does not need all these files — only what the plugin needs.

The plugin.info.txt Manifest

Every plugin must have plugin.info.txt in its root directory:

base    myplugin
author  Your Name
email   your@email.com
date    2026-06-28
name    My Plugin
desc    Description of what my plugin does
url     https://example.com/myplugin

Fields

Plugin Types

Syntax Plugins

Syntax plugins extend DokuWiki's markup language. They register new syntax patterns that are parsed during page rendering.

Example use cases:

• Custom tags ([[server:hostname]])
• Mathematical formulas ($$ formula $$)
• Charts and diagrams
• Embedded content from external services

Syntax plugins implement the DokuWiki_Syntax_Plugin class and specify where in the Parsing Process they should be applied.

Action Plugins

Action plugins hook into DokuWiki events. They can modify behavior at specific points in the request lifecycle.

Example use cases:

• Sending notifications on page save
• Logging page views
• Modifying the page content before rendering
• Adding custom buttons to the toolbar

Action plugins implement the DokuWiki_Action_Plugin class and register event handlers.

Admin Plugins

Admin plugins add pages to the admin menu. They provide administrative interfaces for configuration and management.

Example use cases:

• Custom configuration interfaces
• Data export/import tools
• System health checks
• Usage statistics dashboards

Admin plugins implement the DokuWiki_Admin_Plugin class.

Helper Plugins

Helper plugins provide reusable functions for other plugins. They do not have a user-facing interface.

Example use cases:

• Database abstraction
• API clients
• Caching utilities

Helper plugins implement the DokuWiki_Plugin class directly.

Event System

DokuWiki has an event system that allows plugins to hook into specific actions.

Available Events

Common events that plugins can hook into:

Registering Event Handlers

In the plugin's action.php:

<?php
class action_plugin_myplugin extends DokuWiki_Action_Plugin {

    public function register(Doku_Event_Handler $controller) {
        $controller->register_hook(
            'COMMON_PAGE_SAVE',
            'BEFORE',
            $this,
            'handle_page_save'
        );
    }

    public function handle_page_save($event, $param) {
        // $event->data contains page information
        $pageId = $event->data['id'];
        $content = $event->data['content'];
        // Do something before the page is saved
    }
}

Plugin Lifecycle

Installation

1. Download the plugin to lib/plugins/pluginname/
2. Or use the Extension Manager to install from URL
3. The plugin is disabled by default after installation

Enable/Disable

Use the Extension Manager to enable or disable plugins:

1. Admin > Extension Manager
2. Find the plugin in the list
3. Click "Enable" or "Disable"

Enabling a plugin makes its functionality available immediately.

Update

1. Download the new version
2. Replace the plugin directory
3. Refresh the Extension Manager

Uninstall

1. Disable the plugin in Extension Manager
2. Delete the plugin directory from lib/plugins/
3. Remove any plugin configuration from conf/plugin/

The Extension Manager

The Extension Manager is available at Admin > Extension Manager. It provides:

• Plugin list: All installed plugins with status (enabled/disabled)
• Plugin search: Browse the DokuWiki plugin repository
• Install: Install plugins by URL or from uploaded ZIP
• Update: Check for and apply plugin updates
• Enable/Disable: Toggle plugin status
• Info: View plugin details and version info

Plugin Configuration

Plugins can have their own configuration settings, stored in conf/plugin/pluginname/.

Default Configuration

<?php
// conf/default.php
$conf['setting_name'] = 'default_value';

Configuration Metadata

<?php
// conf/metadata.php
$meta['setting_name'] = array('string');  // String setting
$meta['number_setting'] = array('numeric'); // Numeric setting
$meta['bool_setting'] = array('onoff');    // Boolean setting

Common Mistakes

1. Creating a plugin when a configuration change would work: Before writing a plugin, check if the desired behavior can be achieved through configuration or ACL settings.
2. Not using the Extension Manager: Manually downloading and extracting plugins works, but the Extension Manager handles dependencies and version checks automatically.
3. Modifying plugin files directly: Changes to third-party plugins are overwritten on update. Fork the plugin or create a new plugin that extends it.
4. Writing a syntax plugin when an action plugin is needed: Syntax plugins handle custom markup; action plugins handle events. Choose the right type for your use case.
5. Ignoring language files: Hard-coding strings in English prevents localization. Use language files for all user-facing text.

Practice Questions

1. What are the four types of DokuWiki plugins, and what is each one used for?
2. What information must be included in the plugin.info.txt manifest file?
3. How do events work in DokuWiki, and how does an action plugin register to handle an event?
4. Challenge: Create a simple plugin that logs every page save to a separate log file. The plugin should: register for the COMMON_PAGE_SAVE event, log the page ID, editor username, and timestamp to data/log/page-saves.log, and have a plugin.info.txt manifest. Install the plugin, enable it, and verify that page saves are logged correctly.

FAQ

Mini Project

Goal: Install and analyze three different types of plugins.

1. Install a syntax plugin (e.g., the Gallery plugin for image galleries)
2. Install an action plugin (e.g., the Blog plugin)
3. Install an admin plugin (e.g., the Configuration Manager plugin or similar)
4. For each plugin, examine:
   • The plugin.info.txt file
   • The directory structure
   • The type (syntax, action, admin, or helper)
   • The configuration options
5. Enable each plugin and test its functionality
6. Document the purpose and capabilities of each plugin

What's Next

Now you understand the plugin system. Explore essential plugins that extend DokuWiki for blogs, discussions, galleries, tags, and forms.