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.

• 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

• auth0Domain (optional): Needed if sso or self-learning modules are used. Indicates the auth0 application domain url (it is defined in the auth0 management app)

• auth0ClientId (optional): Needed if sso or self-learning modules are used. Indicates the auth0 client id (it is defined in the auth0 management app)

• hideLogin (optional): It's used only when the sso module is used. If defined and set to true it will hide the login information area in the top right corner of the site. Default: false

• learnApiBaseUrl (optional): Needed if self-learning module is used. Indicates the the learn API base url. It can be omitted if the host running the site matches the api host.

• aiAssistantApiBaseUrl (optional): Needed if ai-assistant module is used. Indicates the the ai assistant API base url.

• aiAssistantTopbarButton (optional): Defaults to false, a boolean telling if the ai assistant launch button should be displayed in the site topbar. The flag is only affecting the visibility of the topbar button, any other ai-assistant button added in the pages will be still visible and working.

• selfLearningFeatures (optional, Array): Needed if self-learning module is used. An array of strings indicating feature flags to toggle specific functionalities. Expected values:

  • status-indicator: feature flag to toggle the course and topics status indicator.
  • complete-profile-modal: feature flag to toggle the complete profile modal window functionality
  • page-ready: feature flag to toggle the detection of full page load (used for VRT snapshotting). It should be deactivated in production mode

Available Options for the Site Metadata

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

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

• breadcrumbs (required, string): Defines the text displayed as root breadcrumb in the site header.

• products (optional, array of strings): Defines which products the website relates to. Available options are: [Composable Commerce, Frontend, Checkout, Connect]. Changing this value will affect both AI search results and Algolia search. See algolia section for more information.

• contentType (optional, string): Defines the type of content in the website. Available options are: referenceDocs, guidedDocs, userDocs.

• 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.

• isSelfLearning (optional, boolean): Identifies a self-learning website.

• 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',
    products: ['CHOOSE PRODUCTS'],
    contentType: 'CHOOSE CONTENT TYPE',
    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');

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
      additionalPrismLanguages: [
        'markup-templating',
        'json',
        '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.