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:
- Create Your HTML Template
A project contributor creates a single Velocity-based HTML template file. The Confluence documentation has a Basic Introduction to Velocity that links to the Velocity User Guide. You'll want to read the Velocity User Guide to understand how to set template variables, write conditional statements, etc.
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.
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.
- Upload Template Static Resources
Static resources that your .html template file references are not imported into the Auto Export plugin - you need to place those in a separate location. The way we've done it for Shiro is to create a single purposefully reserved directory at the root of our website called static. So if our public website root is located here:
then all of our static content that we manage manually will be in this directory:
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.
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.
- Update Template Resource References
Once you've uploaded those resources to their appropriate place on people.apache.org filesystem, you need to now change your template to reference their runtime location where they will be when your page is served by the web server. We did this by setting a Velocity variable in our template that reflects the runtime site root:
Then you an use the Velocity variables in your html to reference their location:
Again, see Shiro's Auto Export HTML Template as an example.
- Set Up a Cron Job to Sync Auto-Exported Content
When Auto Export runs, it outputs its content into a different directory than your website filesystem location. You need to ensure that after Auto Export runs, the generated content will make its way to the correct filesystem location that will be published to the web server farm. You can do that by setting up a cron job on one of the project team member's people.apache.org account:
First make sure that when the crontab editor runs, it is using an editor that you feel comfortable in (VI, Emacs, etc):
Then execute the following crontab command, which will launch your preferred editor:
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):
Then save and exit the file.
These 3 cron lines say:
- Line 1: "Every minute (on the minute), rsync the Confluence auto-exported content from its output directory to my project's public website directory"
- Line 2: "Every minute (at the 5 second mark), ensure all the files in my project's public website are (recursively) made group readable and writable". You want other project team members to be able to write to them if necessary.
- Line 3: "Every minute (at the 5 second mark), ensure all the directories in my project's public website are (recursively) made group readable, writable and executable".
* The >/dev/null 2>&1 parts at the end of each line will swallow any output that would have been emailed to you if anything failed. Typically you'll see some innocuous permission-related messages that can be ignored. You can always take off that part on each line if you want regular emails - up to you.
- Ask a Confluence Administrator to Import Your Template
After you've updated your template to reference the correct resource paths and made your crontab entries, you need to find an Apache member with Confluence administrative privileges to add your template file to the Auto Export plugin configuration. Unfortunately only a Confluence administrator may perform this function - the plugin does not support per-project administrators. Check with your project mentors or the Incubator PMC as they will typically know who to contact.
Once they've added the template to the configuration, also (kindly) ask them if they would explicitly export your Confluence space so you can test the results. You can also change and save a wiki page at any time to trigger the export process and it will be copied to your project webspace when the cron job runs.
Note: This is why it is important to use CSS heavily in your template. Because you may not have direct access to change the template whenever you want, it is better to rely on CSS that you can change whenever you want.
- Verify Pages Export Correctly
After your template has been installed and you make modifications to your space pages, you should see them start to show up within a minute or two in your project's root web directory (again, for Shiro, this is in people.apache.org:/www/incubator.apache.org/shiro). Look inside the .html files and you should see your HTML template code surrounding the wiki content. If you see this, Auto Export and your cron job are running propertly.
- Wait For the Web Server Farm
As mentioned before, the static .html files exported to your /www/incubator.apache.org/projectname web directory need to propagate to an Apache web server farm that actually services HTTP requests. We don't have access to those machines, so we have to wait for an automated process (managed by Apache Infrastructure) to pick up the files in /www and sync them to the server farm. This process can take up to an hour or two.
After an hour or two, visit the site, hit refresh, and you should see any changes that you made previously in Confluence display as a nice page with your template's look and feel. You can make changes to Confluence pages from this point on and you won't need to touch the template or Auto Export settings again (unless you want to change the template).
Now you're done setting up Auto Export!
Please contact the firstname.lastname@example.org mailing list with errata.