StaticPages

Summary: Allows pmwiki pages to be published as static pages
Version: 2.0.1
Prerequisites: pmwiki-2.2.0-beta45 or pmwiki-2.2.0-beta54 (It could work with earlier versions)
Status:
Maintainer: MarkS
Categories:

Questions answered by this recipe

  • How do I publish pmwiki pages as static pages?
  • How can I reduce the time it takes to open a pmwiki page?

Description

  • Allows an Administrator to Publish PmWiki pages inside the working directory (wiki.d) as static pages.

Installation

  • 2.0.1
  • Download StaticPages-2.0.1.zipΔ and extract it to your cookbook directory.
    • Bug fix, see version 2.0.0 for instructions.
  • 2.0.0
  • Download StaticPages-2.0.0.zipΔ and extract it to your cookbook directory.
  • Updating your config.php
    • Required: Add the following to your pmwiki/local/config.php
      • include_once("$FarmD/cookbook/StaticPageOutput.php");
      • include_once("$FarmD/cookbook/RelativeURLs.php"); (This must be your last entry in config.php)
    • Required: An admin password for pmwiki will need to be set to access the StaticPageGenerator action page
      • $DefaultPasswords['admin'] = crypt("test");
    • Optional: Define your Static Page output location
      • $StaticPageDir = "pub/web"; (Default)
    • Optional: Define your wiki location from your Static Page output location
      • $StaticPageDirToWikiDir= "./../.."; (Default)
    • Optional: Set the pmwiki action name (http://localhost/pmwiki/pmwiki.php?action=StaticPageGenerator) to show the StaticPageGenerator page
      • $StaticPageGeneratorActionName = "StaticPageGenerator"; (Default)
    • Optional: When a wiki page is saved, does it update the corresponding static page.
      • $StaticPageUpdateOnEditSaveAction = TRUE; (Default)
    • Optional: When a dynamic wiki page is shown, this will automatically generate all static links associated.
      • $StaticPageAutomaticCreation = TRUE; (Default)
    • Optional: The file naming format for the static page files produced.
      • $FmtPV['$staticPageName'] = '"$group.$name.html"' (Default)
    • Optional: Not all operating systems support UTF-8 file names. So select the encoding of the Static Page file names.
      • $ServerFileSystemEncoding = "UTF-8"; (Default)
      • $ServerFileSystemEncoding = "WINDOWS-1252"; (Default for $_ENV['OS'] containing the text "Windows")
    • Optional: Exclude Wiki Pages that you do not wish to have static pages generated for. (Both for "Save" and the action=StaticPageGenerator page)
      • $StaticPageRegularExpressionExclude = array(); (Default)
      • $StaticPageRegularExpressionExclude = array("/Main\.H.*/", "Main.WikiSandbox");
      • $StaticPageRegularExpressionExclude = array("/Main\.*/"); (Exclude all pages in the Main Group)
    • Optional: List of additional pages to be built when you "Save" a page.
      • $StaticPageSaveActionPageList = array(); (Default)
      • $StaticPageSaveActionPageList = array("Main.RecentChanges");
      • $StaticPageSaveActionPageList = array("Main.HomePage", "Group.RecentChanges"); (The Group keyword will be replaced with the group of the page being saved.)
  • 1.0.8
  • Download StaticPages-1.0.8.zipΔ and extract it to your cookbook directory.
  • Updating your config.php
    • Required: Add either one of the following to your config.php
      • include_once("$FarmD/cookbook/StaticPages.php"); (Default Pmwiki recommended cookbook recipe include)
      • include_once(realpath(dirname(__FILE__) . "/../cookbook/StaticPages.php"));
    • Required: An admin password for pmwiki will need to be set to access the StaticPageGenerator action page
      • $DefaultPasswords['admin'] = crypt("test");
    • Optional: Define your Static Page output location
      • $StaticPageDir = "pub/web"; (Default)
    • Optional: Define your wiki location from your Static Page output location
      • $StaticPageDirToWikiDir= "./../.."; (Default)
    • Optional: Set the pmwiki action name (http://localhost/pmwiki/pmwiki.php?action=StaticPageGenerator) to show the StaticPageGenerator page
      • $StaticPageGeneratorActionName = "StaticPageGenerator"; (Default)
    • Optional: Set the Password key for the StaticPageGenerator action
      • $StaticPageGeneratorPasswordKey = 'admin'; (Default)
    • Optional: When a wiki page is saved, does it update the corresponding static page.
      • $StaticPageUpdateOnEditSaveAction = TRUE; (Default)
    • Optional: Exclude Wiki Pages that you do not wish to have static pages generated for.
      • $StaticPageRegularExpressionExclude = array(); (Default)
      • $StaticPageRegularExpressionExclude = array("/Main\.H.*/", "Main.WikiSandbox");
      • $StaticPageRegularExpressionExclude = array("/Main\.*/"); (Exclude all pages in the Main Group)
    • Optional: List of additional pages to be built when you save a page.
      • $StaticPageSaveActionPageList = array(); (Default)
      • $StaticPageSaveActionPageList = array("Main.RecentChanges");
      • $StaticPageSaveActionPageList = array("Main.HomePage", "Group.RecentChanges"); (The Group keyword will be replaced with the group of the page being saved.)
  • 1.0.6
  • Download StaticPages-1.0.6.zipΔ and extract it to your cookbook directory.
  • Updating your config.php
    • Required: Add either one of the following to your config.php
      • include_once("$FarmD/cookbook/StaticPages.php"); (Default Pmwiki recommended cookbook recipe include)
      • include_once(realpath(dirname(__FILE__) . "/../cookbook/StaticPages.php"));
    • Required: An admin password for pmwiki will need to be set to access the StaticPageGenerator action page
      • $DefaultPasswords['admin'] = crypt("test");
    • Optional: Define your Static Page output location
      • $StaticPageDir = "pub/web"; (Default)
    • Optional: Set the pmwiki action name (http://localhost/pmwiki/pmwiki.php?action=StaticPageGenerator) to show the StaticPageGenerator page
      • $StaticPageGeneratorActionName = "StaticPageGenerator"; (Default)
    • Optional: Set the Password key for the StaticPageGenerator action
      • $StaticPageGeneratorPasswordKey = 'admin'; (Default)
    • Optional: When a wiki page is saved, does it update the corresponding static page.
      • $StaticPageUpdateOnEditSaveAction = TRUE; (Default)
    • Optional: Exclude Wiki Pages that you do not wish to have static pages generated for.
      • $StaticPageRegularExpressionExclude = array(); (Default)
      • $StaticPageRegularExpressionExclude = array("/Main\.H.*/", "Main.WikiSandbox");
      • $StaticPageRegularExpressionExclude = array("/Main\.*/"); (Exclude all pages in the Main Group)
    • Optional: List of additional pages to be built when you save a page.
      • $StaticPageSaveActionPageList = array(); (Default)
      • $StaticPageSaveActionPageList = array("Main.RecentChanges");
      • $StaticPageSaveActionPageList = array("Main.HomePage", "Group.RecentChanges"); (The Group keyword will be replaced with the group of the page being saved.)

Cookbook files

Usage

  • When you "View" (browse) a page, all the linked Wiki Pages will have the associated Static Pages generated. (Default: StaticPageAutomaticCreation = TRUE)
  • When you "Save" a wiki page, the associated Static Page will be generated.
  • Access to the special "Administrator" StaticPageGenerator page at;

Notes

  • Don't use with dynamic navigations (e.g. DynamicPageActions) as generated static pages won't have all actions on it.
  • It would be great if those you use this, could give me some feedback. Did it work. Did it not. Was it a pain. What did you like etc etc

Release Notes

  • 2.0.1
    • BugFix: RelativeURLs.php was having problems with UTF-8 html link encoding and the styles markup.
  • 2.0.0
    • Reworked quite a bit.
    • UTF-8 webpages are NOW handled correctly.
  • 1.0.8
    • Static Pages now use relative URLS.
    • If you browse a page, all static page links will be created if they don't yet exist.
    • Quite a significant code change, so let me know how it goes.
  • 1.0.7
    • Needed to be reworked. Some huge issues with the way relative paths where handled.
  • 1.0.6
    • Added extra configuration variable: $StaticPageSaveActionPageList
  • 1.0.5
    • Internal Release
  • 1.0.4
    • Tested with pmwiki version 2.1.26
    • The exclusion list of static pages will be done via the $StaticPageRegularExpressionExclude variable in config.php
      • The $StaticPageExclude variable is now deprecated.
    • StaticPageGenerator updates
      • Authentication using pmwiki.php's RetrieveAuthPage method (Instead of an extra php file).
      • Removed possible error output with "StaticPageGenerator.php".
      • StaticPageGenerator page updated. Excluded pages are mentioned. Better look'n'feel in Internet Explorer.

Comments

  • This recipe does not work properly when using per group sub-directories in wiki.d. it only reads the folder name - thinks it is a page, and can't update anything. should be an easy fix I hope :). Seth, 18.01.2007
  • The new regexp exclude works great, thanks a lot! One potential problem: v1.0.4 seems to avoid static links to Site.AllRecentChanges. I can hazard a guess that generating the RC pages might lead to a performance problem. This "default exclude" doesn't seem absolute though. For example, if there is a link to Site.AllRecentChanges on the side bar, it gets rewritten to ../pub/web/Site_AllRecentChanges.html, which doesn't exist and never gets generated. "Recent Changes" in the header and the footer work fine. One solution is to add S.ARC, or possibly every Groupname.RC, to the regexp exclude. --Pervilä 29.11.2006
    • If you go to "http://localhost/pmwiki/pmwiki.php?action=StaticPageGenerator", all the pages listed will be names of files that exist in the "wiki.d" directory. So if a page such as Site.AllRecentChanges doesn't exist on the "StaticPageGenerator" page, then it doesn't exist in the "wiki.d" directory. (Sometimes you have to view a RecentChanges page before a page is created in the "wiki.d" directory) --MarkS
    • The interesting thing you might be finding is that some links continue to use the wiki "pmwiki?n=Main.RecentChanges" rather a static link of "Main_RecentChanges.html". This is because some links are created using a wiki template (Wiki Skin) and are hard coded and not wiki links. Have a look at "pmwiki.tmpl" which is part of the default pmwiki skin. To get around this change your template file to include wiki pages using the following notation <!--wiki:$Group.HeaderBar Main.HeaderBar--> --MarkS
    • Let me know if this helps --MarkS
  • It works, but at a cost: the *RecentChanges pages are not refreshed when changes are made, so their contents become obsolete quickly. Would it be possible to automatically build Group.RC and Site.ARC when a page is edited? Perhaps as a future optional feature? -- Pervilä 8.12.2006
    • Done. See usage of $StaticPageSaveActionPageList --MarkS
  • Greatness! One more step towards perfection, thanks. One last question (until the next one) and a note. -- Pervilä 19.12.2006
  • Is there any way to generate the links to the static pages as relative and not static? We run a read-only mirror site as backup, and it would be most nice if the links did point to the relative root of the wiki directory. This might be a problem with pmwiki itself.
    • See version 1.0.8 -- MarkS
  • Nota bene: The more of less standard way of) linking a new page and then editing content into it yields a broken link on the first static page. This is due to the fact that there is no db with referencing pages. It's probably not worth implementing the referenced links in the static pages recipe, but it's worth mentioning.
    • See version 1.0.8 -- MarkS
  • With 1.0.7 linking to pages with utf-8 characters in the name seems to be broken. Eg. WikiSandbox links to (Main/)ÄllitJaTällit, after saving the link becomes
    <p class='vspace'><a class='wikilink' 
    href='./pub/web/Main_<span class='c3'>84llitJaT</span><span class='c3'>a4llit.html'>ällit 
    ja tällit</a></span>
    (some line breaks added) -- Pervilä 1.1.2007
    • See PITS 00858 -- MarkS
    • I upgraded a copy of our wiki to 1.0.8. Linking now works, but the PageAction "header" breaks in the same way. See http://mekanismi.sange.fi/test-pmwiki/pub/web/Main_WikiSandbox.html for an example. Thanks a lot for you patience in debugging this. (Note: v1.0.6 works) -- Pervilä 10.1.2007
      • If you remove the file "wikistyles.php" (And regenerate the static page), does it work correctly? -- MarkS
    • If I remove ../scripts/wikistyles.php and edit & save the page, regenerating it, no. A lot of other things get broken after removing said file, though. --Pervilä
      • Can you put a return statement at the start of the wikistyles.php file, before functionality is reached? Of course if you use wiki styles such as %black% or %% then this won't be an option.
    • After adding a return; on line 8 of scripts/wikistyles.php and editing said page & saving, no change. The | pageactions are still broken. --Pervilä 17.1.2007
    • If there is anything else I could try to debug this, I'm ready and willing. Although any progress might be blocked by PITS.00858? We are still running 1.0.6 with the static links. --Pervilä 18.3.2007
    • I need to look into this issue as there is no indication that the pmwiki team has looked at this PITS.00858. I will see what I can do when I get a spare chance. --MarkS 18.03.2007
    • Pmwiki has had some nice changes made to the core so doing a significant rework, and it's coming along. Just doing the regular expressions to make a wiki page a static page... --MarkS 09.05.2007
  • New release 2.0.0 Please let me know how it goes for you --MarkS 20.05.2007
    • I've just finished installing and testing 2.0.0 on pmwiki-2.1.27. Everything seems to be running smoothly and the old problems are gone. Relative linking rules! If you ever come to Helsinki, I'll buy you three beers. ;) --Pervilä 1.6.2007
    • Okay, caught a minor glitch. External links without the square brackets become invisible. E.g., [[http://www.pmwiki.org/]] works, but http://www.pmwiki.org/ does not. I tested this with a clean pmwiki-2.2.0-beta52 and said pmwiki-2.1.27. -Pervilä 1.6.2007
  • New release 2.0.1 Should fix bug described above (In version 2.0.0). -- MarkS 07.06.2007
    • Thanks again! I can confirm a working installation on pmwiki-2.1.27, if we spot any new bugs, I'll keep this page posted. -Pervilä 10.6.2007
    • 2007-06-10 / Maddes / Bug:
      One link is not changed to a static link, the one in the title which leads to the homepage of a group. Here it would be Cookbook at the top of this page.
    • 2007-06-10 / Maddes / Enhancement:
      Had to change the script a little bit, so that it works with my farm setup (2 fields) with pmwiki-2.1.27.
      My wiki data is stored outside the web folders, so I needed to separate between file pathes and URL pathes.
      • Defined an additional variable in config.php called $StaticPageDirFile, which is used for file accesses.
      • In StaticPageOutput.php added after line #15:
        if (!isset($StaticPageDirFile)) {$StaticPageDirFile = $StaticPageDir;}
      • Replaced $StaticPageDir with the new $StaticPageDirFile in the functions createStaticPage() and ensureStaticPageDirExists() of StaticPageOutput.php plus also in StaticPageGenerator.php.
    • 2007-06-09 Smc What a great recipe well done! Thought I'd post a problem I've found. It's taken me ages to actually diagnose the issue. I've found that if you use "$EnablePathInfo = 1" which gives URLs of the form .../pmwiki.php/Group/PageName then the static URLs on the page have the wrong root. In the example above linked URLs look like .../pmwiki.php/Group/pub/web/Group.PageName.html (note that 'pmwiki.php/Group/' should not be there. If I switch off $EnablePathInfo so URLs look like .../pmwiki.php?n=Group.PageName then all work as expected. Digging around your code I'd guess that one of your 'dirname()' calls is not doing what you expect. I'm no expert though!
    • This looks like just the thing I could use for running pmwiki on my NSLU2 embedded device, some large/complex pages take up to 20s to load from markup, whereas equivalent static pages take 1s... However, I didn't get it to work yet, when I use https it doesn't generate anything (except for lots of "Could not open URL for copying" messages), and with http it does generate something, but then seems to be incompatible with UserAuth2 (generates all links with login screens instead of pages, regenerating after login not possible). Any ideas anyone?
      Still this looks promising! -2007-08-03, Lennert
      • Page Generation is done by making a URL connection to a remote address. I haven't tested with https, so I never had to deal with authentication issues. I will have a look at all these issues soon, and update this page. -- MarkS 03.08.07
  • Getting a blank page back from StaticPageGenerator - Ben, Oct 2010
    • This is likely caused by a PHP execution time-out. In the cookbook directory, edit the StaticPageGenerator.php and just below the comment at the top, add this (otherwise increare the time-out in php.ini):

ini_set("display_errors", 1); ini_set('max_execution_time', '0');

  • Error about undefine mb_convert_encoding - Ben, 21 Dec 2008
    • I got an error in StaticPageOutput.php about undefined function mb_convert_encoding (running on Windows, IIS, no choice). I do not have access to my php installation to install this module, but I was able to work around it by editing StaticPageOutput.php and commenting these three lines out:
      • #if (isset($ServerFileSystemEncoding)){
      • # $pagenameLink = mb_convert_encoding($pagenameLink, $ServerFileSystemEncoding, "UTF-8");
      • #}
    • Needless to say, only do this if there is no alternative, and it wont work in all cases. I have no idea what the impact of this is, other than that it may be a good idea to avoid pages with non-ASCII names.
    • With this change StaticCache worked great and resulted in *significantly* reduced page loading times (which I desperately needed). Thank you so very much! I tried using Cookbook.FastCache but it did not help in my case, likely because I could not use Apache/mod_rewrite.
    • Mark, IMHO the description of this module does not seem to do justice to the immense difference that it can make and the fact that in some cases it is the only available option to drastically reduce page load times.
    • With this change I do notice that immediately after you edit a page, you initially get the old page content and you also get the old content if you request the page. This is a little disconcerting but seems to fix itself after about five seconds or so and then everything is nice and fast and properly working again.
    • Please see this excellent discussion: http://www.mail-archive.com/pmwiki-users@pmichaud.com/msg11441.html
    • It may also help to change the line:
      • if (isset($ServerFileSystemEncoding)){
    • to
      • if (isset($ServerFileSystemEncoding) && $ServerFileSystemEncoding<>"UTF-8"){
    • because then you could set it to UTF-8 on Windows and have it work without having to change the code.
  • Anchored links to another wiki page (OtherPage#Anchor) do not seem to work - Nicolas, 7 Dec 2009
    • Using the latest PmWiki (2.2.8) and StaticPages-2.0.1 with all default parameters, it looks like links to anchors (#anchor) on the same page are generated and working correctly on the StaticPages built, however wiki links to AnotherPage#anchor are not -- they are missing the #anchor in the link generated on the static page. The problem does not appear on pages which are kept dynamic (excluded from Static generation) so it looks like a StaticPage-2.0.1 bug to me... Any idea/workaround ? This is quite annoying as it breaks many things... Thanks !
  • '''Q: All of the links on my pages have the external link icons (i.e. a little square with an arrow point to the upper right) behind them? How do I get rid of them?
    • The simplest way to fix this is to edit local/config.php and place this text in there:
## This changes external links to not have the small link icon in them:
# This is the default:
#$UrlLinkFmt = "<a class='urllink' href='\$LinkUrl' title='\$LinkAlt' rel='nofollow'>\$LinkText</a>";
$UrlLinkFmt = "<a class='plainlinks' href='\$LinkUrl' title='\$LinkAlt' rel='nofollow'>\$LinkText</a>";

See Also

Contributors

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.