Learn about DokuWiki
Learn about DokuWiki
epub is a plugin that will create EBooks from Dokuwiki pages that can be read in standard ebook readers. See ebook_readers below.
EPUB is an open specification for digital books based on XML, CSS, and XHTML, and EPUB files can be read on portable e-ink devices, mobile phones, and desktop computers. The specification is overseen by the International Digital Publishing Forum.
Unlike pdf files which have a standardized output, epub output is e-reader dependent, much like web pages, to which they are directly related. An epub page is XHTML with CSS styling. Ebooks can be collected in an e-reader's library of e-books and consulted off-line, making them always available.
Install using the plugin manager or a manual install.
The plugin has recently been upgraded to conform to epub naming conventions, which does not allow
@ signs in ids. The most recent distributions substitute underscores for the earlier
@ signs. Should this cause any problems, you can revert to the earlier version: turnermm-epub-b111076.tar.gz. If this occurs, please report an error.
The epub plugin keeps a link on the page where the ebook has been created. This link is updated every time the book is updated. ACL rules apply. So, for this to work, users and/or visitors must have read access to the page. See below configuration and settings. There is an administration panel where the administrator can prune the cache that keeps track of these links and the pages on which they appear, as well as enabling the admin to delete epubs no longer in use when entries are deleted from the cache. While deletions from the cache can be done on a page-by-page basis using the Remove button (see configuration and settings), the admin panel provides a systematic view of the status of the epubs on your system.
There is also a configuration option which allows for hiding the link. This version also has the capacity to delete the working directories in data/cache, where the epubs are created; this facility is controlled also by a configuration option.
eBooks are zip files with the '.epub' extension. So, in order to create ebooks the plugin will have to be able to create zip files. The epub plugin will first look for the PHP ZipArchive class; if it doesn't find it, on Linux systems, it will try to use the command line
zip utility. This is not found on Windows systems. The ZipArchive class can usually be downloaded as a .dll and easily installed on Windows by updating the extensions assignments in php.ini. It can also be installed on *nix systems using a package manager like yum or apt-get or directly from a GUI software installer. But my experience has been that the PHP version has to be 5.2 and above.
If epub does not find either the ZipArchive class or a working copy of the zip utility, it will use Dokuwiki's own ZipLib class.
Open a page in the namespace named “epub”. Then create a list of pages as follows, in the order in which you want them to appear. The page names can be inserted using the link wizard on the Dokuwiki toolbar (these are in the square brackets).
<epub:Book-1> introduction v06 features [[index:site_inx|index]] media [[:configuration|]] docs:upgrade_6 </epub>
Book-1 is the title of the ebook. It is the name that the book will be known by in ebook readers. There is also an author, whose name is taken from the user's actual name as it was entered upon the user's registration.
When the page is saved a Start button will appear on the page. When it's clicked a throbber comes up, which will disappear when the book is complete. It will be replaced by a status report and a link to the newly created ebook. The Start button should always be active until the page used for creating the ebook is removed from the list of these pages (see below).1)
The book will be saved to the media directory in a sub-folder named epub/<user_name>. You should create the epub directory yourself, in advance, and give ebook creators upload permission to the epub namespace (See below).
The name of the new book will be based on the date and time. For instance: 2012_march_7_07-58-49.epub. This makes it possible to recreate a book without accidentally over-writing a prior copy. The status report tells you the name of the newly created book. In other words, you can feel free to edit your page list and the contents of the pages themselves, without fear of losing a previous version of the ebook.
The scratch directory for the book is in meta/epub/username/ in an md5 subdirectory which is created for each new ebook instance (i.e. each time you click the Start button). For instance:
A lot of files can accumulate here, which the plugin will attempt to delete. However, you might want to check and if necessary clean them out manually.
eBooks generally have a 'cover' page. Depending on the ebook reader, this may be displayed as the first page of the book, or in a sidebar, or both. The epub plugin comes with a default cover page which consists simply of the title 'Dokuwiki Ebook'and the Dokuwiki logo image. You can, however, create your own cover from within Dokuwiki. Name the cover page title and place it first in the list of pages to be processed. The cover must have one image, and one image only, and this image must be named cover.png.
Both the cover page and the cover page image can be included in a namespace, so that namespace:title and namespace:cover.png are both acceptable. This makes it possible to have different title pages for different projects and users.
While you can include text in the cover page, not all ebook readers display the text. So, you might consider putting all that you want to say in cover.png.
The epub plugin distinguishes between links to external resources and internal links to pages included in the ebook. Links to pages included in the ebook appear in the text and can be used to navigate between pages. Most ebook readers will have a back button, like a browser, making it possible to return to the page where the link appeared.
The epub plugin lists references to external resources on an end-note page. For convenience, the end notes are referenced by active footnote numbers. Clicking on a footnote number takes you to the end notes and clicking on an end-note number returns you to the place on your page. For instance, your page might have this note:
You can find out more about plugins on Dokuwiki 
Clicking on  takes you to the end notes where you might find:
Clicking on the end-note number will return you to the original page and place on the page. Clicking on http://www.dokuwiki.org/plugins will take you to plugins on Dokuwiki.org in your default browser.
The epub plugin supports a list that consists of an optional title page and a namespace. The namespace is indicated using an asterisk and it must be the first item in the list of pages:
The initial colon is recommended.
The complete syntax, including the optional title page, is as follows:
<epub:Book_name> :namespace:* :namespace:title :page_id :other_page_id </epub>
Currently only one namespace is supported. Moreover, only the topmost namespace directory is processed; so, if you have
namespace_1 is processed. These limitations may be addressed after some testing and use. If you omit the title page, a default title page will be inserted.
After the namespace setting, you can add additional page ids. A page id can consist of any standard DokuЦiki page identifier, for instance
For chapter headings, you must use the Dokuwiki internal link markup and a chapter heading is created from the link text:
<epub:Book_name> [[namespace:page|Chapter 1]] [[namespace:page|Chapter 2]] </epub>
If you omit the link text, then a Chapter heading will be created from the page id, using both the namespace and the page name.
If you use the namespace technique described above, the plugin will create Chapter headings from the page names, without the namespace. This is analogous to the way in which Dokuwiki implements its trace feature.
The epub plugin will import external images into the ebook, which differs from the way in which the plugin handles other external resources as described in the Links section above. For this to work, you must have a PHP installation which allows external resources to be accessed. This facility is enabled in php.ini by setting
allow_url_fopen = on
allow_url_fopen = 1
With the release of Binky, Dokuwiki uses the LESS CSS compiler for CSS which requires it. The latest epub release supports the LESS compiler as implemented by Dokuwiki. If for any reason you do not wish to use LESS, you can turn it off using the
|group||Name of group which has permission to create ebooks. This setting is optional and has effect only where a user does not have upload permission to the epub namespace.||epub|
|rmdir||Remove scratch directory after the ebook has been created.||y|
|permalink||Keep a permanent download link on the book creator page||true|
|less||The LESS CSS compiler will be used if present, unless this option is set to false.||true|
|compress||If the LESS compiler is used, the style sheet will be compressed if this option is set to true.||false|
|sort||Pages processed using the namespace markup will appear in alphabetical order, unless this option is set to false (unchecked)||true|
1. Create a namespace named epub and set its ACL at 0. This namespace should be kept exclusively for creating ebooks. Then give upload permission to the epub namespace to those users who will be creating ebooks. This setup has two effects:
A download link is written to the page from which the ebook has been created. This enables users with access to the page to download the book directly from that page. In this case you might want to give people read access to the page and use method number 2 below for your security.
2. Assign ebook creators to the ebook creator group.
The default group name is
epub, which can be changed in the Configuration Manager. If a user belongs to this group, then the user does not need upload permission for the epub namespace. The book may then be created in a sub-directory of the epub namespace, i.e. it must still exist in the epub namespace hierarchy.
3. The user must have create permission for pages on which the ebook is created. While this may seem self-evident, it is also a further safety check, because it means that users without create permission for an epub page cannot re-create an ebook from the data on that page, even if they might otherwise have access to the page.
The plugin keeps a list of pages which have created ebooks. This prevents the plugin from placing a Start button on all pages in the epub namespace, regardless of whether they contain epub syntax. If you wish to use an epub page for some other purpose, you can remove its name from the list using a second button which appears beneath the Start button and has the following label: Remove Page from Creator List.
There are three language files in
epub/lang/en. You can make your own translations and place them in
To upload epub files to Dokuwiki, you will have to enter its mime type in conf/mime.local.conf:
If you don't have a mime.local.conf, you can create it.
But “ignored” is not an iron-clad guarantee of security, because Dokuwiki will have cached the page. To be completely secure you should remove your page from the list of epub ids by clicking the Remove button. This forces a new user to make changes to the page in order to re-activate the Start button, at which point the page will be re-processed and its list of included id's will be re-checked for ACL permissions.
As noted above, the epub plugin places all new ebooks in a namespace created from the user's name:
It might be useful to give your ebook creators delete permission to their own epub namespaces. This will give them complete control over the books they have created.
If you find syntax plugins which do not work in epub, please post them to the forum.
epub does not support action plugins, that is, if you are using an action plugin which inserts text into the output stream, these insertions will not be captured by epub.
All of the following are free downloads.
A sample of an ebook created by epub can be downloaded here: fckgLite manual.
For a complete listing of changes see: https://github.com/turnermm/epub/commits/master. First commit March 3, 2012.
Please put your questions on the discussion page. Or use the forum. Thanks.
Discussions have been moved to a separate page: epub:discussions.