chore: get rid of hard-coded versions from multiversion docs site

- Gatsby multiversion is quite complex
- This handles all automatically
- Fetches two previous majors's latest minors
- remove useless packages

Refs: HDS-2883

Author: mrTuomoK

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [4.X.X] - Month, XX, 202X
 
+Updated documentation build process for multi-version docs by replacing the `gatsby-source-git` setup with a local filesystem-based source and adding automatic version detection from the documentation directory structure.
+
 ### React
 
 #### Breaking
@@ -65,7 +67,6 @@ Changes that are not related to specific components
 
 #### Fixed
 
-- [Component] What bugs/typos are fixed?
 - [Checkbox] Stories to include full interactivities.
 
 ### Figma

site/.gitignore

@@ -39,3 +39,6 @@ yarn-error.log
 
 # icon&group mapping 
 icon_group.json
+
+# Local version downloads
+.previous-versions

site/gatsby-config.js

@@ -2,22 +2,93 @@ require("dotenv").config({
   path: `.env.${process.env.NODE_ENV}`,
 })
 
+const fs = require('fs');
+const path = require('path');
+
 const buildSingleVersion = process.env.BUILD_SINGLE_VERSION === 'true';
-const versionsFromGit = buildSingleVersion ? [] : require('./src/data/versionsFromGit.json');
 
