PublishWebPlugin < TWiki

---+!! Publish Web Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/PublishWebPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/PublishWebPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
Utility to publish a TWiki web to static HTML pages. Useful to maintain a static website collaboratively in an access restricted TWiki.

---++ Description and Syntax Rules

Topics in a publish web serve as the source of static HTML pages of an external website. A TWiki web is considered a publish web if a PUBLISHWEBPLUGIN_PUBLISHWEBNAME preferences setting is set to the name of the web. The plugin generates an HTML page every time a user saves a topic in a publish web. The static HTML files are based on a TWiki skin of choice. All referenced attachments (images etc) are copied to a publish directory.

---+++ Topics and Links

   * The home topic is assumed to be =Index=
   * Topic names: For clarity, use capitalized words and underscores (%SYSTEMWEB%.WikiWord names are possible too)
   * All links should be defined as double square bracket links, e.g. =[<nop>[Topic]]= or =[<nop>[Topic][label]]= (do not use %SYSTEMWEB%.WikiWord links)

#PublishProcess
---+++ Publish process

<div style="position: relative;"><div style="position: absolute; top: 0; left: -26px; width: 16px; z-index: 10; border-radius: 4px; color: #fff; background-color: #4c4; text-align: center; font-size: 9pt;" title="This section is published">P</div></div>
<div style="border-left: 4px #1b1 dotted; margin-left: -14px; padding-left: 10px;">
   * A static HTML page is generated for every topic saved in a publish web defined by the PUBLISHWEBPLUGIN_PUBLISHWEBNAME setting.
   * A topic is excluded from publishing if it, or any of its ancestors (parent, grandparent, ...) is listed in the PUBLISHWEBPLUGIN_EXCLUDETOPIC setting.
   * A topic is also excluded from publishing if the ={RequirePublishVariable}= configure flag is set, and if the topic has no =%<nop>STARTPUBLISH%= and/or =%<nop>STOPPUBLISH%= variable.
   * If the ={RequirePublishVariable}= configure flag is set, the publish area of a topic is indicated by a green dotted line at the left page margin (as with this bullet list).
   * Topic names get converted to a lowercase filename, e.g. =Index= to =index.html=, =AboutUs= to =aboutus.html=, and =Customer_Support= to =customer_support.html=.
   * Only text between =%<nop>STARTPUBLISH%= and =%<nop>STOPPUBLISH%= is used (the whole text if missing).
   * !WikiWord links are ignored, also across webs.
   * Page layout is based on the skin defined in the PUBLISHWEBPLUGIN_PUBLISHSKIN setting.
   * Visit !WebPublish in a publish web to re-publish topics without an edit/save cycle.
   * It is possible to conditionally show one thing when viewing a topic, and another thing when publishing a topic. For example, it may be desirable to show a different header in published pages. The =publish_topic= context can be used for this. This example shows how to include !ClassHeader for normal topic view, and include !ClassHeaderPublish instead when publishing the topic:
     %BR% =%<nop>IF{=
     %BR% =<nop>  "context 'publish_topic'"=
     %BR% =<nop>  then="$percntINCLUDE{ClassHeader}$percnt"=
     %BR% =<nop>  else="$percntINCLUDE{ClassHeaderPublish}$percnt"=
     %BR% =}%=
</div>

---+++ Variables

   * =%<nop>STARTPUBLISH%= - place in topic text where to start publishing
      * Optional, start from top if missing
   * =%<nop>STOPPUBLISH%= - place in topic text where to stop publishing
      * Optional, publish to end of topic if missing
   * =%<nop>PUBLISHWEB{"nicetopic"}%= - nice topic name
      * Shows a "nice" topic name of the current topic: Underscores in topic names are rendered as space; the Index topic is rendered with the HOMELABEL Plugin setting
      * Example: Topic =Customer_Support= turns into =Customer Support=
   * =%<nop>PUBLISHWEB{"breadcrumb"}%= - nice breadcrumb
      * The breadcrumb is based on the parent child relationship of topics, starting at the Index topic
      * The breadcrumb does _not_ include the current topic, append =%<nop>PUBLISHWEB{"nicetopic"}%= to get the complete breadcrumb
      * The skin may contain a =%<nop>PUBLISHWEB{"breadcrumb"}%= variable to show the breadcrumb
      * Underscores in topic names are rendered as space
      * Example: =You are here: <u>Home</u> &gt; <u>Customer Support</u> &gt;=
   * =%<nop>PUBLISHWEB{"publish" topic="Name"}%= - re-publish topic(s) without edit/save cycle
      * Useful to refresh all HTML pages if the skin has been modified
      * A =topic="all"= publishes all topics in the Publish web except for the excluded ones
      * A =topic="Any_Topic"= publishes a specific topics

---++ Plugin Settings

%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%
Plugin settings are stored as preferences settings. Do __not__ change the settings here, they are here only for illustration purposes showing the default values. Define the settings in the publish web's !WebPreferences or in [[%LOCALSITEPREFS%]]. For example, to customize the =PUBLISHWEBPLUGIN_PUBLISHSKIN= setting, add a =* Set PUBLISHWEBPLUGIN_PUBLISHSKIN = mypublish= bullet in the preferences topic.

   * Web to publish, must be defined in each publish web:
      * Set PUBLISHWEBPLUGIN_PUBLISHWEBNAME = DemoWebsite

   * Optional sub-directory below ={Plugins}{PublishWebPlugin}{PublishPath}= to publish content to:
      * Set PUBLISHWEBPLUGIN_PUBLISHSUBDIR = 

   * Skin used for publishing:
      * Set PUBLISHWEBPLUGIN_PUBLISHSKIN = demo_website
      * __Note:__ It is also possible to specify a publish skin on a per page basis. Define a [[%SYSTEMWEB%.TWikiForms][TWiki Form]] with a form field called !PublishSkin. It can be of any type, but a select dropdown box is probably most convenient.

   * Exclude topics from publishing:
      * Set PUBLISHWEBPLUGIN_EXCLUDETOPIC = WebAtom, WebChanges, WebCreateNewTopic, WebHome, WebIndex, WebLeftBar, WebNotify, WebPublish, WebPreferences, WebRss, WebSearchAdvanced, WebSearch, WebStatistics, WebTopicList, WebTopMenu, WebTopicCreator, WebTopicEditTemplate

   * Home label, used by =%<nop>PUBLISHWEB{"breadcrumb"}%=:
      * Set PUBLISHWEBPLUGIN_HOMELABEL = Home

   * Breadcrumb item separator, used by =%<nop>PUBLISHWEB{"breadcrumb"}%=:
      * Set PUBLISHWEBPLUGIN_HOMESEPARATOR = &raquo;
%ENDTWISTY%

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server. 
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==data/DemoWebsite/*.txt== | Demo web for website publishing (topics) |
     | ==pub/DemoWebsite/WebPreferences/== | Demo web for website publishing (attachments) |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
     | ==templates/view.demo_website.tmpl== | Demo publish skin |
   * Configure and test the installated Plugin:
      * Run the [[%SCRIPTURL{configure}%][configure]] script:
         * Plugins section: Enable the Plugin.
         * Extensions section: Configure these settings:
            * ={Plugins}{PublishWebPlugin}{TemplatePath}=: Template path where skin files are located.
               * If empty or omitted: the =twiki/templates= directory is assumed; normal %SYSTEMWEB%.TWikiTemplates search path applies, e.g. for a =PUBLISHSKIN = website= setting, a =twiki/templates/view.website.tmpl= template file is assumed
               * If specified: Must be an absolute path; skin is assumed to be an html page at that location, e.g. for a =PUBLISHSKIN = website= setting, a =$TWiki::cfg{Plugins}{PublishWebPlugin}{TemplatePath}/website.html= file is referenced
            * ={Plugins}{PublishWebPlugin}{PublishPath}=: Path where the plugin places the generated html files.
               * Specify an absolute or relative path
               * If relative, path is relative to =twiki/pub=, such as ='../../html'=
               * Example to publish to multiple virtual hosts, one for each publish web: ='/var/www/vhosts/%<nop>LCWEB%/html'=
            * ={Plugins}{PublishWebPlugin}{AttachPath}=: Path where the plugin places images and other topic attachments.
               * Must be relative to =$TWiki::cfg{Plugins}{PublishWebPlugin}{PublishPath}=, default is ='_publish'=
            * ={Plugins}{PublishWebPlugin}{PublishUrlPath}=: URL path that corresponds to ={PublishPath}= directory. Leave empty if it is the HTML document root.
            * Note that all path settings may include these variables:
               * =%<nop>WEB%= - name of the publish web
               * =%<nop>LCWEB%= - lower case name of the publish web (preferred over mixed case)
               * =%<nop>SKIN%= - name of the publish skin 
         * Manual setup: Instead of using the configure script you can add/customize these =twiki/lib/LocalSite.cfg= settings: %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{Enabled} = 1;= %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{TemplatePath} = '';= %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{PublishPath} = '/path/to/apache/html';= %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{AttachPath} = '_publish';= %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{PublishUrlPath} = '';= %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{RequirePublishVariable} = 1;= %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{PublishAreaStyle} = 'border-left: 4px #1b1 dotted; margin-left: -14px; padding-left: 10px;';= %BR%
           =$TWiki::cfg{Plugins}{PublishWebPlugin}{Debug} = 0;=
      * Configuration on shell level:
         * Create the directory indicated in the ={PublishPath}= setting if needed
         * Create the directory indicated in the ={AttachPath}= setting (relative to ={PublishPath}=)
         * Change the permission of directories indicated by ={PublishPath}= and ={AttachPath}= to be writable by the webserver user (such as user =nobody= or =apache= on !RedHat Linux)
      * Test publishing using the !DemoWebsite web:
         * Go to DemoWebsite.WebHome web
         * Edit and save the !Index topic
         * Check if directory =$TWiki::cfg{Plugins}{PublishWebPlugin}{PublishPath}= has an =index.html=
         * Point your browser to that location to look at the generated =index.html= file
   * Create your own publish web:
      * Create a new publish web based on the !DemoWebsite web, or rename the !DemoWebsite web to a memorable name
      * If you create a new web, make sure to set these settings in !WebPreferences: Set the =NOAUTOLINK= setting to =on=, and set the =PUBLISHWEBPLUGIN_*= settings as in the !WebPreferences of the !DemoWebsite web
   * Create your own publish skin:
      * Create a skin that matches the look of your website. The [[%SYSTEMWEB%.TWikiSkins][TWiki skin]] can be derived from any =twiki/templates/view.*.tmpl= skin file, or can be created from scratch. This plugin contains a bare bone unstyled demo skin called =demo_website= located at =twiki/templates/view.demo_website.tmpl=
      * Omit any links to TWiki, such as edit and attach links
      * The skin can use plugin specific settings =%<nop>PUBLISHWEB{"breadcrumb"}%= and =%<nop>PUBLISHWEB{"nicetopic"}%=
      * The skin can introduce skin specific !WebPreferences settings, such as =%<nop>PUBLISH_SITE%=, =%<nop>PUBLISH_LOGO%=, etc.
      * Activate the new skin with a !WebPreferences settings, such as =* Set PUBLISHWEBPLUGIN_PUBLISHSKIN = mypublish=
      * You can have multiple publish skins; see note in the PUBLISHWEBPLUGIN_PUBLISHSKIN plugin setting above.
%ENDTWISTY%

---++ Known Limitations

   * All attachments are copied into the same directory, e.g. attachments in different topics that sharing the same name will overwrite each other in the published space.
      * Workaround: Make sure to use unique filenames across all topics in your publish web and in your skin

---++ Plugin Info

   * One line description, shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = TWiki CMS - maintain a static website collaboratively in a TWiki web

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2006-2016 Peter Thoeny, TWiki.org <br /> &copy; 2008-2016 TWiki:TWiki.TWikiContributor <br /> &copy; 2013 Wave Systems Corp. |
|  Sponsor: | [[http://www.wave.com/][Wave Systems Corp.]] for 2013-04-25 enhancements |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2016-03-27 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}%"
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2016-03-27: | TWikibug:Item7738: Add publish_topic context when publishing a topic |
|  2016-01-17: | TWikibug:Item7708: Copyright update to 2016 |
|  2014-12-04: | TWikibug:Item7593: Fix for TOC links not working properly -- TWiki:Main.MichaelSprague |
|  2014-10-26: | TWikibug:Item6968: Fix for mangled HTML anchors on published pages -- TWiki:Main.MichaelSprague |
|  2014-05-22: | TWikibug:Item7368: Fix for external https links not linking properly |
|  2013-08-08: | TWikibug:Item7313: Convert links properly in !DoxygenImportPlugin generated topics |
|  2013-05-14: | TWikibug:Item7154: Show <span style="border-radius: 4px; color: #fff; background-color: #4c4; text-align: center;">&nbsp;P&nbsp;</span> box at the top of the green dotted line to better indicate the publish area |
|  2013-04-25: | TWikibug:Item7244: New {RequirePublishVariable} configure flag to require STARTPUBLISH and/or STOPPUBLISH in topics that should be published; if flag is set, the publish area of a publish topic is indicated by a green dotted line at the left page margin; exclude topic from publishing if any of its ancestors (parents) is listed in the PUBLISHWEBPLUGIN_EXCLUDETOPIC setting; after publishing show "TopicName" link label instead of "Web.TopicName"; hack fix to make !TreeBrowserPlugin work in "re-publish all" mode |
|  2013-02-15: | TWikibug:Item7091: New PUBLISHWEBPLUGIN_PUBLISHSUBDIR preferences setting |
|  2013-02-07: | TWikibug:Item7091: Configurable breadcrumb item separator |
|  2013-02-05: | TWikibug:Item7123: Use TWISTY in installation instructions and change history |
|  2013-02-05: | TWikibug:Item7091: Document that attachments share one and the same namespace |
|  2012-10-21: | TWikibug:Item6818: Remove obsolete WEBFORMS preferences setting |
|  2012-06-12: | TWikibug:Item6837: Small doc fix in configure settings -- TWiki:Main.RayMikkelson | 
|  2012-03-06: | TWikibug:Item6857: Remove topic preferences, use only configure settings and PUBLISHWEBPLUGIN_* settings | 
|  2012-03-05: | TWikibug:Item6856: Publish multiple webs feature, useful for virtual host publishing -- TWiki:Main.JohnVestrum |
|  2012-02-28: | TWikibug:Item6853: Add demo publishing web called !DemoWebsite to plugin; add Config.spec for easier configuration |
|  2012-02-25: | TWikibug:Item6851: Fix for re-publising a topic using !WebPublish uses !WebPublish for topic name instead of actual topic name |
|  2011-07-23: | TWikibug:Item6808: Fix for incorrect BASETOPIC used when topics are re-published; use registerTagHandler for PUBLISHWEB variable; hide topics specified in EXCLUDETOPIC from picklist in !WebPublish |
|  2011-07-23: | TWikibug:Item6773: Move config settings to =LocalSite.cfg=; support multiple skins; support template path outside TWiki file path; add view.website.tmpl as a publish skin for demo; possible to publish into sub-directory of html doc root indicated by {PublishUrlPath} setting; change global package variables from "use vars" to "our"; remove URL parameters in links of published page to make TOC and other TWiki internal links work |
|  2006-02-15: | Added =%<nop>PUBLISHWEB{"publish" topic="Name"}%= |
|  2006-02-13: | Initial version |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle 100%, %SYSTEMWEB%.FormattedSearch 100%, %TOPIC% 99% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences
This topic: TWiki > PublishWebPlugin
Topic revision: r0 - 2016-03-28 - TWikiContributor
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.PublishWebPlugin