Documentation for JIRA 6.3 EAP developer (EAP) releases only. Not using this? See below:
(JIRA 6.2.x documentation | JIRA OnDemand documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

On this page:

Why would I set up local online documentation?

You may wish to run the documentation locally, and have JIRA link to it. There are a few reasons you may wish to do this:

  • JIRA's interface contains links ( ) to help pages, some to pages within JIRA, but many to the online documentation on www.atlassian.com. For deployments in environments without an internet connection, a local copy of the documentation is desirable.
  • If you have customized JIRA, you may wish to update the documentation to reflect your changes, or add new pages.
  • You can change the look and feel of the documentation to integrate into your company's intranet.

How to set up local online documentation for JIRA 4.0.x and later

  1. Install Atlassian Confluence. (If you don't already have Confluence, ask for a free Evaluation License. You can use 'Anonymous' access to allow your users to view the documentation.)
  2. Download the JIRA Documentation's XML source. Note that the Confluence version of the XML source needs to be the same major Confluence version as your local Confluence site.
  3. Import the XML file into your Confluence site. (Note: if there is already a 'JIRA' space in your Confluence site, it will be overwritten.) For detailed instructions, see the Confluence documentation on Restoring a Space.
  4. If you are importing the documentation for JIRA 4.1 or later, you will need to remove or adjust the customized 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 customizations we have made to the header, footer and left-hand navigation bar. These customizations include references to our Atlassian Documentation space. 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:

    • Customize 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) If you want JIRA's help links ( ) to point to your local documentation, you will need to:
    1. edit JIRA's /WEB-INF/classes/help-paths.properties file and change the url-prefix line so that it points to the 'JIRA' space in your local Confluence site, e.g.:

    2. restart JIRA.

Additional documentation spaces required

Why you need the additional documentation spaces

The JIRA documentation shares some content with other Atlassian products, such as Confluence. 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 JIRA documentation space:

You will need to import those documentation spaces into your Confluence site, to ensure that the reused content is accessible in your JIRA 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:

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

List of Spaces Required

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

How to set up local online documentation for JIRA 3.13.x and earlier

JIRA licensees can download the XML source for the documentation.

To build JIRA's docs locally:

  1. Download Apache Forrest 0.5.1 (zip, tar.gz), used to render the docs.
  2. Download the JIRA Documentation's XML source (6.2Mb). Note: the download is restricted to JIRA license holders.
  3. Follow the JIRA_DOCUMENTATION.txt instructions in the package.

Local field documentation

If you just want to document usage of a custom field, please see Creating Help for a Custom Field.

  • No labels

4 Comments

  1. Anonymous

    I followed those instructions, and I have a couple of pages complaining about an unknow macro : htmlcomment.

    I am using the JIRA 4.1 documentation on Confluence 3.2. Is there an incompatibility there? Do I need to install an aditionnal plugin?

    1. It seems that this macro has been used in some of the FAQ docs — apologies. We will try to limit its use in future.

      None of the main documentation is affected.

  2. Anonymous

    comments are posted here

  3. An analysis of the JIRA 5.2 document zip file (entities.xml) shows the following spaces are used in 'include' macros: ALLDOC, APPLINKS, APPLINKS012, APPLINKS032, APPLINKS035, ATLAS, DEV, DOC, GADGETS, GADGETS010, GADGETS020, GH, PLUGINFRAMEWORK, SUPPORT, UPM, UPM015, USERMAN, USERMAN010, USERMAN020.

    How can this be cleaned up such that the documentation points to only one version of each documentation set?  Our users would prefer to not see multiple (up to 4x) sets of documentation (spaces) for each linked space.