DokuWiki Offline Plugin

Description

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 others1).

See download section for available versions.

Features

  • 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

Requirements

  • 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.

Security concerns

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!

Download

Installation

Disclaimer

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.

Prerequisites

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.
  2. zip for creating a single archive file that contains all wiki pages, media files and additional stuff.
  3. unzip for testing a freshly zipped archive. This program is only needed if you specify the option T in the configuration parameter archiverOptions.

Installation steps

  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

Configuration

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.

template

The template to use for offline files.

dokuwikiProtocol

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'.

dokuwikiHost

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'.

dokuwikiRelativePath

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.

wgetPathToBinary

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:

Program Path to binary
wget /opt/local/bin/wget

wgetHttpUser

.htaccess user.

wgetHttpPasswd

.htaccess password.

archiverPathToBinary

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

This is what the output could look like:

Program Path to binary
zip /usr/bin/zip
bzip Not installed.
gzip /usr/bin/zip
rar Not installed.
tar /usr/bin/zip

archiverOptions

Options for the archiver.

insertLinkBackToHome

Insert Link to start page.

  • Not used yet.

writeLogFile

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

Creating an 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.

Create offline version right away

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

Simulate creation with dryrun parameter

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.

Directory structure

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.

Support

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

For developers

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

Known issues

  • 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.

Future enhancements

  • 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

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

1) Provided they have a browser installed.
 
start.txt · Last modified: 2009/02/09 10:17 by admin
 
Except where otherwise noted, content on this wiki is licensed under the following license:CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki