It's better when it's simple

User Tools

Site Tools


DokuWiki Nav Overlay Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Creates floating window at the template level that can be toggled open and closed into which navigation plugins (or any other pages) can be inserted. Can be configured for multiple namespaces, each with its own overlay.

Last updated on


Search and install the plugin using the Extension Manager will install the plugin plus the css for several popular navigation plugins. Refer to Plugins on how to install plugins manually.

The remainder of the install may require modification of your template as described below.


This was initially designed as facilitator for navigation plugins. But, it could be used to insert a floating window on top of your template for any purpose. This window could replace the sidebar. The overlay window is both draggable and resizable:

start resizemid resize

To drag, click and hold anywhere inside the window. To resize, click and hold any of the seven square handles; the resize tool tip will pop up. As the resize is in process, a dotted outline marks out the new size, which is set when you release the mouse button.

How To

Overlay Types

Default Overlay

The plugin comes pre-configured to use wiki:nav as the page where the default overlay content should be placed. You can, if you wish, change this in the configuration settings. This is the default overlay.

Namespace Overlays

It is also possible to create namespace overlays. These are wiki pages which will be used for the overlay instead of the default content. To implement this feature, you must set the relevant namespaces in the Configuration Manager. Then, when a page is accessed in that namespace, the namespace overlay for that namespace will pop-up instead of the default overlay. See other_options.

User Overlays

These enable overlays that display content for a particular user. These overlays take precedence over both the default and the namespace overlays. The pages for these overlays can have one of two implementations: overlay:user or user:overlay. The plugin first looks in the overlay namespace and then in the user namespace. This means that if you have a user named john, the plugin first looks to see whether there is a page named overlay:john. If it doesn't find overlay:john, it then looks for john:overlay. A user overlay takes precedence over both the default and namespace overlays.

Order of Precedence

  1. overlay:user
  2. user:overlay
  3. namespace overlay
  4. default overlay

Default Dokuwiki Template

If you are using the default dokuwiki template, the plugin will automatically insert a link to toggle the overlay open and closed. Go to the overlay configuration options and choose the placement of your toggle. It can be placed as a link in either the User Tools or the Site Tools section of the header. Or it can be placed as a button in the row of Page Tools buttons on the right of the window. You can also have the overlay open automatically during selected actions. It can always be closed using the “toggle” or from the overlay's own menu bar. (See the options described below.)

The display name for the link or button created by the overlay plugin is set in lang/<your_lang>/lang.php using the $lang['toggle_name'] setting. The English default is Index. Any other language strings are also set in your lang.php.

Alternate Templates

If you are using Dokuwiki Detritus or later, you can insert either a link or a button using the following php syntax:

  tpl_toolsevent('ovltools', array());

Place this code where you want your link or button to appear. Whether you get a link or a button will depend on the toggletype configuration option. You can style the link or button using the css in overlay/style.css, where you will find two place-holders:

/* mark  settings here as !important.  For instance,  color: green !important; */
button.overlaytools {}
a.overlaytools {}

The tpl_toolsevent() is now deprecated. Therefore, if you are using a current template that no longer supports the tpl_toolsevent() function, then you can insert your own link or button into your template. Use one of the following:

<a href="javascript:jQuery('#overlay').toggle();void(0);" rel="nofollow" title="Index">Index</a> 
<button onclick="jQuery('#overlay').toggle();void(0);">Index</button>


In plugins/overlay, you will find a script.css file. You can change the initial position of the window on the screen, its size, border, etc. The size can also be changed using Configuration Options.

The overlay window cannot be resized by grabbing the Windows handle at the lower right corner. Instead you must use its own resize handles, the boxes at corners and sides. These are defined as follows and can be modified using css:

              handles: {
                  'nw': '#nwgrip',
                  'ne': '#negrip',
                  'sw': '#swgrip',
                  'se': '#segrip',
                  'n':  '#ngrip',
                  'e':  '#egrip', 
                  'w':  '#wgrip'

n, e, and w are the top and sides, the others are the four corners. They can be modified using css. If for instance, you don't want the top and sides, you can place the following css in conf/userstyles:

  div#overlay #egrip, #ngrip, #wgrip {
     visibility: hidden;


If you use the indexmenu plugin, in style.css you should change the one instance of __missing__ to __existing__:

/* Namespace without page link in nojs mode. !important has to be used */ a.indexmenu_idx {
    color: __missing__ !important;

Also, you should set the overlay page to NONE for @ALL; otherwise, if the reader goes to the overlay page, the menu will show two menu listings separated by an error message.

Configuration Options

Using the configuration options, it is possible to select during which actions the overlay should be automatically displayed. The default is to hide the overlay for all actions initially. It can always be opened using the link or button that toggles it open and closed.


Initially hide the overlay during the following actions

Option Description Type Default
admin accessing the admin panels boolean true
profile updating profiles boolean true
recent accessing recent changes boolean true
revisions reviewing revisions history boolean true
backlink viewing backlinks boolean true
login during logins boolean true
index accessing the sitemap boolean true
media opening media window boolean true
register new registrations boolean true
edit during edits boolean true
always Always boolean true

The overlay window can always be activated from the toggle button or link. However, it's possible to set when you want it to automatically pop up. This is done by setting the boolean values in the above group of options, which determine whether the overlay window should pop up during a particular DokuWiki action.

  1. If the option is set to false, the overlay will pop-up during the action in question.
  2. always means always initially hide the overlay. If always is set to true, then all of the others can be false. It will never pop up automatically.
  3. If all of the other actions are set to true, but always is set to false, then the overlay window will pop up when the page is simply being viewed.

Other Options

Option Description Type Default
page page containing overlay data [namespace:pagename] string wiki:nav
menutype Where to place toggle multi-choice: user, site, page user
nsoverlays Comma separated list of namespaces where alternate overlay content will be found; the pagename holding that content must be called overlay. If the namespace identifier ends with an asterisk, it governs all child namespaces unless a specic namespace overlay is specified string <empty>
tools Which action links to insert in top menu bar multi-checkbox: login,admin,revisions,profile login,admin
width Width in pixels of the overlay window string <empty>
height Height in pixels of the overlay window string <empty>
toggletype Link or button for toggling overlay in alternate templates multi-choice: button or link button



The page is the DokuWiki page where you have your data for the overlay. It defaults to wiki:nav but can be any valid page. If no page is specified, then there will not be an overlay window. The overlay plugin contains the css needed for the simplenavi plugin and can also be used with indexmenu with a small optional modification (see above).

The menutype option applies to the current default dokuwiki template which has three places to insert links or buttons. These are the Page Tools, the Site Tools, and the User Tools. The Page Tools are the icons that run along the right side of the DokuWiki template. The User Tools are admin, login, etc. The Site Tools are recent, media, index. If you do not have a template which supports these tool sets, you will have to insert your own toggle as described above.


The pages for nsoverlays must be named overlay. When a page from one of these namespaces is accessed (i.e. namespace:page), the overlay window will be filled with the content found in namespace:overlay. To create an overlay page that applies to all subdirectories of a namespace, add an asterisk to that namespace (namespace*); then its overlay will apply, unless the current namespace has its own overlay page.


The tools option enables insertion of standard action links in the toolbar at the top of the overlay window. If you need actions that are not included in the choices, they can be entered in the textbox, separating multiple entries with commas. You may have to increase the width of the overlay window when inserting multiple links.

width and height

width and height are given default values in style.css: 325px (H), 250px (W). You can change these either in style.css itself or by using these options in the Configuration Manager. But neither of these values can be smaller than 200px.


toggletype: If you are using a version of Dokuwiki beginning with Detritus but are not using the default dokuwiki template, you can insert your own toggle button or link as described above. This option enables you to choose whether you want a button or a link.



Please use the issues page at github or the forum.

plugin/overlay.txt · Last modified: 2023-10-30 22:33 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki