DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin_installation_instructions

Plugin Installation Instructions

Find the plugin you want to install on the list of plugins and read the plugin's description carefully. Then refer to the details below to install it.

Automatic Installation

Most plugins can be installed automatically using the extension manager (since Ponder Stibbons). The extension manager lets you search and directly install a plugin by clicking the “Install” button. This is by far the quickest and least error prone way to install plugins. Refer to instructions for using the extension manager.

There are some circumstances where it is not possible to use the extension manager to install a plugin:

  • ACL is not enabled. The extension manager is accessed via the admin menu which makes it only available on wikis with ACL enabled. Even in a completely public wiki it can be worth enabling ACL to gain access to DokuWiki's admin functions, like the extension manager.
  • No plugin package. The extension manager requires a specially prepared archive containing the plugin files.
  • The webserver doesn't have write access to DokuWiki's lib/plugins directory. The extension manager needs to be able to add the new plugin to this directory.
  • Developers building their own plugins from scratch. Developers should read about plugin file structure.

In these circumstances its necessary to install plugins manually.

Manual Instructions

Direct access to server filesystem

  • Download the extension and unpack it into lib/plugins/<base-plugin-name>.
  • The base name of the plugin can be found in plugin.info.txt
    (e.g. for the gallery plugin its defined by the line base gallery)

Or Using FTP

These instructions assume that you don't have console access to your server and will need to upload the files using FTP or the file manager in your server's control panel.

With a Plugin Package File

  1. If the plugin has a package file, download that file to your computer. If the plugin comes in different formats, choose the one that fits you best (Windows user will prefer zip).
  2. Expand (i.e. unzip) the package (See unpacking for some help and utilities). That should give you a directory named after the plugin. Inside that directory you will see files or directories named for the type of plugin (e.g. syntax.php or /syntax/).
    • Note: some decompression software will place all the decompressed files in a directory named after the original archive file. If that is the case you will need to move up one directory to find the directory named for the plugin. This could get confusing if the archive file actually has the same name as the plugin too!
    • Note: Many plugin authors host their plugins at github and let github automatically create a ZIP file from the most current check in. These automatically created archives usually contain the wrong foldername. You need to rename the folder to the correct name.
      Example: unpacking the Gallery Plugin will result in a folder name like splitbrain-dokuwiki-plugin-gallery-169c0bb – you need to rename it to gallery.
      Hint: in the file plugin.info.txt you could find the base name (e.g. base gallery)
  3. Using your file uploader (e.g. FTP or your Control Panel File Manager), on the server navigate to DokuWiki's lib/plugins directory and upload the plugin directory you just created (on your computer) along with all its contents. The end result should be a new directory on the server, lib/plugins/<new-plugin-name>, containing the files and directories of the plugin.

The plugin is now installed.

Without a Plugin Package File

Installing a plugin without a package is still quite straightforward, especially for simple plugins that consist of only a few files. However there are more ifs and buts and greater familiarity with DokuWiki and PHP maybe required if some crucial information is not clear from the plugin documentation. Actually making a plugin package is very easy, so if you are totally unfamiliar with PHP it may be worth dropping the plugin author an email politely asking if they can email you the plugin package or at least clarifying the exact name to use for the plugin.

For those familiar with PHP, check out the plugin pages in the developer section, in particular the plugin file structure.

These instructions assume the author has pasted the code required for the plugin on a web page, where the code for each file is clearly identifiable along with the name for each file.

  1. Create a directory on your computer and name it after your plugin. The name is important, it should match part of the “class” name used in the plugins files.
  2. For each file used by the plugin, start a new file in a plain text editor (e.g. notepad), copy the contents from the web page and paste them into the editor ensuring there are no additional blank lines at either the top or the bottom (this can be quite important for .php files) and save the file with the appropriate name in the plugin's directory. If the author has indicated a file needs to be in a sub-directory, create that sub-directory before saving the file.
  3. After all the files are created, using your file uploader (e.g. FTP or your Control Panel File Manager), on the server navigate to DokuWiki's lib/plugins directory and upload the plugin directory you just created (on your computer) along with all its contents. The end result should be a new directory on the server, lib/plugins/<new-plugin-name>, containing the files and directories of the plugin.

The plugin is now installed.

Troubleshooting

If the plugin doesn't seem to work, check the FAQ on plugin problems.

plugin_installation_instructions.txt · Last modified: 2023-10-02 07:39 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