This page tells you how to set up a copy of the Confluence documentation on your own local Confluence site.

On this page:

Reasons for Setting up your own Local Documentation

You may wish to run the documentation locally. In addition, you may want to point Confluence's links at your local documentation.

• If you are working in an environment without an internet connection, you will need a local copy of the documentation.
• If you have customised Confluence, you may wish to update the documentation to reflect your changes.
• You may want to change the look and feel of the documentation to integrate into your company's intranet.
• Confluence's interface contains links to help pages in the online documentation on confluence.atlassian.com. You may wish to point these help links to a different destination. Possible reasons include:
  • You want to point the help links to a destination behind your firewall.
  • You may want to link to a translated version of the documentation.

Setting up your Local Online Documentation

To set up your own Confluence site with a copy of our Confluence documentation:

1. Install Atlassian Confluence, if you have not already installed it. (If you do not already have Confluence, ask for a free evaluation license or a starter license. You can use 'Anonymous' access to allow your users to view the documentation.)
2. Download the XML source code for the Confluence documentation. Note that the Confluence version of the XML source needs to be the same major Confluence version as your local Confluence site. For example, if the Confluence version in the XML is 3.0, you can import it into a Confluence site running version 3.0, 3.0.1 or 3.0.2. But you cannot import it into Confluence 2.9 nor into Confluence 3.1.
3. Import the XML file into your Confluence site. This will create a new space with key 'DOC'. Note: If there is already a 'DOC' space in your Confluence site, it will be overwritten. For detailed instructions, see the Confluence documentation on Restoring a Space.

4. Remove or adjust the customised header, footer and left-hand navigation bar in your new space.
   Explanation: When you create your new space from our XML source code, the space will inherit the Confluence 'Documentation' theme. The XML source code also includes the customisations we have made to the header, footer and left-hand navigation bar. These customisations include references to our Atlassian Documentationspace. Since your Confluence site does not have that space, you will see errors like this in the left-hand navigation bar, header and footer in your new space:

   Unable to render {include} Couldn't find a space with key: ALLDOC

   To fix these errors, take one of the following steps:

   • Customise the navigation, header and footer sections to suit your Confluence site or environment. See our documentation on configuring the Documentation theme.
   • Or restore the default left-hand navigation bar, by removing all content from the navigation, header and footer sections and selecting the 'Page Tree' check box. See our documentation on configuring the Documentation theme.
   • Or change the theme of your space to the Confluence default theme or another theme of your choice.
5. Download the XML source code for the additional documentation spaces listed below and import them into your Confluence site too.
6. (Optional) Follow the steps in the next section if you want to redirect Confluence's help links to point to your local documentation.

Additional Documentation Spaces Required

Why You Need the Additional Documentation Spaces

The Confluence documentation shares some content with other Atlassian products, such as JIRA. For the sake of efficiency, we reuse the same content across documentation spaces. You will notice that some of our pages contain an {include} macro that draws in content from another space.

For example, the following macro includes content from the Application Links (APPLINKS) space into the Confluence documentation space:

{include:APPLINKS:_securityTrustedApps}

You will need to import those documentation spaces into your Confluence site, to ensure that the reused content is accessible in your Confluence documentation.

Determining the Version Required

We supply different versions of the documentation, for each version of the software or plugin concerned. To see which version you need, take a look at the space key in the {include} macro concerned.

• If the space key has a number at the end, that number indicates the version. For example, 012 means version 1.2, and 011 means version 1.1.
• If the space key does not include a number, you need the latest version of the documentation.

Here is an example of an include macro that requires version 1.2 of the Application Links documentation:

{include:APPLINKS012:_securityTrustedApps}

This example requires the latest version of the Application Links documentation:

{include:APPLINKS:_securityTrustedApps}

List of Spaces Required

Retrieve the relevant version of the XML backups from these pages:

• Application Links
• Universal Plugin Manager
• User Management

Redirecting Confluence's Help Links to your Local Documentation

In some parts of the Confluence user interface, you will see hyperlinks that point to the documentation for detailed information. These hyperlinks are Confluence's help links. You can redirect Confluence's help links to point to your local documentation.

There are two types of configuration changes you can make to the help property file:

• Change the base URL that determines the destination website of all your help links.
• (Optional) Change the page name for each individual help link.

Changing the Base URL for your Help Links

The help links and base URL are contained in a property file. In summary, you will need to do the following:

