Site and Theme Configuration

Available Options for the Theme

• websiteKey (required): the identifier of the website, used for error reporting and similar concerns. Usually this value would be the same as the pathPrefix without the leading slash and without whitespaces.

• colorPreset (optional): pick the "look and feel" of the website by choosing one of the available Color Presets. Default: base

• gaTrackingIds (optional, Array): List of tracking IDs to be passed to gtag.js. For all sites hosted on the docs.commercetools.com domain the IDs must be ["G-XGR7PSLVB2", "UA-38285631-3"] to fill both UA and GA4 concurrently for the time being.

  For test websites the gaTrackingId field should not be set.

• hubspotTrackingCode (optional): this is HubSpot tracking code.

• createNodeSlug (optional): in case you need to have more control over the creation of the page slugs, you can implement this function. This is useful if for example your website has content files in other file system locations and you want to provide a more meaningful URL path.

  type Options = { node: Node }; // A Gatsby Node
  type CreateNodeSlugFn = (originalSlug: string, { node }: Options) => string;

• availablePrismLanguages (optional): in case you need to include Prism languages that are not included by default by prism-react-renderer, you can pass a list of them here. For example, Java and PHP are not included by default, so you should usually set this configuration. Setting it also prevents regressions due to prism-react-renderer changing its defaults.

• overrideDefaultConfigurationData (optional, array of glob strings): allows to replace the configuration files in src/data instead of augmenting them. The option is passed to the ignore option of the gatsby filesystem plugin. For example, by passing ['**/top-*'] and placing top-menu.yaml and top-side-menu.yaml files in the website's src/data folder the top navigation can be overridden completely. If this option is used, the files matching the glob patterns must be provided.

• enableCanonicalUrls (optional): indicates that the website should use canonical URLs, pointing to the docs.commercetools.com domain. Default: true

Available Options for the Site Metadata

• title (required, string): Defines the title of the website.

• description (required, string): Defines the description of the website.

• beta (optional, boolean): indicates that the website should be marked as beta. Each page gets a beta flag, no matter if the page frontmatter has it defined or not. Furthermore, in the main navigation, the beta flag is shown near the website title and not next to each link. Default: false

• betaLink (optional, string): Configures the link for beta button.

• excludeFromSearchIndex (optional, boolean): indicates that the website should not be indexed by crawlers. This option sets the robots="noindex" meta attribute on all pages of the site. If true, the search box in the top navigation is not displayed. Default: true Note that the on-site Algolia Docsearch is not respecting the instruction, it is purely based on click-trough reachability from the home page.

• globalNotification (optional, object): Activates a global banner at the top of every page within the website. It contains three configuration options:

  • active (Boolean): flag to activate the global notification banner.
  • notificationType (String, must be either info or warning) defines the type and color of the banner.
  • content (String) defines the text within the banner.

  siteMetadata: {
    title: 'CHANGE TITLE',
    description: 'CHANGE DESCRIPTION',
    beta: false,
    betaLink: '',
    excludeFromSearchIndex: true,
    globalNotification: {
      active: true,
      notificationType: 'info',
      content:
        'This is a global notification. You can _write_ **markdown** here!',
    },
  },

Site path prefix

All commercetools documentation websites are served under docs.commercetools.com. To make this work, all documentation websites must be bundled for production using a pathPrefix. This value determines the URL path where the website is served from.

For example, for the "Custom Applications" website, the path prefix is /custom-applications.

The pathPrefix is configured in the gatsby-config.js file.

Usage with Theme Add-Ons

If your website requires the usage of add-ons, you need to configure the main theme using the configureThemeWithAddOns helper function. For example, the ability to generate REST API documentation or code blocks from files are add-ons. See examples below.

const {
  configureThemeWithAddOns,
} = require('@commercetools-docs/gatsby-theme-docs/configure-theme');
const colorPresets = require('@commercetools-docs/gatsby-theme-docs/color-presets');

module.exports = {
  pathPrefix: '/change-path-prefix',
  siteMetadata: {
    title: 'CHANGE TITLE',
    description: 'CHANGE DESCRIPTION',
    betaLink: '',
  },

  plugins: [
    // pass plugin options here
    ...configureThemeWithAddOns({
      // See available plugin options below
      websiteKey: 'change-website-key', // required
      colorPreset: colorPresets.base.key,
      additionalPrismLanguages: ['scala', 'csharp'],

      // See https://github.com/commercetools/commercetools-docs-kit/tree/master/packages/gatsby-theme-docs#using-theme-with-add-ons
      addOns: [
        '@commercetools-docs/gatsby-theme-code-examples',
        '@commercetools-docs/gatsby-theme-constants',
      ],
    }),
  ],
};

Additional configuration files

.eslintrc.yaml: in case you're using a monorepository, you need to provide this file with an empty object {}, otherwise provide a valid ESLint configuration.