1# Dokuwiki Site Export
3Site Export is an admin plugin that offers a convenient way to download your dokuwiki site as a standalone version. It cycles through your namespaces - a starting point can be given at run-time - and packs the result into a zip file.
4The result can be unpacked at any place and viewed without having an internet connection. That makes the plugin perfect for providing static documentation to customers on a CD or DVD.
6[![Build Status](https://travis-ci.org/i-net-software/dokuwiki-plugin-siteexport.svg?branch=master)](https://travis-ci.org/i-net-software/dokuwiki-plugin-siteexport)
8## Requirements
10 * [DokuWiki](http://dokuwiki.org) version **Weatherwax**, **Binky** and newer
11 * You need to log in as administrator to have access to the siteexport plugin
12 * You have to have the [zip compression library of your php](http://de.php.net/manual/en/book.zip.php) installation activated.
13 * [dw2pdf](https://www.dokuwiki.org/plugin:dw2pdf) for PDF export options
14 * a writable <code>/inc/preload.php</code> file for template switching
16## Configuration
18This is about the Admin --> Configuration Manager page.
20 * **Default Export Depth:**<br>
21 How far in should the export go. This option will be used when selecting "_specific depth_" as _Export Type_.
22 * **Try to export non-public pages:**<br>
23 SiteExport only allows to export public pages. This option will allow to export non-public pages that the currently logged in user has access too as well. **(no yet implemented)**
24 * **Wiki Path and name for exported ZIP file:**<br>
25 DokuWiki namespace and file name that will be used to create temporary files.
26 * **Pattern to exclude resources:**<br>
27 A regular expression to define paths that should not be exported
28 * **Maximum script execution time:**<br>
29 Defines an execution time in seconds for how long the script may run while exporting a site via URL Request or wget/curl request. Due to PHP settings this may be very limited and if you export a very large site or namespace the script will time out. This option will take care of redirecting the request as many times as needed until the export is finished for all pages (the time should be long enough to have at least one page exported).
30 * **Debug Level:**<br>
31 Level of Debug during export job. This may be important to find errors for the support.
32 * **Debug File:**<br>
33 Where will the debug log be written to? It has to be a writable destination.
34 * **Cache time for export:**<br>
35 The siteexport uses its own cache timer to determine when an export should be discarded.
37## How to export pages
39SiteExport is only available from the Admin menu at the _Additional Plugins_ section. When starting of from the page you want to export, simply go to the export menu, and hit _start_.
41### Enter your starting Namespace
43Basic export options
45#### Set Namespace
46The namespace/page you actually want to export. This will be predefined with the page you currently visited.
48#### Parent Namespace to export
49By default this is the same namespace/page that you are going to export. That will result in a flat structure, with the pages at the top level.
51You can define a higher namespace which will result in the structure below being exported with potentially empty folders but having the lib (plugins, template) directories beeing at top level.
53This is usefull for exporting translated namespaces starting with the root of the translation.
55#### Export Type
56How many pages should be exported?
58  * **This page only:**<br>
59  Attemps to only export this one page.
60  * **All sub namespaces:**<br>
61  Exports everything below the defined namespace
62  * **Specific depth:**<br>
63  Exports everything below the defined namespace but only for the defined depth. The depth means how many namespaces it will go down.
65##### Depth
66Number of namespaces to go down into.
68##### Export Linked Pages
69Will export linked pages outside or even deeper of the defined namespace as well.
71### Select your Options
73#### Export Absolute Paths
75#### Export Body only
76Adds the option for renderes to only export the inner body other than exporting the whole page.
78#### Export all parameters (e.g. "do")
79Adds all parameters to the links in exported pages - which may make sense when using JavaScript that relies on the links
81#### Render Engine
82By default the engine of the DokuWiki. This allows exporting the pages with other renderers, e.g. the siteexport_pdf (derived from dw2pdf) to have pages in PDF file format.
84#### Export Template
85**Only available if <code>inc/preload.php</code> is writable.**<br>
86Allows to export the pages with a different template than the default one.
88#### PDF Export
89**Only available if the dw2pdf plugin is installed.**<br>
90Exports the pages into PDF files, one per page. There are options ([TOC](#table-of-contents-definition)) to export multiple pages into one large PDF.
92#### Numbered Headings
93**Only available if the dw2pdf plugin is installed.**<br>
94Adds a number to each heading. Usefull for a Table Of Contents inside the PDF.
96### Select one of the Help Creation Options (optional)
97This is totaly optional.
99#### Create Eclipse Help:
100Allows the creation of <code>context.xml</code> and <code>map.xml</code> files that can be used by Eclipse and its Plugins.
102#### Create Java Help:
103Allows the creation of <code>tox.xml</code> and <code>map.xml</code> files that can be used by Java and the Java Help implementation.
105#### Use TOC file in Namespace
106If you do not want the export to be structured like your DokuWiki is, you can create a file called <code>toc</code> in the namespace and create a custom structure that will be used instead.
108This is great for having all the chapters of a documentation in their own file and exporting them into PDF as a single file.
110See [Table Of Contents definition](#table-of-contents-definition).
112### Disable (JS/CSS) Plugins while export
113The checkboxes stand for each plugin. By checking it the plugin will be disabled temporarily and therefore not generate any CSS or JS output.
115This is great for a static export that does not need any other or only some plugins. Be adviced that disabling plugins might improve the speed of PDF export.
117### Custom Options
118Here you can add additional variables that will be given to exported page. This can help to create content dynamically when using other plugins or PHP execution.
120Simply hit _add Option_ for a new _name_ / _value_ field, enter the variables name and value. Done.
122### Start Process
123The three links are convenience links. They will be regenerated by every change of any option. They reflect static URLs that can be copied and used e.g. for _ant_ jobs.
125Now: Hit start and your pages will be exported.
127### Status
128Reflects what is currently going on and will display errors that occur during exporting or changing options.
130### Save as Cron Job
131If your configuration directory is writable - which it should after setup, you can save your current setup here.
133You can show what has been saved, view them, delete them and re-run them.
135If you have CLI access (terminal or whatever) and cron access to your server, you can add the <code>cron.php</code> file to schedule runs of your cron jobs.
138## Table Of Contents definition
139If you do not want the export to be structured like your DokuWiki is, you can create a file called <code>toc</code> in the namespace and create a custom structure that will be used instead.
141This is great for having all the chapters of a documentation in their own file and exporting them into PDF as a single file.
143The structure is basically a list of links:
147  * [[.:index|Index of the page]]
148    * [[.:sub:index|Index of the sub namespace]]
149      * [[.:sub:sub:index|Index of the sub/sub namespace]]
150    * [[.:sub:page|Page in the sub namespace]]
151  * [[.:another-page|Another page]]
152    * [[.:another-sub:index|Index of another sub namespace]]
156The &lt;toc&gt; tag support several options:
158Option | Behavior
159---- | ----
160notoc | hide the user defined TOC in the document
161description | display the description abstract below of the linked page below the link (usefull together with:`~~META:description abstract=This is my abstract.~~`
162merge | this will merge all the defined documents from the TOC into the current document.
163mergeheader | this will, as addition to merge, merge all headers starting with the first document (new headers of later documents will be appended at the end, the will not be sorted alphabetically)
164mergehint | add hints about the merged content. It can be configured using the meta plugin and the key "mergehint = <label>". It falls back to the "thema" key or the page title.
165pagebreak | inserts a pagebreak after each page defined by the namespace
167You have to define the options like this: <code>&lt;toc notoc merge&gt;</code>
169## Siteexport
170Add a download button for the current page - or any other page
173{{siteexport [options]}}
176## Siteexport Aggregator
177There is the additional syntax: aggregator. This allows an in-page selection of an ordered list of pages in the current namespace and sub-namespaces. Once selected and submitted, that page will be generated with the options provided - and merged back up the list (it actually starts merging top down). (What?!)
179The Syntax is (and can be used multiple times per document):
182{{siteexportAGGREGATOR [options]}}
185 * This will actually create a `<toc>` internally, using the options `merge` and `mergeheader`
186 * Without options it will generate a dropdown-list of all pages in the namespace (except the current) one
187 * The list will be ordered by a meta key `mergecompare` which has to be added via the META plugin.
188 * You can create an element with predefined options using the editor button.
189 * There are two additional options:
190   * `exportSelectedVersionOnly` - if set it will only export this one selected entry. It will then export this one page with the metadata of the page that has the aggregator.
191   * `includeSelectedVersion` - will export all documents starting from the newest to the document directly prior to the selected one.
192   * `mergehint=false` - disable the addition of merge hints