Documentation for Confluence 5.7.
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

This page is part of the guide to developing technical documentation on Confluence Wiki. In the page about creating your technical documentation space, we showed you how to set up an 'inclusions library' to contain content that you can re-use on more than one page. Now we offer further guidelines on re-using content in your documentation space.

Your documentation may be about using a software application, or it may be a technical manual for your product range. On this page, we use the term 'widget' to describe the things that you are documenting, such as the screen, form, document, product or object.

Quick guide to re-using content:

  • Create an 'inclusions library' to manage your re-usable content. See our guide to creating your technical documentation space.
  • Use the excerpt macro to define a re-usable section ('excerpt') on a page, or just decide to re-use the entire content of the page.
  • Use the excerpt-include macro to include the excerpt from one page onto another page.
  • Use the include macro to include the entire content of a page onto another page.
  • Consider installing the Multi Excerpt add-on if you need to define multiple excerpts per page.

The rest of this page gives an overview and more details of the above procedures.

Reasons for re-using content

A golden rule for technical documentation is to write the content only once but allow that content to be used in many places and in many forms.

For example, you may have the following types of content:

  • A technical manual that describes each widget in detail.
  • Tips and tricks on how to get the most out of the widget.
  • A step-by-step user guide for first-time users on how to use the most common widgets.
  • A training manual with exercises or videos that people can follow in their own time.
  • A one-page cheat sheet for users to stick up on their workstation.
  • Text for a sales brochure that is sent out to a print house for production.

Each of these types of content will share common information, such as a glossary entry, a technical or marketing description of the widget, or a step-by-step guide on how to use the widget.

Some initial planning of your technical documentation will allow you to re-use any or all of the content you write, so there is only ever one place to update the content, and those changes flow through to all of your other documentation.

Defining an inclusions library

We recommend that you create an 'inclusions library' to manage your re-usable content. If you have not already done this, see our guide to creating your technical documentation space.

Working with excerpts and inclusions

Excerpts and inclusions (sometimes called 'includes') are very useful for re-using content:

  • Use the Excerpt macro (excerpt) to define a re-usable section ('excerpt') on a page.
  • Use the Excerpt Include macro (excerpt-include) to include the excerpt on another page.
  • Use the Include Page macro (include) to include the entire content of a page onto another page.

A simple use case for an inclusion is a note or warning that is used in many places in your documentation. Here is an example:

Example note -- "Draft in progress"

This document is still in draft status. Please treat the content with caution.

Tip: Keep your re-usable pages short and sweet. Do not worry if you find that you need hundreds of pages to hold your inclusions. It helps to keep things separate and organised.

Using the Include Page macro

In this example, we use the Include Page macro to create a note that you can re-use on your documentation pages. The Include Page macro will include the entire content of one page into another page.

  1. Create a page in your inclusions library called _Draft Note.
  2. Add the content of the page. In this example, we use the Note macro with some text in the title and body:

  3. Use the Include Page macro to include that note in any page in your documentation. For example:

See the documentation on the Include Page macro for more details.

Using the Excerpt Include macro

An excerpt is a section of a page that you can include into another page.

  1. Use the excerpt macro to define any content in your page that you want to be able to use elsewhere. This content can be as short as a word or as long as the entire page. For example, let's assume we have a page called 'My Short Poem':

  2. Use the Excerpt Include macro to include the excerpt into another page. For example:

You can only define one excerpt on a page. See the documentation on the Excerpt Include macro for more details.

To have multiple excerpts on a page, see the 'Multi Excerpt add-on' below.

Using the Multi Excerpt add-on

The Multi Excerpt add-on provides additional macros that enable you to have multiple excerpts on a page. A good example of where you would find this useful is in the glossary page discussed below. If you want to include a single glossary entry or a subset of the glossary entries in another page, then the named excerpts provided by the Multi Excerpt add-on are very useful.

Notes:

  • The Multi Excerpt add-on is a commercial add-on and is not free.
  • Your Confluence system administrator will need to download and install the add-on into your Confluence site before you can use the macros described below. Refer to the documentation on installing add-ons.
  • Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on add-on support.Please refer to the Multi Excerpt add-on page for support details.

To have multiple excerpts on a page:

  1. Use the following code on the base page containing the content you want to use elsewhere:

  2. Use the following code on the page where you want to include the named excerpt:

  3. You can also include excerpts from other spaces using the following syntax:

See the Multi Excerpt add-on page for more details.

An example of content re-use: a glossary

A glossary is something that most technical documentation will require. There are a few ways to set up glossaries in Confluence. These are the most popular:

  • All glossary entries on one page.
  • Each glossary entry on separate child pages with a main page showing excerpts of the glossary.

Once you have defined the glossary entry, you can refer to it from the main pages of your technical documentation.

Creating a one-page glossary

This style of glossary is useful if the glossary entries tend to be short and there are not too many of them. The code blocks below use wiki markup. To insert wiki markup onto your page, open the editor and chose InsertWiki Markup.

  1. Create a page named Glossary.
  2. Add an alphabetical index at the top of the page and a heading for each letter of the alphabet:

  3. Enter each glossary entry under the relevant alphabetical heading. Each glossary entry (term) should include:
    • An anchor tag, so that you can link to it from other pages.
    • The term itself.
    • A definition of the term.
    • A link to the page in your technical documentation that explains the term in greater detail, where relevant.

  4. Optionally, include a horizontal line between the terms. This depends on how long each entry is. If your glossary tends to have short entries, it may look too cluttered with horizontal lines.

Creating a glossary with child pages

This style of glossary is useful if the glossary entries tend to be quite long or have additional information over and above the definition of the term. The code blocks below use wiki markup. To insert wiki markup onto your page, open the editor and chose InsertWiki Markup.

  1. Create a page named Glossary.
  2. Create a child page for each glossary entry (term). Each child page should contain:
    • The term as the title of the page.
    • The definition of the term in the body of the page.
    • Excerpt tags (excerpt) tags surrounding the definition.
    • Any additional information after the excerpt tags.

  3. On the 'Glossary' page, use the children macro to show the excerpts from each child page in a list, with the page name displayed in 'h4' style.

See the glossary in the Crowd documentation for an example of this style of glossary.

Referring to glossary terms

In the main pages of your technical documentation, create a link to the glossary page for each glossary term.

Note that this is a standard page link with an anchor. We have formatted the link as italics, because it helps to have the glossary links looking different to other page links. Readers can just skip over the glossary link if they are already familiar with the term.

Further reading

A blog post about content re-use: Technical Writing in a Wiki - Content Re-use and Structure (November 2010).

Next Steps

You now have a good idea of how to re-use content in a Confluence documentation space. What next? Take a look at Managing the Life Cycle of your Technical Documentation.

12 Comments

  1. Anonymous

    You could also make a glossary using the azList plugin.

  2. Is there a possibility to have the same page several times in table of contents? Maybe it is possible to change name the way it won’t be visible for user?

    I have same chapters, in which part of the sub-pages are different, and some should be the same with the same title.

    Schematic table of contents:

    1. Abc
      1. Def
      2. Ghi
      3. Jkl
      4. Mno

    2. Prs
      1. Tuw
      2. Ghi
      3. Jkl

    I would be grateful if you could help me.

    1. Hallo Aleksandra

      In Confluence, it is not possible to have more than one page with the same name in the same space. In other words, you can't have duplicate page names in one space.

      There are a few ways you can do what you want to do:

      • Use a different space for each tree in your table of contents.
      • Or install the Scroll Versions plugin, which adds the ability to have duplicate page names in a space.
      • Or you could write your own plugin to hide the first part of the page title from readers, when it follows a given pattern. For example, your page titles could be "Abc - Jkl" and "Prs - Jkl", and you could show only the parts after the hyphen. This would involve some coding. The best place to ask for that sort of help is at Atlassian Answers.


      I hope this helps!

      Cheers, Sarah

  3. Thank you Sarah

    I'll try to do as you recommend.

     Regards

    Aleksandra

  4. Anonymous

    Is there anything in the backlog to be extend the excerpt include macro to reuse content across spaces? This would be a valuable extension for our use cases.

    Regards

    Mike

    1. Hallo Mike

      The Excerpt Include macro can now include content from other spaces. This improvement came in Confluence 4.3.2. Yaayyy. (smile)

      Cheers

      Sarah

  5. Anonymous

    Sarah, can you please provide us with the detailed instruction on how to include content from other spaces? It just didn't work when I was using standard multiexcept-include macro. It didn't work either as I included it into the Wiki Markup macro in the following format: {multi-excerpt-include:spaceKey:pageName|name=excerptName|nopanel=true}.
    We are using Confluence 4.3.6.

    Thank you!
    Olha 

    1. Hi Olha, the Multi-Except Include is a commercial plugin. You can find some documentation and support information for using this plugin here https://artemis.atlassian.net/wiki/display/CMEP/Confluence+Multi-Excerpt+Plugin+Home.

      Hope this helps, Rachel. 

  6. Anonymous

    Thanks a lot for the answer, Rachel!
    I will try this plugin.

  7. Anonymous

    One more questions. Our organisation actually has this commercial Multi-Except plugin, and it works perfectly fine when used within one space. However, it doesn't work when I try to include into one space content from the other space. How to deal with such an issue?
    We are using Confluence 4.3.6. 

    Thanks,
    Olya 

  8. Anonymous

    Oh, we found a way to include into one space content from the other space.
    In the PageWithExcerpt * field of the Multiexcerpt include macro you need to specify the spacekey of that other space followed by the topic name, and separated by a column:


    spacekey:topic name


    In the field below we also have to specify the MultiExcerptName, as usual. 
    Hope that helps to other folks who also experienced issues with that (smile) 

  9. Is there an option to display in one space all the pages from another space that have a specific label?

    I cannot include them page by page.

    Thanks,

    Rakefet