Before you start wondering, ‘deconfluencing’ is not a word you can lookup in Merriam Webster. Perhaps it should be. It certainly is something I needed, and eventually ended up creating myself.
Have you ever been in a position in which you had a lot of useful content inside Confluence, but you did not necessarily want it to be published out there as a Confluence web site, with all the bells and whistles it offers. If you were in that position, then the Deconfluencer might be just what you need.
The Deconfluencer is doing exactly what you would expect from its name. It takes a Confluence space, and republishes it, stripping off everything you don’t want, and rewriting the bits you want to have rewritten.
Let’s look at an example. Suppose this is your Confluence page:
Then the Deconfluencer could turn it into something like this:
Same contents, just rendered differently.
How does it work?
The Deconfluencer is simply a reverse proxy with some built-in transformation logic. (And some other features that come in handy when republishing Confluence content.) It’s not a war. It’s simply a commandline tool that – once started up – listens on a certain port, forwards incoming requests to Confluence, transforming the results before sending it back to the browser.
I don’t like your look and feel
Well, rightfully so. The good thing is, you can transform the Confluence page in any way you like. If you unzip a Deconfluencer distribution, you will find a conf directory with a filter.xsl file, and a resources directory containing static resources, such as CSS and imagery. To start with the latter: if you only want to change the CSS, then you simply change the style.css file, and you’re good. However, if what you want to do is a little bit more involved, you need to adjust the filter.xsl file.
The filter.xsl XSLT template is used to transform the page coming from Confluence into the resulting page. It is this file that actually generates a page header that points to the resources found in the resources directory I mentioned before. However, it also has some basic templates to filter out contents you probably don’t want to see. In order to be able to transform an HTML page using XSLT, the Deconfluencer first transforms the incoming XML into a DOM.
That sounds like a painful exercise
Well, it may sound that way, but it really isn’t. Once you started the Deconfluencer, you can simply update the filter.xsl file on the fly, and check out the results immediately after hitting the refresh button. Rest assure, the Deconfluencer will not load the template from the file system for every request. Instead, it will monitor the conf directory and only reload the filter.xsl file if the file was changed.
Overwriting existing files? I don’t want to do that!
Then you don’t. You don’t have to. You can also start the deconfluencer and point it to alternative locations. Simply run the deconfluencer without any options, and it will tell you which options you have to use. Just for sake of convenience: these are the commandline parameters it currently supports:
-b BASE URL : The base URL of the URL space we want to deconfluence. -f FILTER : The location of the XSLT filter to be applied. (Defaults to con f/filter.xsl.) -n PORTNUMBER : The portnumber on which the reverse proxy will run (8082) -o NAME=VALUE : Parameters to be passed to the transformation -p PASSWORD : The password used to authenticate to Confluence. -s PATH : Location to be used for serving static resources. (Defaults to resources/.) -u USERNAME : The username used to authenticate to Confluence. -v : Verbose mode. Logging data to std err.
Enough about that; where can I find it?
The Deconfluencer project is hosted on Github. You can download the sources and build it from scratch, but I have to warn you that JNotify is not listed in one of the central Maven repositories though, so you probably need to install that yourself. Alternatively, you can download a distribution from Github directly, by pointing your browser here.
There are certainly some things that could be improved. Like, currently it’s not dealing with attachments in a useful way. As a result, images you have on your Confluence page will most likely not show up correctly. It will not require a major overhaul, but it’s certainly something that would be nice to have.
Now, what do you think about all of this?
Does this sound sensible? Do you see other purposes for it? Feel free to comment, or – even better – just fork the project yourself.