This page describes how we use the Confluence Auto Export plugin to create a custom look and feel for our project's public website while still using Confluence to manage and host our content.
This page is especially useful if you're a member of another Apache project that wants to use Confluence as your content repository but have a nicely formatted custom look and feel that you can design.
The high level overview is that you create a custom look and feel in the form of an HTML template. Confluence is then configured to automatically export your project space to static .html files that conform to the template. This allows a project website to have a different look entirely than the default Confluence theme.
The generated 'templatized' static .html files are then served as the project's public facing website, which is beneficial for scalability - an Apache farm of web servers can serve the static files (doing what Apache does best), relieving the Confluence server from direct and/or heavy load.
Here are step-by-step instructions to enable this for your project:
Confluence Velocity Objects When writing your template, you will want to know about the Confluence Objects Accessible From Velocity. You can use these existing variables and macros from within your template as necessary. |
Also note that your template file can reference static assets such as images, css files and javascript as necessary. Typically a template designer will work in whatever design tool they like and test it out on browsers etc. Its just that the static assets themselves are not imported into the Auto Export plugin directly. They need to be hosted in a separate location. We'll cover that next.
Example: Here is Shiro's Auto Export HTML Template (as of 21 May 2010). You can use it as an example or modify as necessary for your own site in accordance with the Apache 2.0 license.
people.apache.org:/www/incubator.apache.org/shiro/
then all of our static content that we manage manually will be in this directory:
people.apache.org:/www/incubator.apache.org/shiro/static/
It is important that you don't create a Confluence page at the root of your Confluence space named Static as it will conflict with your manually managed static directory above.
Also note that because everything else in the /www/incubator.apache.org/shiro directory is auto-exported from Confluence, you really don't ever want to mess with any files in that directory. Stick to only manually editing things in the static subdirectory and you'll be fine.
So, if our .html template referenced some images, css, and javascript in an assets directory while we were designing the template, you'll need to secure rsync or sftp those resources to a matching directory structure on people.apache.org under our reserved static directory:
/www/incubator.apache.org/shiro/static/assets/images/header.jpg /www/incubator.apache.org/shiro/static/assets/css/style.css /www/incubator.apache.org/shiro/static/assets/js/some-javscript-library-minified.js ...
Heavy CSS For reasons that will become apparent later, it is recommended to make heavy use of CSS in your template as well as ensure that the CSS definitions are in an external static file and not embedded in the template itself: you will be able to freely change your CSS files in this static directory, while it will be much harder to change the template after it is installed. If your template heavily leverages CSS, you can change the CSS whenever you want. |
<!DOCTYPE html PUBLIC ... ASF license header here ... ## #set ($siteroot = "http://incubator.apache.org/shiro") ... other variables, macro definitions, etc here ... ## <html> ... rest of html template here ... </html>
Then you an use the Velocity variables in your html to reference their location:
<img src="$siteroot/assets/images/header.jpg"/>
Again, see Shiro's Auto Export HTML Template as an example.
> export EDITOR=vi
Then execute the following crontab command, which will launch your preferred editor:
> crontab -e
Ensure the following 3 cron lines* are in that file (where SPACENAME is the case-sensitive Confluence space name (in our case SHIRO) and PROJECTNAME is typically your lower-case project name (in our case shiro):
0 * * * * /usr/local/bin/rsync -p -r /www/confluence-exports/SPACENAME/ /www/incubator.apache.org/PROJECTNAME >/dev/null 2>&1 5 * * * * find /www/incubator.apache.org/PROJECTNAME -type f -exec chmod g+rw {} \; >/dev/null 2>&1 5 * * * * find /www/incubator.apache.org/PROJECTNAME -type d -exec chmod g+rwx {} \; >/dev/null 2>&1
Then save and exit the file.
These 3 cron lines say:
Please contact the dev@shiro.apache.org mailing list with errata.