• Make a copy of the property file that Confluence uses to control the help links.
• Place the copy in a given directory where it will override the default property file.
• Update the copy with your own values.

To change the destination of your Confluence help links:

1. Copy the confluence-x.x.x.jar file from your {CONFLUENCE-INSTALLATION}\confluence\WEB-INF\lib directory and place it in a temporary location.
   Note: Do not remove the JAR, just make a copy of it.
2. Unzip the confluence-x.x.x.jar file into your temporary location and copy the help-paths.properties file.
3. Put the copy of the help-paths.properties file into your {CONFLUENCE-INSTALLATION}\confluence\WEB-INF\classes directory.
   Note: The property file will override the file in the JAR.
4. Edit your new help-paths.properties file.

5. Change the help prefix, found at the top of the file. By default, the help prefix looks like this:

   help.prefix=http://docs.atlassian.com/confluence/docs-{0}/{1}

   If you want to point your help links the 'DOC' space in your local Confluence site, your URL prefix will look like this:

   help.prefix=http://confluence.mycompany.com/display/DOC/

   In addition, you can use the following special characters in the URL:

   
   
   • {0} – Optional. This value will be replaced with the version of Confluence running on your site.
   • {1} – Optional. This value will be replaced with the page name from the configuration file.

    

6. Restart Confluence.

(Optional) Changing the Links for Individual Help Pages

If necessary, you can also change the individual page names to point to specific pages in your local documentation. You may want to do this if you are using a translated version of the documentation, for example, or your own custom guide rather than a copy of the Atlassian documentation.

The help links for each page are contained in a the same property file as the help prefix, described above.

To change the destination for each page:

1. Follow steps 1 to 4 described above, to put your copy of the help-paths.properties file into your {CONFLUENCE-INSTALLATION}\confluence\WEB-INF\classes directory, and edit your new help-paths.properties file.

2. Change the individual page names to point to specific pages in your local documentation. In our example file below, the first key-value pair looks like this:

   help.restore.site=Restoring+a+site

   You could change it to something like this:

   help.restore.site=My+page+about+Restoring+Confluence

3. Restart Confluence.

Example of the Help Property File

Below is an example of part of the Confluence help-paths.properties file.

help.prefix=http://docs.atlassian.com/confluence/docs-{0}/{1}
 
## Page Names
help.restore.site=Restoring+a+site
help.manually.backup.site=Manually+Backing+Up+The+Site
help.configure.server.URL=Configuring+the+Server+Base+URL
help.configure.time.date.format=Configuring+Time+and+Date+Formats
help.edit.user.details=Editing+User+Details

The first line (help.prefix) shows the destination website of the help links. This value forms the first part of the destination URL.

• {0} – Optional. This value will be replaced with the version of Confluence running on your site.
• {1} – Optional. This value will be replaced with the page name from the configuration file.

Below the description '## Page Names' there are a number of key-value pairs.

• The key (such as help.restore.site) is an identifier used by Confluence to find the help link for a specific screen or dialogue.
• The page name (such as Restoring+a+site) is the URL-encoded page name that forms the last part of the destination URL.

Example of a Help Link

Here is an example of a Confluence screen with two help links, one on the words 'our online documentation' and another on 'More about daily backups':

Screenshot: Example of help links in Confluence

More Notes about Help Links

• The ability to configure the destination of the help links is available only in Confluence 3.3.x and later.

• Make sure that you keep all the key-value pairs for the page names in the help-paths.properties file. If you want to point them all to the same location, you should retain all the keys and replace all the page names with the same name. For example:

  help.prefix=http://myguide.mycompany.com ## Page Names help.restore.site=My+guide help.manually.backup.site=My+guide help.configure.server.URL=My+guide help.configure.time.date.format=My+guide help.edit.user.details=My+guide

• In the above instructions on configuring help links, we assume that you want to host your local documentation on your own Confluence site. Instead, you could choose to point the Confluence help links to an entirely different set of documentation, on a website or intranet. After reading through the instructions above, you will have an idea of how to adapt them for your own purposes.
• The help-paths.properties file is currently in the confluence-x.x.x.jar in the WEB-INF/lib directory. Instead, it should be a config file in the WEB-INF/classes directory. This will make it easy for people to change the values in the file and repoint their help links. It will also standardise the help design with that of JIRA and other Atlassian applications. This issue is tracked at CONF-20105.