This page is part of the guide to developing technical documentation on Confluence. In this section we highlight the built-in Confluence macros that are most useful in technical documentation. For more information about Confluence macros, see Working with Macros.
To add a macro to a Confluence page, use the Macro Browser.
On this page:
Auto-Generating a Table of Contents for Page Content
It is important to make it easy for viewers to jump to the section of a Confluence page that they are most interested in. The Table of Contents macro helps you navigate lengthy pages by summarising the content structure and providing links to headings used on the page. Headings are indented progressively.
- You document the Release Notes for the latest version of your product in a Confluence page.
- Each feature in the release is a heading on the page.
- You can generate a list of hyperlinks to each of the features in the release notes by inserting the Table of Contents macro:
- The image below shows the Table of Contents macro inserted at the top of the 'Release Notes' page. Note that we have excluded the 'Highlights of Confluence 3.4' heading from the table of contents by modifying the macro's parameters.
- The image below shows the macro parameters specified in the Macro Browser. Note the 'Minimum Heading Level' and 'Maximum Heading Leve' parameters.
Drawing Attention to Elements of a Page
Often when creating documentation there are elements of a page that you want to highlight, or draw the the viewers attention to. Confluence ships with the following macros that help you focus a viewer's attention to a note, information, tip or warning.
Putting Content inside Customisable Panels
The Panel macro allows you to place content inside a customisable coloured panel. This is particularly useful when you want to clearly separate elements on a page.
- You are documenting a procedure which involves a number of steps.
- You want to call out the steps of the procedure from the rest of the page by placing it inside a coloured box, or panel.
- You can create a coloured panel using the Panel macro.
- The image below shows the parameters set for the panel using the Macro Browser.
Inserting Anchor Links on Pages
Anchor links can be especially useful when navigating between sections of a long document or when you want to link to a segment of a page from another page. The Anchor macro allows you to link to specific parts of a page.
- You are documenting part of a user guide.
- The page is split into multiple sections.
- After each section you want to provide a link for viewers to click, taking them back to the top of the page.
- To achieve this you first must create an anchor at the top of the page using the Anchor macro. You can give the anchor any name you like. In the image below, the anchor at the top of the page has been named 'top'.
- Create a link to the anchor, anywhere on the page, using the Link Browser. The image below shows a link to the anchor called 'top', with an alias of 'Return to top of page'.
See Working with Anchors for more examples and instructions.
Structuring Content using Sections and Columns
Sometimes it is necessary to structure content into sections and columns.
- You can create any number of sections on a Confluence page using the Section macro.
- Each section can contain any number of columns, created using the Column macro.
- Columns can either have a fixed width, specified in pixels, or a dynamic width, specified as a percentage of the page width.
- Note: A column must be created inside a section
The images below show part of a Confluence page with two sections (red), each with two columns (blue) of different widths.
- Section 1:
- Section 1 columns – left column has a fixed width of 400 pixels:
- Section 2:
- Section 2 columns – left column has a fixed width of 10 pixels:
Making your Documentation more Engaging by Embedding Videos
Pictures can be worth a thousand words. The same can be said for videos. Often, it's easy to explain a concept or demonstrate a procedure using a video. The Widget macro allows you to embed web content, including YouTube, Episodic and Vimeo videos, in a Confluence page.
- You release a new version of your product.
- You document the Release Notes on a Confluence page.
- The marketing team creates a video demonstrating the new features of the release and uploads it to YouTube.
- You can embed the video in your Release Notes using the Widget macro, for playback on your Confluence page.
- Select 'Widget' from the 'Insert' menu in the Rich Text Editor toolbar.
- Insert the URL of your YouTube video into the 'Web Sites Widget URL' field.
- Click 'Insert' and save your page.
- Select 'Widget' from the 'Insert' menu in the Rich Text Editor toolbar.
See Widget Macro for information on the supported services and for more usage examples.
Next Steps
Take a look at Confluence Plugins for Technical Documentation.