Publish Web Plugin

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 (WikiWord names are possible too)
  • All links should be defined as double square bracket links, e.g. [[Topic]] or [[Topic][label]] (do not use WikiWord links)

Publish process

P
  • 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 %STARTPUBLISH% and/or %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 %STARTPUBLISH% and %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: %IF{   "context 'publish_topic'"   then="$percntINCLUDE{ClassHeader}$percnt"   else="$percntINCLUDE{ClassHeaderPublish}$percnt" }%

Variables

  • %STARTPUBLISH% - place in topic text where to start publishing
    • Optional, start from top if missing
  • %STOPPUBLISH% - place in topic text where to stop publishing
    • Optional, publish to end of topic if missing
  • %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
  • %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 %PUBLISHWEB{"nicetopic"}% to get the complete breadcrumb
    • The skin may contain a %PUBLISHWEB{"breadcrumb"}% variable to show the breadcrumb
    • Underscores in topic names are rendered as space
    • Example: You are here: Home > Customer Support >
  • %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

Show details toggleopen.gif Hide details toggleclose.gif
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 Main.TWikiPreferences. 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:

  • 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 TWiki Form with a form field called PublishSkin. It can be of any type, but a select dropdown box is probably most convenient.

  • Home label, used by %PUBLISHWEB{"breadcrumb"}%:
    • Set PUBLISHWEBPLUGIN_HOMELABEL = Home

  • Breadcrumb item separator, used by %PUBLISHWEB{"breadcrumb"}%:
    • Set PUBLISHWEBPLUGIN_HOMESEPARATOR = »

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.

Show details toggleopen.gif Hide details toggleclose.gif

  • Download the ZIP file from the Plugin web (see below)
  • Unzip PublishWebPlugin.zip in your twiki installation directory. Content:
    File: Description:
    data/TWiki/PublishWebPlugin.txt Plugin topic
    data/DemoWebsite/*.txt Demo web for website publishing (topics)
    pub/DemoWebsite/WebPreferences/ Demo web for website publishing (attachments)
    lib/TWiki/Plugins/PublishWebPlugin.pm Plugin Perl module
    templates/view.demo_website.tmpl Demo publish skin
  • Configure and test the installated Plugin:
    • Run the 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 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/%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:
          • %WEB% - name of the publish web
          • %LCWEB% - lower case name of the publish web (preferred over mixed case)
          • %SKIN% - name of the publish skin
      • Manual setup: Instead of using the configure script you can add/customize these twiki/lib/LocalSite.cfg settings: $TWiki::cfg{Plugins}{PublishWebPlugin}{Enabled} = 1; $TWiki::cfg{Plugins}{PublishWebPlugin}{TemplatePath} = ''; $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishPath} = '/path/to/apache/html'; $TWiki::cfg{Plugins}{PublishWebPlugin}{AttachPath} = '_publish'; $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishUrlPath} = ''; $TWiki::cfg{Plugins}{PublishWebPlugin}{RequirePublishVariable} = 1; $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishAreaStyle} = 'border-left: 4px #1b1 dotted; margin-left: -14px; padding-left: 10px;'; $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 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 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 %PUBLISHWEB{"breadcrumb"}% and %PUBLISHWEB{"nicetopic"}%
    • The skin can introduce skin specific WebPreferences settings, such as %PUBLISH_SITE%, %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.

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 TextFormattingRules topic:
    • Set SHORTDESCRIPTION = TWiki CMS - maintain a static website collaboratively in a TWiki web

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2006-2016 Peter Thoeny, TWiki.org
© 2008-2016 TWiki:TWiki.TWikiContributor
© 2013 Wave Systems Corp.
Sponsor: Wave Systems Corp. for 2013-04-25 enhancements
License: GPL (GNU General Public License)
Plugin Version: 2016-03-27
Show Change History toggleopen.gif Hide Change History toggleclose.gif
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  P  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 %PUBLISHWEB{"publish" topic="Name"}%
2006-02-13: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle 100%, FormattedSearch 100%, PublishWebPlugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/PublishWebPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/PublishWebPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/PublishWebPluginAppraisal

Related Topics: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

This topic: TWiki > PublishWebPlugin Topic revision: r3 - 2020-05-19 - TWikiAdminUser
 
This site is powered by the TWiki collaboration platformCopyright &© 1999-2025 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.