ExportHTMLWiki

Summary: Create a wiki using static HTML pages as front end for visitors
Version: 2023-10-06
Prerequisites: PmWiki 2.2.56 or newer
Status: stable
Maintainer: HansB
Users: (view? / edit)

Questions answered by this recipe

  • Can I convert PmWiki pages into static HTML?
  • Can I export my site to a set of static HTML pages?
  • Can I maintain a PMWiki site with fast loading static HTML pages for visitors?

Description

I created this script out of frustration about slow PHP page generation on a shared hosting server. The FastCache recipe offers a similar solution, but I was uncomfortable with setting up .htaccess files for url rewrites, and the way FastCache renews the static HTML pages.

It is suitable for wikis with mainly static page content, like CMS wikis, blogs, brochures etc., but not for highly interactive wikis which rely on ever changing content being generated on the fly via user interaction, i.e. use of url parameters or cookies etc.

ExportHTMLWiki will export a wiki page to HTML when it gets saved, and also offers a custom action htmlbatch to export multiple pages to HTML. With the default configuration the static HTML pages will have a file extension html, and will get served from their locations in Group folders. No Apache server url rewrites are used for this. Some pages are automatically excluded from HTML exports, such as pages in the Site and SiteAdmin groups, as well as RecentChanges pages.

Installation

Download exporthtml.phpΔ, add to your cookbook folder and include in config.php.

Configuration

Your wiki configuration must not use $EnablePathInfo = 1;, i.e use simplified URLs without parameter n=Group.PageName. For site visitors simple URLs like www.example.com/Group/PageName.html can be used, with the file PageName.html residing in folder Group/ in the domain's root.

An example for a ExportHTMLWiki: Put your wiki installation in a special folder, with a name not used for any wiki group, for instance naming it _wiki/. If you have a wiki farm setup, consider moving any public files into locations under this folder, for instance have uploads in _wiki/uploads, skin files in _wiki/pub/skins/myskin/ or whatever you use, any recipe scripts using javascript configured with their javascript a folder under _wiki/pub etc. This will enable the HTML pages created to use relative links to images and skin related files like css files. Relative links allows you to develop your wiki site on your local machine, and then simple upload the exported HTML files to a server. Check the HTML source code of the saved static HTML page to make sure all url references are correct.

A static HTML page will be created or saved whenever the corresponding wiki page is saved. In addition action=html will export a page to HTML. action=htmlbatch will export all pages of a wiki group to HTML static pages. This can be modified using the parameter p= with an appropriate page wildcard pattern in the url (wildcards * and ? are allowed, similar use as in pagelists, a group part needs to be given, seperated with a . (dot) to the page (name) part). You need admin authorisation to use action=htmlbatch, and edit authorisation to use action=html.

For batch HTML exports, to make admin life easier, I usually add a custom link to the action menu, which appears on every wiki page:

* [[{*$FullName}?action=htmlbatch|save HTML group]]

then I use this action on a page in each group, i.e. export HTML pages group by group, just to be sure all goes well.

You may wish to exclude certain page sections from HTML pages, like for instance page actions. If these are part of a skin section, they can be listed, separeted by commas, in config variable $SaveHTML['hidden']. Or you may use in the wiki page conditional markup (:if nohtml:) to show content in the wiki page, which will not show in the HTML page.

A custom pagelink markup may be used: {[pagelink]}, which will be rendered as a link to the corresponding HTML page in a wiki page, and to the wiki page in the HTML page. This is useful to provide easy edit access in HTML pages, and a way to view the HTML page easily after editing the wiki page. This markup accepts parameters to set the link label. Full syntax is: {[pagelink wikilabel htmllabel [edit|login] ]} (edit or login are further options after setting labels for the link to the wiki or HTML page).

Configuration variables

Any of the following elements of the config variable $SaveHTML can be configured in config.php before inclusion of the script. What follows are the default settings of $SaveHTML:

SDVA($SaveHTML, array(
	'suffix' => '.html',
	'relativeurls'=> true, //HTML pages will have links with relative urls when possible, not absolute urls. 
	'htmldir' => 'HTML/', //name of directory with the exported html files, relative to the wiki field
	'wikipath' => 'pmwiki/', //path from web root to wiki field directory (inclusive). Needs to be set. 
	#'localhosturl' => '', //set this to point to root of local wiki farm, to have local script urls replaced by server script urls
	#'serverhosturl' => '', //set this to point to farm on server, in conjunction with above.
	//example: $SaveHTML["localhosturl"] = $UrlScheme.'://localhost/mydomain.com';
	//         $SaveHTML["serverhosturl"] = 'https://mydomain.com';
	'exclude' => "*.RecentChanges,*.Group*,Site.*,SiteAdmin.*", //wildcard patterns to exclude pages
	'include' => PageVar($pagename, '$Group').".*",
	'hidden' => 'PageTopActionsFmt,PageTopSearchFmt,PageFootActionsFmt,PageActionFmt,PageTopBarFmt,PageTextFooterFmt,PageFootMenuFmt', //excluded skin templ sections
	'htmllabel' => 'HTML', //default html label for {[pagelink]}
	'wikilabel' => 'Wiki', //default wiki label for {[pagelink]}	
	'htmltooltip' => 'go to HTML page', //tooltip for {[pagelink ..]} link to HTML page
	'wikitooltip' => 'go to Wiki page', //tooltip for {[pagelink ..]} link to wiki page
	'redirect' => false, //true: redirects to HTML page
	'update' => true,    //true: HTML page will automatically be created when saving a wiki page as part of edits 
	'pause' => 0,  //delay in secs for page refresh when iterating pagelist pages
	'htmlecho' => false, //false, //true: show html page while saving, flashed briefly or for 'pause' seconds
	'batch' => true,     //true: batch processing is enabled
	'session' => true,   //true: batch process starts new Session and uses SESSION variables
	'test' => false, //false. Set to true to prevent actual html page saves, for testing
	'list' => false, //false. Set true to display list of pages to be exported
));

Configure with MultiLanguageViews

MultiLanguageViews allows different language content to be present on the same wiki page, while only content of one language will be served, and users can switch languages via special links. For static HTML pages we need to save language specific HTML pages.

To use langviews.php with exporthtml.php, include langviews.php before you include exporthtml.php. Now the ExportHTML process will create HTML pages in language-specific subfolders, like en/Main/HomePage.html for an English home page, and de/Main/HomePage.html for a German home page (en and de are the language keys MultiLanguageViews is using).

Set $EnableLangFolders = false; to override the creation or use of language-specific subfolders. Use this only for the specific purpose to override MultiLanguageViews, so one language version of pages can be saved as HTML, but MultiLanguageViews markup directives in pages do not need to be removed.

Usage

  • Set $SaveHTML['wikipath'] to the path of your wiki field, from the web root. Default is pmwiki, which will only work if your installation is in a folder of that name under the web root (accessed locally with localhost/pmwiki/ usually.
  • Set $SaveHTML['htmldir'] as the folder name for the HTML files. Default is HTML/, which will be a folder under the wiki field root folder (usually the folder containing pmwiki.php or some other php file acting as the script file {including pmwiki.php from a farm folder for instance}).
  • Run ?action=html or ?action=htmlbatch to save wiki pages as HTML. You could create action links for this in the header or footer.
  • When saving edits of a page, the page also gets saved as HTML automatically.
  • Check if the HTML pages are correct, especially with relative links to other pages and attachments.
  • If relative links don't work, you can try setting SaveHTML['relativeurls'] = false; to produce absolute URL links in the HTML pages.

Local wiki, public HTML pages

One can edit a wiki locally, have it saved as HTML pages, and upload these to a server for public view. But make sure all necessary image files, css files and javascript files are uploaded as well. Best may be to have the wiki on the public server as well, but mainly use the local wiki to create and edit wiki pages, and save them as HTML.

This can also be done if the wiki is part of a wiki farm, or if the wiki skin is part of the farm setup. Add to farmconfig.php something like this:

$SaveHTML["localhosturl"] = $UrlScheme.'://localhost/mydomain.com';
$SaveHTML["serverhost"] = 'https://mydomain.com'; 

Under serverhost put the root URL of your wiki farm on the public server. The URL of localhost will be replaced by that of serverhost in the ExportHTML process, after all other substitution are done.

Some restrictions

When creating a site using static HTML pages and maintaining it by editing wiki pages some restrictions should be observed:

  • any url parameters used in the wiki will be ignored, as no PHP script is called, but simply the static HTML page is served.
  • after editing a page which is included on other pages requires exporting all these other pages to HTML, for instance after editing the Site.SideBar page or other pages in the Site group, and even editing template sections.
  • if pages contain forms for public users, you most likely need to check if these forms are still usable in the static HTML page, and that the user gets redirected to a correct HTML page afterwards, and does not end up viewing a wiki page instead.
  • the recipe script at present does not create any index files, like index.html or index.php, nor any .htaccess files used to achieve the same. So you may want to create a file index.php or index.html to redirect to any Homepage.html or such.

Notes

  • To do: create index.html pages automatically as part of batch export process.

Acknowledgements

The script code is using some modified code from the FastCache recipe, many thanks to Eemeli Aro, and code from the JJSIterator recipe, many thanks to Jjs (Jens Schiffler)!

Change log / Release notes

  • 2023-10-06: Fixed bug in URL rewrite patterns for when Uploads are not enabled. Thanks Bernhard for spotting this!
  • 2023-10-05: Minor fix to $group and $name determination. Added debug function show().
  • 2023-10-04: Revised automatic path creation. Added switch to enable HTML pages with absolute, not relative, URLs.
  • 2023-01-01: update for PHP 8
  • 2017-06-16: changed link markup to use Markup(), not Markup_e().
  • 2016-09-16: added $EnableLangFolders variable; added $SaveHTML config options 'test' and 'list'; added URL rewrite rule to enable saving Server Host URL instead of localhost URL with help of $SaveHTML parameters localhost and serverhost.
  • 2016-07-08: improveded integration with MultiLanguageViews recipe, to enable export of language specific HTML pages on wiki page edits, as well as in single page and batch modes (?action=html and ?action=htmlbatch).
  • 2016-04-27: added 'index,follow' for robots metatag in HTML, suppress some wiki edit specific styles otherwise possibly loaded when page editing.
  • 2016-04-09: added $HTMLRewritePattern for links with ?setlang=... and language-specific HTML subfolders, to integrate with MultiLanguageViews recipe.
  • 2016-01-10: initial release

See also

Cookbook /
BackupHTMLZip  Export your wiki to static HTML then optionally compress/zip it (Experimental)
ExportHTML  Export PmWiki pages as "static" HTML pages
FastCache  Caches complete wiki pages for very fast retrieval (beta)
HtmlUrls  Add ".html" to the end of page urls (Core)
PrintGroup  Export WikiGroup pages to one large HTML file, and/or to PDF (Experimental)

Contributors

Comments

See discussion at ExportHTMLWiki-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.