PublishPlugin
Generates a static view of a web, as HTML files on disc, or as a PDF
, or as a zip
or tgz
archive file, or by uploading directly to an FTP server.
This is the most complete publishing solution for Foswiki.

PublishPlugin provides support for the generation of stand-alone HTML
from a web. It will generate fully rendered versions of a set of
Foswiki pages together with any attached files.
When you want to read a document stored in Foswiki, you have to have
access to the web server that hosts that document. There are times
when this may not be desirable, or even possible. For example:
- Foswiki is used to create documentation which has to be readable off-line
- Published versions of Foswiki pages must be read-only
- The Foswiki server is inaccessible to the audience (e.g. on the other side of a corporate firewall)
- You want an efficient, high-density snapshot of the wiki content
To address these requirements the
PublishPlugin supports the generation of several different document formats from Foswiki pages, including HTML and PDF.
Features
- All standard Foswiki macros are interpreted, and plugins are called
- Topic links internal to the wiki are translated to relative links
- Powerful support for choosing what content gets published
- Any links to the 'pub' areas of topics in the web are automatically resolved, and the referenced files copied
- Any links to images outside the wiki are resolved, and the image is stored in the output (requires LWP)
- Output in HTML or PDF
- HTML can be compressed in different archive formats
- Incremental output of HTML for efficient incremental publishing
- Full support for hierarchical webs
- Format-specific skins (such as viewpdf) can be specified
- Able to publish HTML and referenced files directly to a remote server via ftp
- Complete history of what was published, and when
- Fully compatible with BookmakerPlugin
Usage
The plugin can be used in a number of different ways:
- Via the Publish Form on this page
- Using a crafted
rest
call
- From a re-usable configuration topic
- From the command line
- Using BookmakerPlugin (if installed)
The quickest way to publish is by completing the following form.
The output is generated in a directory designated during
installation. The progress messages printed during documentation
generation tell you exactly where the output is. Admins can use the
PublishPluginControlCentre to manage the published output.
Publishing is an access-controlled process; before you can publish,
you have to have VIEW access to the topics you want to publish (and
CHANGE access to the publishing history topic, if you have asked for
one).
You can also create a
permanent topic in a web to
help with a repeated publishing process.

