Set up a new docs site

Install and configure

A Docs-Kit website is a Gatsby project with at least the @commercetools-docs/gatsby-theme-docs Gatsby theme installed. The theme is providing not only the visual design but also all core functionality.

To create a new documentation website, run the following command to initialize the basic folder for the new website. (Node.js is assumed to be installed).

yarn create-new-microsite

Follow the instructions in the console.

Once the new folder is created, look into the gatsby-config.js file inside the new website folder. Check if you want to change the site metadata or if you want to configure additional plugins. See the theme configuration documentation to see all the options.

const config = {
  flags: {
    FAST_DEV: true,
  },
  pathPrefix: '/site-template',
  siteMetadata: {
    title: 'Site template',
    description: 'CHANGE-ME',
    products: ['smokeTest'],
    contentType: 'test',
    breadcrumbs: 'CHANGE-ME',
    betaLink: '/beta',
    excludeFromSearchIndex: isProd && !shouldEnableSearch,
  },
  plugins: [
    ...configureThemeWithAddOns({
      websiteKey: 'site-template',
      auth0Domain: 'auth.id.commercetools.com',
      auth0ClientId: 'xLk8EDUCc8PKqCbrSJCnuahvn86nEn4z',
      selfLearningFeatures: ['complete-profile-modal'],
      hideLogin: true,
      aiAssistantTopbarButton: true,
      aiAssistantApiBaseUrl: 'https://assistant-api.commercetools.vercel.app',
      learnApiBaseUrl:
        isProd === 'true'
          ? 'https://learning-api.docs.commercetools.com'
          : 'https://learning-api.commercetools.vercel.app',
      additionalPrismLanguages: [
        'markup-templating',
        'json',
        'bash',
        'java',
        'scala',
        'csharp',
        'swift',
        'php',
      ],
    }),
  ],
};

Start the local preview server

Now start the development server:

yarn clean:develop

Once the dev server is up and running, you can see already a landing page and a first chapter in the navigation. Here you can see tha basic folder structure:

├── src
│   ├── content
│   │   ├── files
│   ├── images
│   └── data
└── static
    └── downloads

Start writing pages

The index.mdx in the src/content folder is your homepage. You can start to add some markdown content here.

All pages are served on a URL path that matches the filename inside src/content without the file extension. For example, src/content/example-topic/example-page.mdx in a page with path prefix my-site would be served as /my-site/example-topic/example-page in production.

All pages must be in MDX format.

Next steps

Head on to the following documentation to complete your setup and writing skills: