DokuWiki Offline Plugin

This is a plugin for DokuWiki. This plugin creates a static HTML version of your DokuWiki website. The static version will be browseable offline, i.e. without a connection to the server that hosts the wiki. All internal links will still work. External links will be preserved, so they will function when you are online again.

This way you can take your entire DokuWiki website with you and read it on your mobile phone, pda and others¹⁾.

See download section for available versions.

• Creates a single archive file that contains all your DokuWiki pages
• Contains internal media (e.g. uploaded images or pdf files)
• Works on .htaccess-protected websites
• Can be run via cron job
• Preserves the hierarchical directory structure (if your wiki uses namespaces)
• Creates an alphabetical index of all wiki-pages
• Supports a dryrun mode which simulates the creation of a offline version without actually doing so
• All actions are logged and can be reviewed in detail afterwards

• DokuWiki installation (successfully tested with 2008-05-05, 2007-06-26b and rc2009-01-30)
• Admin privileges to your DokuWiki installation

In addition, Dokuwiki Offline Plugin relies on two external programs:

1. wget for downloading the wiki pages.
2. zip for creating a single archive file that contains all wiki pages, media files and additional stuff.

Operating Systems

• DokuWiki Offline Plugin was developed and tested under a Mac OS X 10.5 and Windows XP.
  But it should work on other Unix like file systems and under different Windows versions as well.

More of an academical nature, but they should be mentioned here.

• If your DokuWiki installation is protected by a .htaccess password you have to fill in both the user name and the password fields in the Admin configuration page. After saving the settings the values will be stored uncrypted in the config file . So, anybody who has access to the config file will be able to see these credentials.
• Some configuration parameters such as path to wget or path to archiver and archiver options will be executed on the server's shell without further examination of the parameters. So if someone gains access to these options, he could easily shred valuable data!

offline_plugin.zip (~38 kB)

Though this plugin has been tested thoroughly I have to mention the usual disclaimer:

• DokuWiki Offline Plugin comes with no warranty!
• Use at your own risk.
• Make a backup before using this plugin.

So for the brave ones: Make sure you have these two additional programs installed. They not come with your DokuWiki installation or your web server but depending on the operating system you are using the might already be installed.

1. wget for downloading the wiki pages.
   • For Max OS X: Install conveniently using Darwin ports or compile it yourself.
   • For Windows: http://gnuwin32.sourceforge.net/packages/wget.htm
     Choose the Complete package, except sources with Setup program.
2. zip for creating a single archive file that contains all wiki pages, media files and additional stuff.
   • For Windows: http://gnuwin32.sourceforge.net/packages/zip.htm
     Choose the Complete package, except sources with Setup program.
3. unzip for testing a freshly zipped archive. This program is only needed if you specify the option T in the configuration parameter archiverOptions.
   • For Windows: http://gnuwin32.sourceforge.net/packages/unzip.htm
     Choose the Complete package, except sources with Setup program.

1. Unzip the file offline_plugin.zip into your plugin directory.
   This should result in a new directory offline beneath your lib/plugins/ directory.
2. Make sure there is a directory called tmp in your data directory:
   data/tmp
3. Make sure the tmp directory is writable by the web server.
   If you do not exactly know how to accomplish this elegantly, open a shell and change to the root directory of your DokuWiki installation. Then execute the following command :
   chmod 777 data/tmp

To configure the plugin's behaviour enter the admin panel and then click on configuration.

Before you run the Offline Plugin for the first time you should make sure that the pats to wget and zip are correct.

The template to use for offline files.

Protocol prefix ('http' or 'https').
In most of the cases this is 'http'. Only if your website's HTTP traffic is encrypted by method of an SSL certificate you have to choose 'https'.

The name of the server on which DokuWiki is hosted.

Example:
For 'http://www.ocean-dreams.com/categories/octogarden/' this would be 'www.ocean-dreams.com'.

The relative path from your web server's docroot to the DokuWiki installation (do no use leading or traling (back-) slashes)!).

Example:
For 'http://www.ocean-dreams.com/categories/octogarden/' this would be 'categories/octogarden'.

Please note that '/categories/octogarden', 'categories/octogarden/' or '/categories/octogarden/' would be wrong.

Path to executable wget file.

Of course this depends on your server's configuration and differs. This could be something like /opt/local/bin/wget on Unix-like machines or E:\programme\GnuWin32\bin\wget.exe on Windows. On Linux or modern Macs you can use the commands which wget or locate wget to find out where your wget installation resides.

If your are not sure about the path you can use the helper program
http://YOUR-SERVER/YOUR-DOKUWIKI-NAME/lib/plugins/offline/which_binaries.php

This is what the output could look like:

.htaccess user.

.htaccess password.

Path to executable archiver file (e.g. '/usr/bin/zip').

• This field must contain a full path to an archiver that is already installed on your host.
• If your are not sure about the path you can use the helper program
  http://YOUR-SERVER/YOUR-DOKUWIKI-NAME/lib/plugins/offline/which_binaries.php

This is what the output could look like:

Options for the archiver.

Insert Link to start page.

• Not used yet.

Create log file (slows backup down. Only recommended if errors occur while creating offline version).

You can either use the plugin right away as it comes out of the box or you can simulate the creation of a static html version.

You can trigger the creation of an offline version in two ways:
Either execute the script via browser or run the script via cron job.

• Via browser:
  

  http://YOUR-SERVER/YOUR-DOKUWIKI-NAME/lib/plugins/offline/create.php

• Via cron:
  
  • Without .htaccess protection:
    

    00 20 * * *  (wget http://YOUR-SERVER/YOUR-DOKUWIKI-NAME/lib/plugins/offline/create.php)

  • With .htaccess protection:
    

    00 20 * * *  (wget --http-user="USERNAME" --http-passwd="PASSWORD" http://YOUR-SERVER/YOUR-DOKUWIKI-NAME/lib/plugins/offline/create.php)

• You can download the offline archive from the following location:
  

  http://YOUR-SERVER/YOUR-DOKUWIKI-NAME/lib/plugin/offline/offline.zip

If you are anxious about accidently deleting data on your server by using this plugin you can use the dryrun option. Just call the script create.php with the following parameter and value offlineMode=dryrun for example:

http://YOUR-SERVER/YOUR-DOKUWIKI-NAME/lib/plugins/offline/create.php?offlineMode=dryrun

The parameter can be added to the URL in both of the above mentioned invocation methods:
It makes no difference whether the script is called via browser or via cron job.

In dryrun mode the script create.php simulates the whole offline version creation process. In addition debugging information will be output only to the screen. Neither files or directories are being created, renamed, archived or deleted.

You can take your time and examine all actions performed by the plugin in detail. You can check paths, file names and the like. Finally, when you feel comfortable with the plugin's behaviour, you can call the script without the parameter offlineMode.

Your offline version will use the following directory hierarchy:

  /offline
  +- pages
  +- media
  +- css
  +- index
  |  +- alphabetical.html
  +- index.html

You can start browsing it by opening the file index.html in the root directory of the folder offline.

I coded this plugin in my spare time and for my purposes. Since I do appreciate Andreas Gohr's work very much and since I know that other people did also did ask for an offline plugin I provide it to you without asking for money. But, please understand that I cannot provide support of any kind. Of course I will try to fix bugs as soon as possible.

For discussion, hints and critic please use the plugin page
http://www.dokuwiki.org/plugin:offline

• Based on plugin s5 and renderer xhtml
• All paths are defined without a trailing slash (or backslash on Windows systems)

• The table of contents which usually shows up in the wiki page is not included in the offline files.
  I'm open for any hints how to achieve this.
• For very very large wikis the PHP interpreter might run out of memory.
  So far this happened only once and the script was optimized immediately. Anyway, if you should encounter this problem again please let me know.

• Exclude certain media files when creating the offline archive.
  This could be specified through filenames, file extension or file size.
• Retrieval of external pictures/media.

Thanks to Robert Peake for suggesting a recursive directory retrieval function (see source code for further details)