Introduce new create-new-microsite script and update site template (#…

…2088)

* feat: introduce new create-microsite script + update site template

* fix: build issue

* fix: markdown-components file

* chore: remove markdown components from site template

* chore: improve shell script logs

* chore: remove markdown components file

* chore: add missing files

* chore: empty commit

* refactor: use correct eslint config

* chore: keep changelog

* chore: add comments

* chore: check in addon-components

* refactor: adjust documentation / gitignore / changelog

package.json

@@ -28,6 +28,7 @@
     "test:e2e:docs-smoke-test": "cross-env NODE_ENV=test cypress run --spec 'cypress/e2e/docs-smoke-test/**/*.cy.ts'",
     "test:e2e:api-docs-smoke-test": "cross-env NODE_ENV=test cypress run --spec 'cypress/e2e/api-docs-smoke-test/**/*.cy.ts'",
     "test:e2e:self-learning-smoke-test": "cross-env NODE_ENV=test cypress run --config-file 'cypress.config.cucumber.ts' --spec 'cypress/e2e/self-learning-smoke-test/*.feature'",
+    "create-new-microsite": "./scripts/create-new-microsite.sh",
     "cypress-open": "cross-env NODE_ENV=test cypress open",
     "check-links": "yarn exec linkinator ./public",
     "check-npm-login": "npm_config_registry=https://registry.npmjs.org npm whoami",

packages/gatsby-theme-docs/src/overrides/page-header-banner-area.js

@@ -1,8 +1,5 @@
 import React from 'react';
-import UserResearchBanner from '../components/user-research-banner';
 
 // A banner to be rendered in the top-right corner of a content page
-const PageHeaderBannerArea = () => {
-  return <UserResearchBanner />;
-};
+const PageHeaderBannerArea = () => null;
 export default PageHeaderBannerArea;

scripts/create-new-microsite.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const prompts = require('prompts');
+
+(async () => {
+  const response = await prompts({
+    type: 'text',
+    name: 'micrositeName',
+    message: 'What is the name of the new microsite?',
+    validate: (micrositeName) =>
+      micrositeName.length > 64 ? `Microsite name is too long.` : true,
+  });
+
+  const formattedMicrositeName = response.micrositeName
+    .replace(/\s+/g, '-')
+    .toLowerCase();
+  const micrositeTitle =
+    response.micrositeName.replace(/-/g, ' ').charAt(0).toUpperCase() +
+    response.micrositeName.slice(1);
+
+  const gatsbyConfigTemplate = `import { configureThemeWithAddOns } from '@commercetools-docs/gatsby-theme-docs/configure-theme.mjs';
+
+const isProd = process.env.NODE_ENV === 'production';
+const shouldEnableSearch = process.env.ENABLE_SEARCH === 'true';
+
+const config = {
+  flags: {
+    FAST_DEV: true,
+  },
+  pathPrefix: '/${formattedMicrositeName}',
+  siteMetadata: {
+    title: '${micrositeTitle}',
+    description: 'CHANGE DESCRIPTION HERE',
+    products: ['smokeTest'],
+    contentType: 'test',
+    breadcrumbs: '',
+    betaLink: '/beta',
+    excludeFromSearchIndex: isProd && !shouldEnableSearch,
+  },
+  plugins: [
+    ...configureThemeWithAddOns({
+      websiteKey: '${formattedMicrositeName}',
+      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',
+      ],
+    }),
+  ],
+};
+
+export default config;
+
+`;
+
+  const websitesFolderPath = `${process.cwd()}/websites`;
+
+  // Using the site template to create the new microsite folder
+  fs.cpSync(
+    `${websitesFolderPath}/site-template`,
+    `${websitesFolderPath}/${formattedMicrositeName}`,
+    { recursive: true }
+  );
+
+  // Overriding the gatsby config with the given microsite name
+  fs.writeFileSync(
+    `${websitesFolderPath}/${formattedMicrositeName}/gatsby-config.mjs`,
+    gatsbyConfigTemplate
+  );
+
+  // Overriding the package.json file with the given microsite name
+  const packageJson = JSON.parse(
+    fs.readFileSync(
+      `${websitesFolderPath}/${formattedMicrositeName}/package.json`
+    )
+  );
+  packageJson.name = `@commercetools-website/${formattedMicrositeName}`;
+  fs.writeFileSync(
+    `${websitesFolderPath}/${formattedMicrositeName}/package.json`,
+    JSON.stringify(packageJson)
+  );
+
+  // Creating a fresh CHANGELOG
+  fs.writeFileSync(
+    `${websitesFolderPath}/${formattedMicrositeName}/CHANGELOG.md`,
+    ''
+  );
+})();

