Variables

Project Variables help you label parts of your documentation that are repetitive, to be able to change them centrally in one place. It also allows you to personalise the documentation for your readers.

For example, you might want all of API reference to use the latest version in their example requests. Without variables, you would need to upload a new reference containing changes to each example request every time you update the version.

One of the example requests might look as such:

var options = {

 "method": "GET",

 "url": "https://api.your-service.com/user",

 "body": {

   "version": "2019-10-12", // <-- change this to "%latest_version%"

   "id": 512

 }

};

​

request(options, function (error, response, body) {

  if (error) throw new Error(error);

​

  console.log(body);

});

With variables, you'll be able to centrally change version value, saving you time and effort.

How to use Project Variables?

There are two things needed to get project variables setup:

• Add a JSON object of the variables that will be available in the documentation.
• Insert variable references in the documentation by wrapping it in percent signs as such %variable%.

Where can you use Project Variables?

Project variables can be inserted in:

• Page content and blocks.
• API Reference descriptions.
• Index external links.
• Custom javascript.
• Default landing page layout.
• Custom HTML in landing pages.

Editing Project Variables

To edit project variables, do the following:

• From the sidebar, select Project Settings
• Under Project Variables, click on the button on the right.
• Enter a JSON object defining all your variables. For example:

{

  "project_name": "Xyz",

  "versions": {

    "latest_version": "1.54.2"

  }

}

Using Project Variables in References

To use project variables in an API Reference, replace all occurrences of the variable with the variable reference. For example, one definition property could be:

version:

    type: string

    description: Version of the API

    example: "%versions.last_version%"

Or to replace a variable named subdomain in the Server URL:

servers:

  - url: https://{subdomain}.developerhub.io/api/v1

    variables:

      subdomain:

        default: "%subdomain%"

Using Project Variables in Scripts

To use project variables in scripts, you must first set up the project to expose variables through window.vars object. To do that:

• From the sidebar, select Project Settings
• Under Project Variables, click on the button on the right.
• Check Expose Variables in Javascript.
• Click Save.

For the published docs, once the project loads, you'll be able to access the variables (defined under Project and injected through personalisation) through window.vars.

Personalising Docs

You can use variables to personalise docs. Read more about it in Personalised Docs.

Known Limitations

• Variables do not work as HREFs for links.