/

Variable substitution

APIdocs lets you define variables to be substituted with values provided at documentation build time. You can use them to insert timestamps, version numbers and any other dynamic values known at build-time.

Defining variables

Substitution variables are defined in the gatsby-config.js file of your documentation project. The list of variables is part of the @carrotsearch/gatsby-theme-apidocs plugin options. 

module.exports = {
  siteMetadata: {
    ...
  },
  plugins: [
    {
      resolve: `@carrotsearch/gatsby-theme-apidocs`,
      options: {
        navigation: `${__dirname}/src/navigation.json`,
        logo: `${__dirname}/src/logo.html`,
        footer: `${__dirname}/src/footer.html`,
        basePath: "src/content",
        variables: {
          "APIDOCS_STARTER_VERSION": projectPackage.version,
          "BUILD_TYPE": "public"
        }
      }
    }
  ]
}
Defining substitution variables in gatsby-config.js. This configuration defines two variables: APIDOCS_STARTER_VERSION and BUILD_TYPE.

Names of your variables can only contain alphanumeric and underscore characters.

Since gatsby-config.js is a regular piece of JavaScript code, you can compute variable values based on any resources available to Node.JS, such as environment variables or the contents of the file system.

Using variables

Once you have defined your substitution values, you can reference them in the source HTML files surrounded with the $ sign: 

<p>
  Version of this documentation: $​APIDOCS_STARTER_VERSION$<br>
  Build type: $​BUILD_TYPE$
</p>
Make sure variable values are sanitized!

APIdocs will insert the literal values of your variables into the output, HTML tags will not be escaped. Therefore, make sure the values you provide are properly sanitized and don't break the HTML structure of the whole page.