This page last changed on Jul 05, 2010 by smaddox.
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,
- 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.)
- 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.
- 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.
- (Optional) Follow the steps in the next section if you want to redirect Confluence's help links to point to your local documentation.
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.
- Change the page name for each individual help link.
Changing the Base URL for your Help Links
You can set the base URL via the Confluence Administration Console.
To change the base URL for your help links,
Go to the Confluence 'Administration Console'. To do this:
- Open the 'Browse' menu and select 'Confluence Admin'. The 'Administrator Access' login screen will be displayed.
- Enter your password and click 'Confirm'. You will be temporarily logged into a secure session to access the 'Administration Console'.
- Click 'General Configuration' in the left-hand navigation bar.
- Click 'Edit'.
- Change the 'Documentation Url Pattern' to determine the destination website for all your help links. This value forms the first part of the destination URL. For example, if you want to point your help links the 'DOC' space in your local Confluence site, your URL prefix will look like this:
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.
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 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,
- 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.
- Unzip the confluence-x.x.x.jar file into your temporary location and copy the help-paths.properties file.
- 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.
- Edit your new help-paths.properties file.
- 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:
You could change it to something like this:
- Restart Confluence.
Example of the Help Property File
Below is an example of part of the Confluence help-paths.properties file.
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:
- 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 standalone 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.
|