Most publishing tasks will only require setting the immediately
visible options. Other more advanced options can be accessed by
opening the collapsible sections.
Using a rest
call
Create a link that invokes the
rest
script and pass the current topic:
(added newlines for readability).
<a class='foswikiPopUp'
href='%SCRIPTURLPATH{"rest"}%/PublishPlugin/publish?%REVARG%;
topics=%BASEWEB%.%BASETOPIC%;
format=file;
rel='nofollow'>
Publish this page
</a>
Using Bookmaker
The Bookmaker allows you to select a number of topics by visiting them in turn and adding them to the book. Once your book is complete, you can return to this page to publish it.
To start the bookmaker, enable the BookmakerPlugin, and revisit this page to enable the interface. Once the bookmaker is running, visit the pages you want to add to the book and add them to the book. Once you are finished, use the bookmaker interface to return to this page to publish the results. To publish a book generated by Bookmaker, use the
%BOOKLIST{"Bookweb.BookName"}%
macro in the
topics
parameter.
Using a Publish Topic (configtopic)
You can create a publish topic that contains all the details needed to publish. This is just a topic with a series of standard preference settings (which correspond to the parameters described here) in it.
You can use the
PublishWeb topic in this web as a template for your own topics.
To use a publish topic, you must pass the
configtopic
parameter to the
publish
script set to the name of the topic to use to control publishing. This should be a full web.topic specification (if you only give a topic name it will pick the topic up from the Main).
Publishing from the command line
This is the recommended way to publish if you are regularly updating
published content.
Just
cd
to the
bin
directory, and
perl rest /PublishPlugin/publish
. Parameters are passed as name=value pairs, for example:
perl rest /PublishPlugin/publish topics='System.*,-*.Web*' format=file
The available parameter names are shown in the publish form above.
How-tos
How to control which parts of a topic get published
You can control what gets published from a topic using
%STARTPUBLISH%
and
%STOPPUBLISH%
control tags:
- If
%STARTPUBLISH%
is the first control tag seen in the file, everything before it will be ignored.
- Everything between
%STOPPUBLISH%
and the next %STARTPUBLISH%
(or the end of the topic) will be ignored.
-
%STARTPUBLISH%
and %STOPPUBLISH%
will be visible in the viewed topic, so you can easily see what will be published from the topic.
- If you don't want to see the tags in normal view, then just define global preferences STARTPUBLISH and STOPPUBLISH using
Set
. Set them to the empty string. That won't stop them being interpreted by the plugin, but will make them invisible in normal view.
Another good trick is to set up a special "publishing" web. Create topics in the web that %INCLUDE the topics from
other webs that you want to publish. You can use
STARTSECTION and
ENDSECTION to highlight what you want published. This way the "publishing" web gives you a view of exactly what will be in the published output, without the need for special publishing tags.
How to use Wildcard Patterns
A wildcard is a special string that you can put into a filename so that it matches a whole range of files:
String |
What it does |
Example |
What the example matches |
* |
Matches any string, including an empty string. |
*Cheese* |
Every topic with "Cheese" somewhere in the name (but not "cheese") |
? |
Matches any single character. |
Example1? |
Example10 and Example 1X but not example1 |
[...] |
Matches any one of the enclosed characters. A pair of characters separated by a hyphen denotes a range expression; any character that sorts between those two characters, inclusive, using the current locale's collating sequence and character set, is matched. If the first character following the [ is a ^ then any character not enclosed is matched. A - may be matched by including it as the first or last character in the set. A ] may be matched by including it as the first character in the set. Within [ and ] , character classes can be specified using the syntax [:class:] , where class is one of the following classes defined in the POSIX.2 standard: alnum , alpha , ascii , blank , cntrl , digit , graph , lower , print , punct , space , upper , word , xdigit . A character class matches any character belonging to that class. The word character class matches letters, digits, and the character _. |
B[aeiou]g |
Bag, Bog, Big, Beg, Bug |
Irrespective of the archive being used, local output is always generated in
the directory specified by the
{Plugins}{PublishPlugin}{Dir}
configuration setting. Administrators can
manage the contents of this directory from the browser using the
%PUBLISHERS_CONTROL_CENTRE%
macro (see
PublishPluginControlCentre).
If
relativedir is set, then it will be added to
{Plugins}{PublishPlugin}{Dir}
.
If
outfile is not set in the parameters it defaults to the name of the format being published.
Most formats generate a single file with a unique extension that identifies the format e.g.
.pdf
. When publishing a format that generates multiple files (e.g.
file
) then
oufile will be a directory.

The rendered data can get pretty big, and the publishing process itself puts a heavy load on the server, especially when using compression on large webs.
How to generate a Publishing History
Every time a web is published, then the results of that publishing step can be stored in a topic in the web, by setting the
history
parameter to the name of a topic. In order to publish a web, you have to be able to write to this topic.
If the selected publishing skin defines a
skin template called
publish_history
, then that template will be used as the basis of the history topic. This (for example) allows you to use a template with a skin to define access controls for the history topic. The template can refer to a Foswiki macro
%PUBLISHING_HISTORY%
to get the expanded history. The
basic_publish
skin provides
templates/publish_history.basic_publish.tmpl
for this purpose.
The history topic contains a list of all the parameters used, and the versions of the topics that were published, so it is very useful for tracking exactly what you publish. However it can grow very large, if (for example) you are updating a static site from the wiki content regularly.
How to attach the output to a Topic
If you are using an on-disk file store, such as PlainFile or one of the RCS stores, you can publish an attachment direct to an attachment on a topic.