-const gitSources = versionsFromGit.map(version => ({
-  resolve: 'gatsby-source-git',
-  options: {
-    name: `docs-release-${version}`,
-    remote: `https://github.com/City-of-Helsinki/helsinki-design-system`,
-    branch: `release-${version}`,
-    patterns: 'site/src/docs/**',
-  },
-}));
+// Extract version number from directory name
+function extractVersionFromDir(dir) {
+  const versionPart = dir.replace('helsinki-design-system-', '');
+  // Extract only the semantic version part (X.Y.Z)
+  // This ensures we extract just the version even if there's extra text after it
+  const match = versionPart.match(/^(\d+\.\d+\.\d+)/);
+  return match ? match[1] : null;
+}
+
+// Sort versions descending (newest first)
+function sortVersionsDesc(a, b) {
+  const aParts = a.split('.').map(Number);
+  const bParts = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (bParts[i] !== aParts[i]) return bParts[i] - aParts[i];
+  }
+  return 0;
+}
+
+// Auto-detect versions from .previous-versions directory
+function getPreviousVersions() {
+  const previousVersionsDir = path.join(__dirname, '.previous-versions');
+  if (!fs.existsSync(previousVersionsDir)) return [];
+  
+  try {
+    return fs.readdirSync(previousVersionsDir)
+      .filter(item => {
+        const itemPath = path.join(previousVersionsDir, item);
+        try {
+          return fs.statSync(itemPath).isDirectory() && item.startsWith('helsinki-design-system-');
+        } catch {
+          return false;
+        }
+      })
+      .map(extractVersionFromDir)
+      .filter(Boolean)
+      .sort(sortVersionsDesc)
+      .reduce((acc, version) => {
+        // Ensure we only keep the latest minor for each major version
+        const major = version.split('.')[0];
+        if (!acc.some(v => v.split('.')[0] === major)) {
+          acc.push(version);
+        }
+        return acc;
+      }, [])
+      .slice(0, 2); // Get latest minors from the previous two majors
+  } catch (error) {
+    console.warn('Warning: Could not read .previous-versions directory:', error.message);
+    return [];
+  }
+}
+
+const previousVersions = buildSingleVersion ? [] : getPreviousVersions();
+
+// Get current version from package.json for siteMetadata
+const packageJsonPath = path.join(__dirname, 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+const currentVersion = packageJson.version;
+
+// Create local sources using gatsby-source-filesystem
+const previousVersionSources = previousVersions.map(version => {
+  const docsPath = path.join(__dirname, `.previous-versions/helsinki-design-system-${version}/site/src/docs`);
+  
+  // Verify the path exists before adding it
+  if (fs.existsSync(docsPath)) {
+    return {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `docs-release-${version}`,
+        path: docsPath,
+      },
+    };
+  }
+  return null;
+}).filter(Boolean);
 
 module.exports = {
   pathPrefix: process.env.PATH_PREFIX,
   siteMetadata: {
+    // Include versions in siteMetadata so they're available via GraphQL
+    currentVersion,
+    previousVersions,
     title: `Helsinki Design System`,
     description: `Documentation for the Helsinki Design System`,
     siteUrl: process.env.SITE_URL,
@@ -163,7 +234,7 @@ module.exports = {
         path: `${__dirname}/src/docs`,
       },
     },
-    ...gitSources,
+    ...previousVersionSources,
     {
       resolve: `gatsby-plugin-mdx`,
       options: {

site/gatsby-node.js

@@ -1,26 +1,92 @@
 const webpack = require('webpack');
 const path = require('path');
+const fs = require('fs');
 const buildSingleVersion = process.env.BUILD_SINGLE_VERSION === 'true';
 
 exports.onCreateWebpackConfig = ({ actions, getConfig }) => {
   const config = getConfig();
 
+  // Custom resolver plugin to handle dynamic aliases for CSS imports
+  // This hooks into webpack's resolver to catch all module resolutions including CSS
+  class DynamicAliasResolverPlugin {
+    apply(resolver) {
+      // Hook into 'resolve' hook and run it with high priority (early in the chain)
+      resolver.hooks.resolve.tapAsync({
+        name: 'DynamicAliasResolverPlugin',
+        stage: 1, // Run early, before AliasPlugin (which runs at stage 10)
+      }, (request, resolveContext, callback) => {
+        // Handle ~hds-core imports (CSS/SCSS imports)
+        if (request && request.request && request.request.startsWith('~hds-core')) {
+          // Get context path - try multiple possible locations
+          const contextPath = request.context?.path || 
+                             request.path ||
+                             (resolveContext && resolveContext.issuer) ||
+                             '';
+          
+          // Normalize path separators to handle Windows and POSIX paths uniformly
+          const normalizedContextPath = contextPath.split(path.sep).join('/');
+          
+          // Extract version from context path
+          // Use word boundary or path separator to ensure complete version matching
+          const versionMatch = normalizedContextPath.match(/(?:docs-release-|helsinki-design-system-|\.previous-versions\/helsinki-design-system-)(\d+\.\d+\.\d+)(?:\/|$)/);
+          if (versionMatch) {
+            const fullVersion = versionMatch[1];
+            // Replace ~hds-core with hds-core-{version}
+            const newRequest = request.request.replace('~hds-core', `hds-core-${fullVersion}`);
+            const newRequestObj = {
+              ...request,
+              request: newRequest
+            };
+            // Continue resolution with the modified request
+            return resolver.doResolve(resolver.hooks.resolve, newRequestObj, null, resolveContext, callback);
+          }
+        }
+        // Continue with normal resolution
+        return callback();
+      });
+    }
+  }
+
   config.plugins.push(
     new webpack.NormalModuleReplacementPlugin(
-      /hds-core|hds-react/,
+      /(~?hds-core|hds-react)/,
       resource => {
-        if (resource.context.includes('.cache/gatsby-source-git/docs-release-2.')) {
-          resource.request = resource.request.replace('hds-core', 'hds-2-core');
-          resource.request = resource.request.replace('hds-react', 'hds-2-react');
+        // Skip if already versioned (prevent double replacement)
+        // Check for pattern like hds-core-X.Y.Z or hds-react-X.Y.Z
+        if (resource.request.match(/hds-(core|react)-\d+\.\d+\.\d+/)) {
+          return;
         }
-        if (resource.context.includes('.cache/gatsby-source-git/docs-release-3.')) {
-          resource.request = resource.request.replace('hds-core', 'hds-3-core');
-          resource.request = resource.request.replace('hds-react', 'hds-3-react');
+        
+        // Dynamically extract full version from path
+        // Match patterns like:
+        // - docs-release-X.Y.Z (from sourceInstanceName)
+        // - helsinki-design-system-X.Y.Z (from .previous-versions path)
+        // - .previous-versions/helsinki-design-system-X.Y.Z (full path)
+        // Normalize path separators to handle Windows and POSIX paths uniformly
+        const normalizedContext = resource.context.split(path.sep).join('/');
+        // Use word boundary or path separator to ensure complete version matching
+        const versionMatch = normalizedContext.match(/(?:docs-release-|helsinki-design-system-|\.previous-versions\/helsinki-design-system-)(\d+\.\d+\.\d+)(?:\/|$)/);
+        if (versionMatch) {
+          const fullVersion = versionMatch[1];
+          
+          // Replace ~hds-core with hds-core-{version} (remove ~)
+          if (resource.request.includes('~hds-core')) {
+            resource.request = resource.request.replace(/~hds-core/g, `hds-core-${fullVersion}`);
+          }
+          // Replace hds-core with hds-core-{version}
+          else if (resource.request.includes('hds-core')) {
+            resource.request = resource.request.replace(/hds-core(?!-\d+\.\d+\.\d+)/g, `hds-core-${fullVersion}`);
+          }
+          // Replace hds-react with hds-react-{version}
+          if (resource.request.includes('hds-react')) {
+            resource.request = resource.request.replace(/hds-react(?!-\d+\.\d+\.\d+)/g, `hds-react-${fullVersion}`);
+          }
         }
       }
     )
   );
 
+
   actions.setWebpackConfig({
     plugins: [
       // We need to provide a polyfill for react-live library to make it work with the latest Gatsby: https://webpack.js.org/blog/2020-10-10-webpack-5-release/#automatic-nodejs-polyfills-removed
@@ -32,10 +98,13 @@ exports.onCreateWebpackConfig = ({ actions, getConfig }) => {
     resolve: {
       alias: {
         fs$: path.resolve(__dirname, 'src/fs.js'),
-        '~hds-core': 'hds-2-core',
         'hds-react': 'hds-react/lib',
         stream: false,
       },
+      plugins: [
+        new DynamicAliasResolverPlugin(),
+        ...(config.resolve.plugins || []),
+      ],
       fallback: {
         crypto: require.resolve('crypto-browserify'),
       },
@@ -91,10 +160,9 @@ exports.createPages = async ({ actions, graphql }) => {
             parent {
               ... on File {
                 relativePath
+                absolutePath
                 ${!buildSingleVersion ?
-                `   gitRemote {
-                      ref
-                }` : ``}
+                `   sourceInstanceName` : ``}
               }
             }
           }
@@ -180,30 +248,78 @@ exports.createPages = async ({ actions, graphql }) => {
 
   // Create pages dynamically
   result.data.allMdx.edges.forEach(({ node }) => {
-    const gitRemote = node.parent?.gitRemote?.ref;
-    const pathWithVersion = path.join('/', gitRemote || '', node.frontmatter.slug);
+    const sourceInstanceName = node.parent?.sourceInstanceName;
+    // Extract version from sourceInstanceName (filesystem source)
+    const versionFromSource = sourceInstanceName?.startsWith('docs-release-') 
+      ? sourceInstanceName.replace('docs-release-', '')
+      : null;
+    const versionRef = versionFromSource ? `release-${versionFromSource}` : null;
+    const pathWithVersion = path.join('/', versionRef || '', node.frontmatter.slug);
 
     try {
       const pageTemplate = require.resolve('./src/components/ContentLayoutWrapper.js');
-      const contentPath = './src/docs/' + node.parent.relativePath.replace('site/src/docs/', '');
+      // Handle relativePath for both versioned sources and current docs
+      const rawRelativePath = node.parent?.relativePath || '';
+      const normalizedRelativePath = rawRelativePath.replace(/\\/g, '/');
+      const docsPrefix = 'site/src/docs/';
+      const docsRelativePath = normalizedRelativePath.includes(docsPrefix)
+        ? normalizedRelativePath.substring(normalizedRelativePath.indexOf(docsPrefix) + docsPrefix.length)
+        : normalizedRelativePath;
+      const contentPath = path.posix.join('./src/docs', docsRelativePath);
 
-      console.log('createPage() ' + (gitRemote ? gitRemote : 'latest') + ' ' + contentPath);
+      console.log('createPage() ' + (versionRef ? versionRef : 'latest') + ' ' + contentPath);
 
-      const pageContent = gitRemote
-        ? require.resolve(`./.cache/gatsby-source-git/docs-${gitRemote}/${node.parent.relativePath}`)
+      const pageContent = versionRef
+        ? (() => {
+            // For filesystem sources, use the absolutePath directly
+            const absolutePath = node.parent?.absolutePath;
+            if (absolutePath && fs.existsSync(absolutePath)) {
+              try {
+                return require.resolve(absolutePath);
+              } catch (e) {
+                console.warn(`Could not resolve absolute path ${absolutePath}: ${e.message}`);
+              }
+            }
+            // Fallback: construct path from version and docsRelativePath
+            const version = versionRef.replace('release-', '');
+            // Use the already-normalized docsRelativePath instead of node.parent.relativePath
+            // to avoid double path segments
+            const localPath = path.resolve(__dirname, `.previous-versions/helsinki-design-system-${version}/site/src/docs/${docsRelativePath}`);
+            
+            if (fs.existsSync(localPath)) {
+              try {
+                return require.resolve(localPath);
+              } catch (e) {
+                console.warn(`Could not resolve local path ${localPath}: ${e.message}`);
+              }
+            }
+            // Last resort: try contentPath (for latest docs)
+            try {
+              return require.resolve(contentPath);
+            } catch (e) {
+              console.warn(`Could not resolve any path for ${sourceInstanceName}/${node.parent.relativePath}: ${e.message}`);
+              throw e;
+            }
+          })()
         : require.resolve(contentPath);
 
       // filter out duplicate slug entries.
       const allPages = Object.values(
         Object.fromEntries(
           mdxPageData
-            .filter(({ node }) => node?.parent?.gitRemote?.ref === gitRemote)
+            .filter(({ node }) => {
+              const nodeSourceInstanceName = node?.parent?.sourceInstanceName;
+              const nodeVersionRef = nodeSourceInstanceName?.startsWith('docs-release-') 
+                ? `release-${nodeSourceInstanceName.replace('docs-release-', '')}`
+                : null;
+              return nodeVersionRef === versionRef;
+            })
             .filter(({ node }) => node.frontmatter.slug && node.frontmatter.navTitle)
             .map(({ node }) => [node.frontmatter.slug, { ...node.frontmatter, ...node.fields }])
         ),
       );
 
-      const currentMenuItem = resolveCurrentMenuItem(gitRemote, uiMenuLinks, node.frontmatter.slug);
+      const currentMenuItem = resolveCurrentMenuItem(versionRef, uiMenuLinks, node.frontmatter.slug);
       const uiSubMenuLinks = getUiSubMenuLinks(allPages, uiMenuLinks, currentMenuItem);
 
       createPage({

site/package.json

@@ -17,7 +17,6 @@
   "dependencies": {
     "@mdx-js/mdx": "2.3.0",
     "@mdx-js/react": "2.3.0",
-    "body-parser": "1.20.3",
     "gatsby": "5.13.7",
     "gatsby-plugin-image": "^3.13.1",
     "gatsby-plugin-manifest": "^5.13.1",
@@ -31,14 +30,13 @@
     "gatsby-plugin-sharp": "^5.13.1",
     "gatsby-remark-autolink-headers": "^6.13.1",
     "gatsby-source-filesystem": "^5.13.1",
-    "gatsby-source-git": "2.0.0-beta.0",
     "gatsby-transformer-remark": "6.13.1",
     "gatsby-transformer-sharp": "5.13.1",
     "html-validate": "6.5.0",
     "json5": "^2.2.3",
-    "path-to-regexp": "0.1.10",
     "prism-react-renderer": "^1.3.1",
-    "process-top": "^1.2.0",
+    "tar": "^7.4.3",
+    "extract-zip": "^2.0.1",
     "prop-types": "^15.8.1",
     "react": "18.2.0",
     "react-dom": "18.2.0",
@@ -81,7 +79,8 @@
   ],
   "license": "MIT",
   "scripts": {
-    "build": "yarn lint && NODE_OPTIONS='--max_old_space_size=8192' gatsby build",
+    "check-versions": "node scripts/check-versions.js",
+    "build": "yarn check-versions && yarn lint && NODE_OPTIONS='--max_old_space_size=8192' gatsby build",
     "build-single-version": "yarn lint && NODE_OPTIONS='--max_old_space_size=8192' BUILD_SINGLE_VERSION=true gatsby build",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\"",
     "start": "NODE_OPTIONS=--max_old_space_size=8192 BUILD_SINGLE_VERSION=true gatsby develop -o",