This page is part of the guide to developing technical documentation on Confluence. In this section we highlight some of the Confluence plugins that are useful for technical writers in designing and developing documentation. A plugin is an extension module that you can add to your Confluence site, to extend the wiki’s core functionality. It is similar to an add-on for your browser. Confluence plugins may be developed by Atlassian or by third parties. To find the plugins featured on this page, and other plugins too, visit the Atlassian Plugin Exchange. This page features plugins that provide the following extended capabilities:
|
On this page: |
Extended Wiki Markup Features
All wiki markup extensions are provided by macros in Confluence. Some macros are built in to Confluence. Other macros are supplied by plugins.
Quick Overview of Macros
Before looking at plugins, let's take a quick look at macros in general. There are two ways to add a macro to your page:
- Use the Macro Browser. This is the simplest and recommended way.
- Or insert the macro's name in curly brackets into the text of your page and specify the parameters.
A number of macros are shipped with your Confluence installation by default. See Working With Macros. Below we describe some plugins that provide additional useful macros for Confluence:
Composition Plugin
The Composition plugin adds some formatting features to compose a page in a more flexible way. Using the macros provided by the Composition plugin, you can:
- Outline your text blocks.
- Add tabs to a page.
- Flow your text around the images or diagrams on the page.
Using the Composition Plugin to Outline Text Blocks
Use the {cloak} macro to outline a text block.
Usage: The following code creates a text block named 'SeeAlso' for the outlined 'See Also' section within a page. The text block with id='SeeAlso' will be hidden after the 'See Also' title:
{composition-setup} h2. {toggle-cloak:id=SeeAlso} See Also {cloak:id=SeeAlso} h3. Working With Macros: [Link 1] [Link 2] h3. Working with Rich Text Editor: [Link 3] [Link 4] {cloak}
Alternatives: You can also use the {expand} macro available in Confluence by default, but this macro can outline only text of the same level and cannot hide headings within the text. The {expand} macro does not require parameters and just hides the text placed between the {expand} tags.
Note: If you need to outline a text block containing nested headings, consider the text structure. Maybe the block is too big. You could create a child page from this block to decompose the whole text. Then you can include and outline the text block using the {include} macro within {expand}.
Using the Composition Plugin to Add Tabs to a Page
Use the {deck} and {card} macros to separate content between tabs on the same page.
Usage: The following code creates two tabs with client information:
{composition-setup} h1. Client Name {deck:id=ClientName} {card:label=Basic} Client Company Name: Company [Client Web Site|http://url.com] Our projects: [Project1|Project1 Home] {card} {card:label=Contacts} Company CEO: John Brown, e_mail: brown@company.com {card} {deck}
The tabs on a page will look like this:
Using the Composition Plugin to Flow your Text around Images
Use the {float} macro to make your text flow around images or diagrams.
Usage: The following code demostrates how a picture can be surrounded by the description, as often shown in printed publications:
{composition-setup} {float:left} !shakespeare.jpg! {float} William Shakespeare (baptised 26 April 1564; died 23 April 1616) was an English poet and playwright, widely regarded as the greatest writer in the English language and the world's pre-eminent dramatist. ...
The page will look like this:
For more macros, see the Composition plugin page.
Scaffolding Plugin
The Scaffolding plugin allows you to create sophisticated page templates in order to add content easily and fast. Scaffolding templates are suitable for dynamically-filled data and allow people to create pages by completing form fields and selecting values from drop-down lists.
The Scaffolding templates are useful for creating pages with a well-determined structure, such as:
- API methods or property descriptions.
- Constant list.
- Feature description.
- Software requirement specifications.
Example: The following Scaffolding template creates a description of an API method:
h3. Method Name {text-data:methodName|required=true}{text-data} h3. Method Description {text-data:methodDescription|type=area|required=true|width=100%}description{text-data} h3. Parameters {table-data:parameters} || Name || Type || Mandatory || Description || | {text-data:paramName}ParamName{text-data} | {list-data:paramType}{list-option:Number}Number{list-option}{list-option:String}String{list-option}{list-option:DateTime}DateTime{list-option}{list-option:MACaddress}MACaddress{list-option}{list-option:IPaddress}IPaddress{list-option}{list-data} | {list-data:paramMandatory}{list-option:Required}Required{list-option}{list-option:Optional}Optional{list-option}{list-data} | {text-data:paramDescription|type=area}param description{text-data} | {table-data} h3. Return Value The returned value is an XML structure of the following format: \{code:xml\} \{code\} Where elements mean: {table-data:returnValues} || Name || Type || Description || | {text-data:paramName}ParamName{text-data} | {list-data:paramType}{list-option:Number}Number{list-option}{list-option:String}String{list-option}{list-option:DateTime}DateTime{list-option}{list-option:MACaddress}MACaddress{list-option}{list-option:IPaddress}IPaddress{list-option}{list-data} | {text-data:paramDescription}param description{text-data} | {table-data} h3. Remarks {text-data:remarks}remarks{text-data} h3. See Also
This template will look like this:
For more information on how to create templates in Confluence, see Adding a Template.
Alternatives: Confluence includes built-in templates which as useful for static data and simple text. For more information, see Working with Templates.
Notes: The Scaffolding (and any) template changes will affect only new pages created from the modifed template. In order to change the existing pages, you need to edit each individual page and add or modify the formatting manually.
For more information on Scaffolding, see the Scaffolding plugin page.
Extended Version Control
Attachment Checkout Plugin
The Attachment Checkout plugin adds check-out/check-in functionality for Confluence attachments. It allows you to control the versions of the documents attached to a page with the same file name.
Attachment checkout allows Confluence to warn contributors that the document is being edited by someone else. Note that there are no merge features for attachments.
Example: To store and control the versions of Project Vision documentation received from a customer on the Confluence page:
For information on working with attachments, see Working with Attachments.
For information on attachment versioning, see Attachment Versions.
Drawing Tools
Gliffy Plugin
The Gliffy plugin provides an embedded diagram editor. Gliffy allows you to create and edit diagrams directly from a Confluence page. It supports various diagram types (UML, business process, and so on).
Alternatives: As an alternative you can use the standalone version of Gliffy available at http://www.gliffy.com/. Gliffy online has a free basic version.
For more information, see the Gliffy plugin page.
Notes
- Installing plugins. If you decide to use additional plugins, your site administrator will need to install the plugins into your Confluence site. Refer to the documentation on installing plugins.
- Plugin support. Before installing a plugin into your Confluence site, please check the plugin's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on plugin support.
Further Reading
- A blog post about useful plugins and tools for exporting and importing content from/to Confluence: Technical Writing in a Wiki - Single Source Publishing (November 2010).
- Website for exploring and downloading the available plugins: Atlassian Plugin Exchange.
- Documentation on installing and configuring plugins: Installing and Configuring Plugins using the Universal Plugin Manager.
- Documentation on using macros: Working With Macros.
- Further Reading about Developing Technical Documentation on Confluence
Attachments:



