User Guide

Classic Macro

The Advanced Codeblock Macro offers you the possibility to provide different configurations (testsystem1, testsystem 2) based on one base-configuration (content).

Therefore placeholders are used. You can use a placeholder via ${placeholder_name} in the content. When the macro is rendered it will be replaced by the set value.

Inserting the macro in Confluence®

Example macro body:

[testsystem 1]
base.url =
document.root = /www/server1

[testsystem 2]
base.url =
document.root = /www/server2

<VirtualHost *:80>
   DocumentRoot ${document.root}
   ServerName ${base.url}

The example above needs to be used as macro body

What does it look like

The macro then renders the following output:


The underlying syntax-highlighting-system is google prettify.

To use syntax-highlighting you have to select a programming language in the edit macro screen.

Usage for the Direct Download Feature

The Direct Download Feature provides a way to directly download the configuration.

An administrator could download the configuration directly on a linux machine by using commands like wget or curl.

To activate Direct Downloads you must check the checkbox when inserting the macro.

You have to provide a unique ID, otherwise the macro cannot generate valid download links.

The Direct Download Link resides in the right upper corner of the macro.

You have to authenticate via Basic Auth when downloading.

Example Direct Download

The following unix command demonstrates a Direct Download to a unix system.

The username for Confluence® is admin and the password foobar.

As outputfilename we choose my.config. You need to append &os_authType=basic to the DDL-url to tell Confluence® that BasicAuth is used.

If you want to strip all possible bad chars like non-space utf-8 chars that break your apache virtualhost config, use &asciionly=true which strips everything from your config except ASCII and ö ä ü ß.

wget --http-user=admin --http-password=foobar  --output-document=my.config


Specs Direct Download

Encoding with asciionly-modeASCII plus ä ö ü ß
AuthentificationBasic Auth

HTTP Status Codes

HTTP 200Download possible.
HTTP 410Auth-Problem. Not logged in to Confluence® or insufficient rights.
HTTP 500Internal error. Wrong url-parameters, Confluence® page does not exist any more. Confluence® logs the exeption to the logfile.

A Direct Download opens in a new window and looks like this:

Notice for using Direct Downloads

  • By changing the configname (in the example testsystem 1) the download link changes!
  • By changing the ID the download link changes!
  • The download link gets changed when the macro is moved to another page!
  • The data is internally stored as content properties of the Confluence® page.

Usage for the Direct Download List Feature

You can click on the downloadlist link to see a XML list of all downloadable links with human readable names.

For this Advanced Codeblock

the XML-List Output looks like this

<?xml version="1.0" encoding="UTF-8"?>
  <pagename>Advanced Topics</pagename>
  • The first pageproperty Block is for [foooo]
  • The second pageproperty Block is for [barrr]
  • The third pageproperty Block is for [rawdownloads]
  • The servlet will list all download Links for any Advanced Codeblock Macro on the page.

Note: When you upgraded from version 1.7 to 1.8 you will have to edit an save your Confluence® page before you can use this feature!





Remote Macro

This macro works the same way as the classic macro except that is has no macro body and uses a remote file instead.

Please read the documentation of the classic macro first.

Inserting the macro in Confluence®

Fill out the URL and other fields in the Macro Browser.

If your remotefile is password protected (Basic Auth) you can specify the http username and password.

The ID has to be alphanumeric.


HTTP Username-
HTTP Password-
Programming language-

What does it look like

This will produce the following result

Note: After any change on the macro click on the top right link to regenerate the cache.