Note that overwriting attachments this way is extremely dangerous, so this should only be done by experts! You have been warned.
- First set the
{Plugins}{PublishPlugin}{Dir}
to the same as {PubDir}
- Then publish with a
relativedir
setting that corresponds to the attachment directory for the web/topic that you want to attach to
- If {AutoAttachPubFiles} is enabled, it will automatically be attached to the topic.
Installation Instructions
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.
Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button.
Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will
not show up in the
search results.
You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install
If you have any problems, or if the extension isn't available in
configure
, then you can still install manually from the command-line. See
https://foswiki.org/Support/ManuallyInstallingExtensions for more help.
IMPORTANT Run
configure
and complete the installation in the
PublishPlugin section.
If you want to generate PDF files, you will need to install a PDF generator, for example
htmldoc
or
prince
. Find them using google.
Note that
htmldoc
can also be used to generate PostScript. See the
htmldoc
man pages for details.
If you want
zip
output you will have to install
Archive::Zip
.
If you want
tgz
output, install Archive::Tar.
If you want to use the
ftp
upload, you will need to install Net::FTP.
WARNING! Anything published is no longer under the
control of Foswiki access controls, and if you make the publish output
directory visible on the web then you may need to
take precautions to prevent accidental leakage of confidential information
by restricting web access to this directory, for example in the Apache
configuration.
One way to do this is to use the
viewfile
access rights management to control
access to the published content:
- Create a hidden web named e.g. Publish
- Make this web public readable (via WebPreferences; ALLOW/DENYTOPICVIEW)
- Create a topic PublishedContent
- Change PublishPlugin Settings in
configure
to publish to pub/Publish/PublishedContent
Access controles on
Publish
web and
!Publish.PublishedContent
will then
apply.
Dependencies
Name | Version | Description |
---|
File::Spec | >0 | Required. Used to analyse URL paths. |
File::Copy | >0 | Required. Used to move files around. |
File::Path | >0 | Required to manipulate directories. |
File::Temp | >0 | Required for temporary files. |
LWP | >0 | Optional. Used to include images referenced by absolute URLs |
Archive::Zip | >=0 | Optional. Required to generate .zip output |
Archive::Tar | >=0 | Optional. Required to generate .tgz output |
Net::FTP | >0 | Optional. Required for ftp publishing. |
htmldoc | | Optional. Required to generate .pdf output |
Digest::MD5 | >0 | Optional. Required for fast upload to ftp servers. |
Compatibility Notes for version 3.0
- Only tested on Foswiki 2.0.
- The
compress
parameter has been removed.
- The <nopublish> tag has been removed.
- The
templates
parameter has been removed. We couldn't find anyone who was using it. The template
parameter provides a subset of it's functionality.
- The
file
generator no longer deletes existing published content before publishing.
- The
web
, topiclist
, exclusions
and inclusions
parameters are still supported, but are undocumented and will be removed in a later version. They are ignored if topics
is given.
Change History
Info & Copyright
This add-on started life as the GenHTMLAddon, written by
Foswiki:Main/CrawfordCurrie at Motorola. It was then extended by Eric Scouten, and then further fixed and enhanced by
Foswiki:Main/CrawfordCurrie (
http://c-dot.co.uk). It has also been extended by
Foswiki:Main/SvenDowideit and
Foswiki:Main/MartinCleaver, and most recently refactored for Foswiki by
Foswiki:Main/CrawfordCurrie. Other significant contributors are
Foswiki:Main.ArthurClemens and
Foswiki:Main.MichaelDaum.
This code is a development of the Architectures and System Platforms group of Motorola Inc. and is protected by the following copyrights:
- Copyright © 2001 Motorola. All Rights Reserved.
- Copyright © 2002-2003, Eric Scouten.
- Copyright © 2004-2006 Crawford Currie http://c-dot.co.uk
- Copyright © 2006 Martin Cleaver http://www.cleaver.org
- Copyright © 2006-2017, Foswiki Contributors
The 2005 functionality improvements were sponsored by
Wind River Systems
The
pdf
and
tgz
output formats were made possible by
Sabio Labs
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details, published at
http://www.gnu.org/copyleft/gpl.html