Table of Contents

Configuring Dokuwiki

Here we list a couple of starting configuration settings that we deem would make the wiki more production ready. The term config in this page usually refers to the configuration page itself, found under the admin panel. Documentation for specific configuration fields can typically be found in the Dokuwiki configuration page.

To explore the large Dokuwiki universe and support links, head on to the about page.

Customize defaults

Set the following configuration fields, optimized for semi-private wikis:

The favicon can be overridden by uploading :favicon.ico file to the Dokuwiki media root (preferably in multiples of 16x16px), while the logo can be overridden in the default template by uploading :logo.png within the same root namespace (preferably 50x50px).

Modify default descriptions

The default Dokuwiki descriptions, e.g. the text above the page editor, are stored within the Dokuwiki directory, and can be edited by the webserver admin. The files are located in /inc/lang/[LOCALE]/[DESCRIPTION_FIELD].txt, as referenced by the following forum post.

Note that some descriptions are template-specific, e.g. the footer text of the default template is located at /lib/tpl/dokuwiki/tpl_footer.php.

Best practices for editing descriptions

The locale description files do not follow the standard Dokuwiki [FILE].local.[EXT] convention for user definitions. To ensure these changes survive Dokuwiki upgrades, a good practice (applied on the edit.txt file as example):

  1. Create a backup of the original text: edit.txt.orig
  2. Edit the description: edit.txt
  3. Create a backup of the modified text: edit.txt.bak

Decide content organization

Dokuwiki content has a similar hierarchy as that of a filesystem - pages (text files) reside in nested namespaces (directories). There are many ways to classify content, but note the following conflict between namespace classification strategies:

  1. Empirical (property-based): Permissions (via ACL) can be granted on namespace-basis
  2. Functional (topic-based): Natural grouping, i.e. by functional criteria or subject
  3. Flat: Only meta-content (about the wiki and its administration) are given namespaces, e.g. Wikipedia

To incorporate both policies, the namespace system used in this wiki is as follows: 

root
+-- [group]
    +-- [topic]
        +-- ...
            +-- [content]

To circumvent restrictions on strict hierarchical categorization, the tag plugin can be used to assign tags for common categories, such as type of record (e.g. meeting, thoughts), subject, meta-tags (e.g. important), organization, etc. A virtual namespace containing the associated tag can then be created to browse by tags.

Add ACL rules

Read the section on content organization above first, before implementing ACL rules.

The principle behind Dokuwiki's ACL is similar to Nginx's access permissions - the rule with greatest specificity (user > group; page > namespace > root namespace) are applied. The easiest way to understand these rules is to review the ACL example scenario in the documentation.

These rules can be edited under the Access Control List Management page in the admin panel. This also involves editing the groups each user belong to, under the User Manager page in the admin panel. Note that guests are part of the @ALL group, while registered users are by default automatically in the @user group.

Edit the sidebar

A basic sidebar can be created with the following steps:

  1. Ensure the sidebar config field is populated, e.g. mysidebar.
  2. Create the corresponding mysidebar page in the root / namespaces and edit the page text. This text will be immediately reflected in the sidebar.

Multiple sidebar pages can exist, with each page resolving to closest sidebar page along the parent namespace path. For a quick and dirty sidebar, embed the entire sitemap in the sidebar page using the simplenavi plugin, i.e. **Sitemap** \\ {{simplenavi>}}.

More details on customizing the sidebar can be found in the FAQ.

Add features via plugins

Plugins allow easy extension of the base Dokuwiki installation to provide additional features or enhance user experience. Common plugins are primarily classified into syntax plugins that can be used in pages, and action plugins that supplement Dokuwiki functionality. Some useful plugins are listed below.

Syntax plugins

Action plugins

Review plugin source code before installation

Plugins inject code into your Dokuwiki installation, which can be potentially rogue, especially for plugins that are less used/reviewed or requires manual installation. It is always good practice to review the source code before installation to minimize potential security impacts, especially for lesser-known plugins that fulfill a particular niche.

Keep list of installed plugins small

Plugins can inadvertently introduce vulnerabilities. The less plugins you install, the smaller the attack surface of your wiki. This also reduces barriers when reviewing plugins for feature/security upgrades.

Older (deprecated) plugins

Change look-and-feel using templates

Dokuwiki can optionally be customized through the use of templates (although the default template is arguably the best in terms of plugin compatibility and content presentation). Some suggested templates to explore:

Manual CSS overriding

The formatting of the templates can be manually overridden, using the styles specified below in increasing specificity:

The GeSHi syntax parsing definitions for the desired language can be found in /vendor/geshi/geshi/src/geshi/*.php. See Dokuwiki's provided list of code CSS overrides for examples. The CSS overrides for this wiki are documented here.

Other tips