scripts/create-new-microsite.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+set -e
+
+echo "Starting the process."
+
+yarn node ./scripts/create-new-microsite.js
+
+echo "New microsite created."
+echo "Installing dependencies."
+
+yarn
+
+echo "Process complete."
+Purple='\033[0;35m'
+echo -e "${Purple}Please add the new microsite to the build.sh script in the root folder to enable production builds."

websites/api-docs-smoke-test/gatsby-config.mjs

@@ -7,7 +7,6 @@ const config = {
   // https://www.gatsbyjs.com/docs/reference/release-notes/v2.30
   flags: {
     FAST_DEV: true,
-    PRESERVE_FILE_DOWNLOAD_CACHE: true,
   },
   pathPrefix: '/api-docs-smoke-test',
   siteMetadata: {

websites/api-docs-smoke-test/src/@commercetools-docs/gatsby-theme-docs/overrides/markdown-components.js

@@ -1,4 +1,3 @@
-/* eslint-disable import/no-anonymous-default-export */
 /* THIS IS AN AUTOGENERATED FILE. */
 
 // You can edit this file and additionally inject custom components into MDX.

websites/docs-smoke-test/gatsby-config.mjs

@@ -7,7 +7,7 @@ const shouldEnableSearch = process.env.ENABLE_SEARCH === 'true';
 
 const config = {
   flags: {
-    DEV_SSR: true,
+    FAST_DEV: true,
   },
   pathPrefix: '/docs-smoke-test',
   siteMetadata: {
@@ -28,7 +28,7 @@ const config = {
       aiAssistantApiBaseUrl: 'https://assistant-api.commercetools.vercel.app',
       aiAssistantTopbarButton: true,
       hideLogin: true,
-      selfLearningFeatures:['complete-profile-modal'],
+      selfLearningFeatures: ['complete-profile-modal'],
       additionalPrismLanguages: [
         'markup-templating',
         'json',

websites/documentation/gatsby-config.mjs

@@ -4,7 +4,6 @@ import dotenv from 'dotenv';
 dotenv.config({ path: `.env.${process.env.NODE_ENV}` });
 const config = {
   flags: {
-    DEV_SSR: true,
     FAST_DEV: true,
   },
   pathPrefix: '/documentation',

websites/documentation/src/content/getting-started/setup.mdx

@@ -6,33 +6,55 @@ title: Set up a new docs site
 
 A Docs-Kit website is a [Gatsby](https://gatsbyjs.com) 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, create an empty folder and run the following commands to initialize a minimal setup (Node.js is assumed to be installed).
+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).
 
 ```console
-npx install-peerdeps --dev @commercetools-docs/gatsby-theme-docs
-mkdir src
+yarn create-new-microsite
 ```
 
-This can take some time, creates a bare `package.json` file and downloads the dependencies.
+Follow the instructions in the console.
 
-Then create a file `gatsby-config.js` with the following content and modify the strings starting "change-" to your project name. The docs kit is preconfigured to host sites under a path prefix because one Gatsby website represents only one part (or "microsite") of the overall documentation.
+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](/configuration/theme) documentation to see all the options.
 
 ```js
-module.exports = {
-  pathPrefix: '/change-path-prefix',
+const config = {
+  flags: {
+    FAST_DEV: true,
+  },
+  pathPrefix: '/site-template',
   siteMetadata: {
-    title: 'CHANGE TITLE',
-    description: 'CHANGE DESCRIPTION',
-    products: ['CHOOSE PRODUCTS'],
-    contentType: 'CHOOSE CONTENT TYPE',
+    title: 'Site template',
+    description: 'CHANGE-ME',
+    products: ['smokeTest'],
+    contentType: 'test',
+    breadcrumbs: 'CHANGE-ME',
+    betaLink: '/beta',
+    excludeFromSearchIndex: isProd && !shouldEnableSearch,
   },
   plugins: [
-    {
-      resolve: '@commercetools-docs/gatsby-theme-docs',
-      options: {
-        websiteKey: 'change-website-key',
-      },
-    },
+    ...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',
+      ],
+    }),
   ],
 };
 ```
@@ -42,11 +64,11 @@ module.exports = {
 Now start the development server:
 
 ```console
-npm exec gatsby develop
+yarn clean:develop
 ```
 
-You will see the "404 Not Found" page of the development server because there is no page created yet.
-The Docs-Kit has automatically created the conventional folder structure for you:
+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
@@ -60,8 +82,7 @@ The Docs-Kit has automatically created the conventional folder structure for you
 
 # Start writing pages
 
-Now create a file `index.mdx` in the `src/content` folder and add some markdown content.
-This is your home page and the only file named `index`.
+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.
 
@@ -76,7 +97,3 @@ Head on to the following documentation to complete your setup and writing skills
 - [Define the navigation menu](/writing/navigation)
 - [Site and theme configuration](/configuration/theme)
 - [File and folder structure](/writing/files-folders)
-
-Of course, you also want to give your project the proper tooling and configuration that you give any Javascript project. As a minimum you should complete the `package.json` data, add a `.gitignore`, a `LICENSE` file, a `README.md`. Take a closer look at the root folder of the repository of the Docs-Kit, it has a lot more than needed in an average documentation site but you should find examples for most needs.
-
-Finally, don't forget to [deploy](/configuration/deploy).

websites/self-learning-smoke-test/gatsby-config.mjs

@@ -5,7 +5,7 @@ dotenv.config({ path: `.env.${process.env.NODE_ENV}` });
 
 const config = {
   flags: {
-    DEV_SSR: true,
+    FAST_DEV: true,
   },
   pathPrefix: '/self-learning-smoke-test',
   siteMetadata: {

websites/site-template/gatsby-config.mjs

@@ -1,9 +1,10 @@
-import {
-  configureThemeWithAddOns,
-}  from "@commercetools-docs/gatsby-theme-docs/configure-theme.mjs";
-const isProd = process.env.NODE_ENV === 'production';
+import { configureThemeWithAddOns } from '@commercetools-docs/gatsby-theme-docs/configure-theme.mjs';
 
+const isProd = process.env.NODE_ENV === 'production';
+const shouldEnableSearch = process.env.ENABLE_SEARCH === 'true';
 
+// Please update the config template in the create-new-microsite.js script when changing the config here.
+// They should always be in sync.
 
 const config = {
   flags: {
@@ -13,21 +14,34 @@ const config = {
   siteMetadata: {
     title: 'CHANGE-ME',
     description: 'CHANGE-ME',
+    products: ['smokeTest'],
+    contentType: 'test',
     breadcrumbs: 'CHANGE-ME',
-    betaLink: '',
-    excludeFromSearchIndex: isProd,
-    allowWideContentLayout: true,
-    products: ['CHANGE-ME'],
-    contentType: 'CHANGE-ME',
+    betaLink: '/beta',
+    excludeFromSearchIndex: isProd && !shouldEnableSearch,
   },
   plugins: [
     ...configureThemeWithAddOns({
-      websiteKey: 'CHANGE-ME',
-      // additionalPrismLanguages: ['java', 'scala', 'csharp', 'swift', 'php'],
-      addOns: [
-        // '@commercetools-docs/gatsby-theme-code-examples',
-        // '@commercetools-docs/gatsby-theme-api-docs'
-        // '@commercetools-docs/gatsby-theme-constants',
+      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',
       ],
     }),
   ],

websites/site-template/package.json

@@ -5,11 +5,14 @@
   "browserslist": [">0.25%", "not dead and supports es6-module"],
   "scripts": {
     "start": "yarn develop",
-    "develop": "npx gatsby develop",
+    "create-release-note": "yarn create-docs-release-note",
+    "develop": "npx gatsby develop -o",
     "serve": "npx gatsby serve --prefix-paths -o",
     "clean": "npx gatsby clean",
     "clean:develop": "yarn clean && yarn develop",
-    "build": "./scripts/build.sh"
+    "build": "./scripts/build.sh",
+    "build:serve": "yarn gatsby build --prefix-paths && yarn gatsby serve --prefix-paths -o",
+    "build:analyze": "ANALYZE_BUNDLE=true yarn build"
   },
   "dependencies": {
     "@commercetools-docs/gatsby-theme-docs": "24.9.0",

websites/site-template/src/@commercetools-docs/gatsby-theme-docs/overrides/.gitignore

@@ -0,0 +1 @@
+addon-components.js